"`) 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}
**Section:** `DOC-DX-api-compatibility#use-supported-public-operations`.
Use the documented connection-management operations to register, update and test your own tool servers. Availability and permissions depend on the API version and deployment you use.
Document ID: `DOC-DX-api-compatibility`. Section identities and revisions.
---
# ErrorDetails {#overview}
URL: https://docs.travila.ai/api/models/error-details
Typed error details container. Concrete fields instead of Any for
type safety across languages. At most one of each detail type.
## Usage profiles {#fields}
| Usage | Fields and validation |
|---|---|
| In requests | [View fields](#request) |
| In responses | [View fields](#response) |
| In webhook payloads | [View fields](#webhook) |
## In requests {#request}
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
| `errorInfo` | [ErrorInfo](/api/models/error-info#request) | Optional | Identifies the error for machine consumption. REQUIRED on all errors per AIP-193 (enforced at Go helper level). |
| `retryInfo` | [RetryInfo](/api/models/retry-info#request) | Optional | Retry guidance for transient errors. |
| `fieldViolations` | Array of [FieldViolation](/api/models/field-violation#request) | Optional | Field-level validation failures. |
| `upstreamError` | [UpstreamError](/api/models/upstream-error#request) | Optional | Upstream provider error context. |
| `modelError` | [ModelError](/api/models/model-error#request) | Optional | Model-specific error context. |
| `helpLinks` | Array of [HelpLink](/api/models/help-link#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/error-info#response) | Optional | Identifies the error for machine consumption. REQUIRED on all errors per AIP-193 (enforced at Go helper level). |
| `retryInfo` | [RetryInfo](/api/models/retry-info#response) | Optional | Retry guidance for transient errors. |
| `fieldViolations` | Array of [FieldViolation](/api/models/field-violation#response) | Optional | Field-level validation failures. |
| `upstreamError` | [UpstreamError](/api/models/upstream-error#response) | Optional | Upstream provider error context. |
| `modelError` | [ModelError](/api/models/model-error#response) | Optional | Model-specific error context. |
| `helpLinks` | Array of [HelpLink](/api/models/help-link#response) | Optional | Help links for error resolution. |
## In webhook payloads {#webhook}
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
| `error_info` | [ErrorInfo](/api/models/error-info#webhook) | Optional | Identifies the error for machine consumption. REQUIRED on all errors per AIP-193 (enforced at Go helper level). |
| `retry_info` | [RetryInfo](/api/models/retry-info#webhook) | Optional | Retry guidance for transient errors. |
| `field_violations` | Array of [FieldViolation](/api/models/field-violation#webhook) | Optional | Field-level validation failures. |
| `upstream_error` | [UpstreamError](/api/models/upstream-error#webhook) | Optional | Upstream provider error context. |
| `model_error` | [ModelError](/api/models/model-error#webhook) | Optional | Model-specific error context. |
| `help_links` | Array of [HelpLink](/api/models/help-link#webhook) | Optional | Help links for error resolution. |
## 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` |
| [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` |
| [llm.generation_completed](/api/events/llm-generation-completed) | Webhook JSON uses protobuf field names (snake_case). |
| [RpcError](/api/models/rpc-error#response) | Nested in model |
| [RpcError](/api/models/rpc-error#request) | Nested in model |
| [RpcError](/api/models/rpc-error#webhook) | Nested in model |
Download the [public reference contract](/reference/api-contract.json).
- [conversations OpenAPI](/conversations.yaml)
Document: `DOC-API-MODEL-error-details`.
---
# ErrorInfo {#overview}
URL: https://docs.travila.ai/api/models/error-info
Machine-readable error identification (per AIP-193, every error must include this).
## Usage profiles {#fields}
| Usage | Fields and validation |
|---|---|
| In requests | [View fields](#request) |
| In responses | [View fields](#response) |
| In webhook payloads | [View fields](#webhook) |
## 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. |
## In webhook payloads {#webhook}
Webhook JSON uses protobuf field names (snake_case).
| 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 |
|---|---|
| [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` |
| [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` |
| [llm.generation_completed](/api/events/llm-generation-completed) | Webhook JSON uses protobuf field names (snake_case). |
| [ErrorDetails](/api/models/error-details#response) | Nested in model |
| [ErrorDetails](/api/models/error-details#request) | Nested in model |
| [ErrorDetails](/api/models/error-details#webhook) | Nested in model |
Download the [public reference contract](/reference/api-contract.json).
- [conversations OpenAPI](/conversations.yaml)
Document: `DOC-API-MODEL-error-info`.
---
# EventContext {#overview}
URL: https://docs.travila.ai/api/models/event-context
EventContext standardizes event envelope metadata for domain events
## Usage profiles {#fields}
| Usage | Fields and validation |
|---|---|
| In webhook payloads | [View fields](#webhook) |
## In webhook payloads {#webhook}
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
| `event_name` | `string` | Optional | Stable event name, e.g. "llm.message_published" |
| `version` | `string` | Optional | Version of the event schema (semver or simple numeric) |
| `event_id` | `string` | Optional | Unique event identifier (UUID) |
| `correlation_id` | `string` | Optional | Correlation identifier (e.g., session/workflow/conversation id) |
| `emitted_at` | `string` | Optional | RFC3339 timestamp string of when the event was emitted |
| `caller_key` | `string` | Optional | Publisher-provided routing key (e.g., conversation/thread id) |
| `metadata` | Map from string to `string` | Optional | Application-level metadata (not transport tracing headers) |
| `tenant_id` | `string` | Optional | Identifier of the tenant to which the event belongs, used to select that tenant’s webhook destinations. |
| `project_id` | `string` | Optional | Identifier of the project within the tenant that scopes the event. Defaults to default when no project is supplied. |
| `session_id` | `string` | Optional | Identifier of the end-user application session associated with the event, distinct from tenant and conversation identity. |
## Where used {#where-used}
| Reference | Relationship |
|---|---|
| [llm.generation_completed](/api/events/llm-generation-completed) | Webhook JSON uses protobuf field names (snake_case). |
| [llm.generation_started](/api/events/llm-generation-started) | Webhook JSON uses protobuf field names (snake_case). |
| [llm.message_published](/api/events/llm-message-published) | Webhook JSON uses protobuf field names (snake_case). |
| [llm.tool_call_approval_required](/api/events/llm-tool-call-approval-required) | Webhook JSON uses protobuf field names (snake_case). |
| [llm.tool_call_completed](/api/events/llm-tool-call-completed) | Webhook JSON uses protobuf field names (snake_case). |
| [llm.tool_call_started](/api/events/llm-tool-call-started) | Webhook JSON uses protobuf field names (snake_case). |
| [LLMGenerationCompletedEvent](/api/models/llm-generation-completed-event#webhook) | Nested in model |
| [LLMGenerationStartedEvent](/api/models/llm-generation-started-event#webhook) | Nested in model |
| [LLMMessagePublishedEvent](/api/models/llm-message-published-event#webhook) | Nested in model |
| [ToolCallCompletedEvent](/api/models/tool-call-completed-event#webhook) | Nested in model |
| [ToolCallStartedEvent](/api/models/tool-call-started-event#webhook) | Nested in model |
Download the [public reference contract](/reference/api-contract.json).
Document: `DOC-API-MODEL-event-context`.
---
# FieldViolation {#overview}
URL: https://docs.travila.ai/api/models/field-violation
A single field-level validation violation.
## Usage profiles {#fields}
| Usage | Fields and validation |
|---|---|
| In requests | [View fields](#request) |
| In responses | [View fields](#response) |
| In webhook payloads | [View fields](#webhook) |
## 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. |
## In webhook payloads {#webhook}
Webhook JSON uses protobuf field names (snake_case).
| 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 |
|---|---|
| [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` |
| [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` |
| [llm.generation_completed](/api/events/llm-generation-completed) | Webhook JSON uses protobuf field names (snake_case). |
| [ErrorDetails](/api/models/error-details#response) | Nested in model |
| [ErrorDetails](/api/models/error-details#request) | Nested in model |
| [ErrorDetails](/api/models/error-details#webhook) | Nested in model |
Download the [public reference contract](/reference/api-contract.json).
- [conversations OpenAPI](/conversations.yaml)
Document: `DOC-API-MODEL-field-violation`.
---
# HelpLink {#overview}
URL: https://docs.travila.ai/api/models/help-link
A help link for error resolution.
## Usage profiles {#fields}
| Usage | Fields and validation |
|---|---|
| In requests | [View fields](#request) |
| In responses | [View fields](#response) |
| In webhook payloads | [View fields](#webhook) |
## 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. |
## In webhook payloads {#webhook}
Webhook JSON uses protobuf field names (snake_case).
| 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 |
|---|---|
| [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` |
| [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` |
| [llm.generation_completed](/api/events/llm-generation-completed) | Webhook JSON uses protobuf field names (snake_case). |
| [ErrorDetails](/api/models/error-details#response) | Nested in model |
| [ErrorDetails](/api/models/error-details#request) | Nested in model |
| [ErrorDetails](/api/models/error-details#webhook) | Nested in model |
Download the [public reference contract](/reference/api-contract.json).
- [conversations OpenAPI](/conversations.yaml)
Document: `DOC-API-MODEL-help-link`.
---
# ModelError {#overview}
URL: https://docs.travila.ai/api/models/model-error
Model-specific error context.
## Usage profiles {#fields}
| Usage | Fields and validation |
|---|---|
| In requests | [View fields](#request) |
| In responses | [View fields](#response) |
| In webhook payloads | [View fields](#webhook) |
## 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. |
## In webhook payloads {#webhook}
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
| `model_id` | `string` | Optional | The model ID that caused the error. |
| `reason` | `string` | Optional | Why the model failed (e.g., "invalid", "unavailable", "moderation_flagged"). |
| `alternatives_tried` | Array of `string` | Optional | Alternative models that were tried or could be tried. |
## 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` |
| [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` |
| [llm.generation_completed](/api/events/llm-generation-completed) | Webhook JSON uses protobuf field names (snake_case). |
| [ErrorDetails](/api/models/error-details#response) | Nested in model |
| [ErrorDetails](/api/models/error-details#request) | Nested in model |
| [ErrorDetails](/api/models/error-details#webhook) | Nested in model |
Download the [public reference contract](/reference/api-contract.json).
- [conversations OpenAPI](/conversations.yaml)
Document: `DOC-API-MODEL-model-error`.
---
# RetryInfo {#overview}
URL: https://docs.travila.ai/api/models/retry-info
Retry guidance for transient errors.
## Usage profiles {#fields}
| Usage | Fields and validation |
|---|---|
| In requests | [View fields](#request) |
| In responses | [View fields](#response) |
| In webhook payloads | [View fields](#webhook) |
## 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+$. |
## In webhook payloads {#webhook}
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
| `retry_delay_ms` | `string (int64)` | Optional | Suggested minimum delay before retrying, in milliseconds. Pattern: ^-?\d+$. |
## 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` |
| [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` |
| [llm.generation_completed](/api/events/llm-generation-completed) | Webhook JSON uses protobuf field names (snake_case). |
| [ErrorDetails](/api/models/error-details#response) | Nested in model |
| [ErrorDetails](/api/models/error-details#request) | Nested in model |
| [ErrorDetails](/api/models/error-details#webhook) | Nested in model |
Download the [public reference contract](/reference/api-contract.json).
- [conversations OpenAPI](/conversations.yaml)
Document: `DOC-API-MODEL-retry-info`.
---
# RpcError {#overview}
URL: https://docs.travila.ai/api/models/rpc-error
Standardized error payload following google.rpc.Status (AIP-193).
Used across all response messages and event payloads.
## Usage profiles {#fields}
| Usage | Fields and validation |
|---|---|
| In requests | [View fields](#request) |
| In responses | [View fields](#response) |
| In webhook payloads | [View fields](#webhook) |
## 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 | 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 terminal (non-retryable). When true, repeating the same request will produce the same error. When false, transient condition may resolve on retry. |
| `details` | [ErrorDetails](/api/models/error-details#request) | Optional | Structured error details. At most one of each detail type. Follows google.rpc.Status details pattern but uses concrete types instead of google.protobuf.Any for type safety and codegen. |
### Values of `code` {#request-values-code}
Machine-readable reason that a request or operation failed; inspect the accompanying error details for context.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `ERROR_CODE_CANCELLED` | 1 | Canonical | The caller cancelled the operation before it completed. |
| `ERROR_CODE_UNKNOWN` | 2 | Canonical | The operation failed without a more specific error classification. |
| `ERROR_CODE_INVALID_ARGUMENT` | 3 | Canonical | The request contains an invalid argument or field value. |
| `ERROR_CODE_DEADLINE_EXCEEDED` | 4 | Canonical | The operation did not complete before its deadline. |
| `ERROR_CODE_NOT_FOUND` | 5 | Canonical | The requested resource does not exist or could not be found. |
| `ERROR_CODE_ALREADY_EXISTS` | 6 | Canonical | The requested creation conflicts with a resource that already exists. |
| `ERROR_CODE_PERMISSION_DENIED` | 7 | Canonical | The authenticated caller is not permitted to perform the operation. |
| `ERROR_CODE_RESOURCE_EXHAUSTED` | 8 | Canonical | A quota, rate limit or other capacity limit prevented the operation. |
| `ERROR_CODE_FAILED_PRECONDITION` | 9 | Canonical | The operation requires a system or resource state that is not currently satisfied. |
| `ERROR_CODE_ABORTED` | 10 | Canonical | The operation was aborted, for example by a concurrent modification conflict. |
| `ERROR_CODE_OUT_OF_RANGE` | 11 | Canonical | An argument is outside the range supported by this operation. |
| `ERROR_CODE_UNIMPLEMENTED` | 12 | Canonical | The requested operation is not implemented. |
| `ERROR_CODE_INTERNAL` | 13 | Canonical | An internal failure prevented the operation from completing. |
| `ERROR_CODE_UNAVAILABLE` | 14 | Canonical | The service or a required dependency is temporarily unavailable. |
| `ERROR_CODE_DATA_LOSS` | 15 | Canonical | The operation encountered unrecoverable loss or corruption of data. |
| `ERROR_CODE_UNAUTHENTICATED` | 16 | Canonical | Authentication credentials are missing or invalid. |
| `ERROR_CODE_MODEL_INVALID` | 600 | Canonical | The requested model identifier is absent from the model catalog. |
| `ERROR_CODE_MODEL_UNAVAILABLE` | 601 | Canonical | The model exists, but no provider is currently available to serve it. |
| `ERROR_CODE_MODERATION_FLAGGED` | 602 | Canonical | Content moderation flagged the submitted content. |
| `ERROR_CODE_GENERATION_FAILED` | 603 | Canonical | Model generation failed after its configured attempts. |
| `ERROR_CODE_TOOL_EXECUTION_FAILED` | 604 | Canonical | Execution of a requested tool failed. |
| `ERROR_CODE_UPSTREAM_PROVIDER` | 605 | Canonical | An upstream model provider returned an error. |
| `ERROR_CODE_VALIDATION_EXHAUSTED` | 606 | Canonical | Structured-output validation still failed after the configured attempts. |
| `ERROR_CODE_PAYMENT_REQUIRED` | 607 | Canonical | The account lacks the credits required for the operation. |
## 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 | 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 terminal (non-retryable). When true, repeating the same request will produce the same error. When false, transient condition may resolve on retry. |
| `details` | [ErrorDetails](/api/models/error-details#response) | Optional | Structured error details. At most one of each detail type. Follows google.rpc.Status details pattern but uses concrete types instead of google.protobuf.Any for type safety and codegen. |
### Values of `code` {#response-values-code}
Machine-readable reason that a request or operation failed; inspect the accompanying error details for context.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `ERROR_CODE_CANCELLED` | 1 | Canonical | The caller cancelled the operation before it completed. |
| `ERROR_CODE_UNKNOWN` | 2 | Canonical | The operation failed without a more specific error classification. |
| `ERROR_CODE_INVALID_ARGUMENT` | 3 | Canonical | The request contains an invalid argument or field value. |
| `ERROR_CODE_DEADLINE_EXCEEDED` | 4 | Canonical | The operation did not complete before its deadline. |
| `ERROR_CODE_NOT_FOUND` | 5 | Canonical | The requested resource does not exist or could not be found. |
| `ERROR_CODE_ALREADY_EXISTS` | 6 | Canonical | The requested creation conflicts with a resource that already exists. |
| `ERROR_CODE_PERMISSION_DENIED` | 7 | Canonical | The authenticated caller is not permitted to perform the operation. |
| `ERROR_CODE_RESOURCE_EXHAUSTED` | 8 | Canonical | A quota, rate limit or other capacity limit prevented the operation. |
| `ERROR_CODE_FAILED_PRECONDITION` | 9 | Canonical | The operation requires a system or resource state that is not currently satisfied. |
| `ERROR_CODE_ABORTED` | 10 | Canonical | The operation was aborted, for example by a concurrent modification conflict. |
| `ERROR_CODE_OUT_OF_RANGE` | 11 | Canonical | An argument is outside the range supported by this operation. |
| `ERROR_CODE_UNIMPLEMENTED` | 12 | Canonical | The requested operation is not implemented. |
| `ERROR_CODE_INTERNAL` | 13 | Canonical | An internal failure prevented the operation from completing. |
| `ERROR_CODE_UNAVAILABLE` | 14 | Canonical | The service or a required dependency is temporarily unavailable. |
| `ERROR_CODE_DATA_LOSS` | 15 | Canonical | The operation encountered unrecoverable loss or corruption of data. |
| `ERROR_CODE_UNAUTHENTICATED` | 16 | Canonical | Authentication credentials are missing or invalid. |
| `ERROR_CODE_MODEL_INVALID` | 600 | Canonical | The requested model identifier is absent from the model catalog. |
| `ERROR_CODE_MODEL_UNAVAILABLE` | 601 | Canonical | The model exists, but no provider is currently available to serve it. |
| `ERROR_CODE_MODERATION_FLAGGED` | 602 | Canonical | Content moderation flagged the submitted content. |
| `ERROR_CODE_GENERATION_FAILED` | 603 | Canonical | Model generation failed after its configured attempts. |
| `ERROR_CODE_TOOL_EXECUTION_FAILED` | 604 | Canonical | Execution of a requested tool failed. |
| `ERROR_CODE_UPSTREAM_PROVIDER` | 605 | Canonical | An upstream model provider returned an error. |
| `ERROR_CODE_VALIDATION_EXHAUSTED` | 606 | Canonical | Structured-output validation still failed after the configured attempts. |
| `ERROR_CODE_PAYMENT_REQUIRED` | 607 | Canonical | The account lacks the credits required for the operation. |
## In webhook payloads {#webhook}
Webhook JSON uses protobuf field names (snake_case).
| 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 | 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. |
| `is_terminal` | `boolean` | Optional | Whether this error is terminal (non-retryable). When true, repeating the same request will produce the same error. When false, transient condition may resolve on retry. |
| `details` | [ErrorDetails](/api/models/error-details#webhook) | Optional | Structured error details. At most one of each detail type. Follows google.rpc.Status details pattern but uses concrete types instead of google.protobuf.Any for type safety and codegen. |
### Values of `code` {#webhook-values-code}
Machine-readable reason that a request or operation failed; inspect the accompanying error details for context.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `ERROR_CODE_CANCELLED` | 1 | Canonical | The caller cancelled the operation before it completed. |
| `ERROR_CODE_UNKNOWN` | 2 | Canonical | The operation failed without a more specific error classification. |
| `ERROR_CODE_INVALID_ARGUMENT` | 3 | Canonical | The request contains an invalid argument or field value. |
| `ERROR_CODE_DEADLINE_EXCEEDED` | 4 | Canonical | The operation did not complete before its deadline. |
| `ERROR_CODE_NOT_FOUND` | 5 | Canonical | The requested resource does not exist or could not be found. |
| `ERROR_CODE_ALREADY_EXISTS` | 6 | Canonical | The requested creation conflicts with a resource that already exists. |
| `ERROR_CODE_PERMISSION_DENIED` | 7 | Canonical | The authenticated caller is not permitted to perform the operation. |
| `ERROR_CODE_RESOURCE_EXHAUSTED` | 8 | Canonical | A quota, rate limit or other capacity limit prevented the operation. |
| `ERROR_CODE_FAILED_PRECONDITION` | 9 | Canonical | The operation requires a system or resource state that is not currently satisfied. |
| `ERROR_CODE_ABORTED` | 10 | Canonical | The operation was aborted, for example by a concurrent modification conflict. |
| `ERROR_CODE_OUT_OF_RANGE` | 11 | Canonical | An argument is outside the range supported by this operation. |
| `ERROR_CODE_UNIMPLEMENTED` | 12 | Canonical | The requested operation is not implemented. |
| `ERROR_CODE_INTERNAL` | 13 | Canonical | An internal failure prevented the operation from completing. |
| `ERROR_CODE_UNAVAILABLE` | 14 | Canonical | The service or a required dependency is temporarily unavailable. |
| `ERROR_CODE_DATA_LOSS` | 15 | Canonical | The operation encountered unrecoverable loss or corruption of data. |
| `ERROR_CODE_UNAUTHENTICATED` | 16 | Canonical | Authentication credentials are missing or invalid. |
| `ERROR_CODE_MODEL_INVALID` | 600 | Canonical | The requested model identifier is absent from the model catalog. |
| `ERROR_CODE_MODEL_UNAVAILABLE` | 601 | Canonical | The model exists, but no provider is currently available to serve it. |
| `ERROR_CODE_MODERATION_FLAGGED` | 602 | Canonical | Content moderation flagged the submitted content. |
| `ERROR_CODE_GENERATION_FAILED` | 603 | Canonical | Model generation failed after its configured attempts. |
| `ERROR_CODE_TOOL_EXECUTION_FAILED` | 604 | Canonical | Execution of a requested tool failed. |
| `ERROR_CODE_UPSTREAM_PROVIDER` | 605 | Canonical | An upstream model provider returned an error. |
| `ERROR_CODE_VALIDATION_EXHAUSTED` | 606 | Canonical | Structured-output validation still failed after the configured attempts. |
| `ERROR_CODE_PAYMENT_REQUIRED` | 607 | Canonical | The account lacks the credits required for the operation. |
## 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` |
| [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` |
| [llm.generation_completed](/api/events/llm-generation-completed) | Webhook JSON uses protobuf field names (snake_case). |
| [ClientToolResult](/api/models/client-tool-result#request) | Nested in model |
| [LLMGenerationCompletedEvent](/api/models/llm-generation-completed-event#webhook) | Nested in model |
Download the [public reference contract](/reference/api-contract.json).
- [conversations OpenAPI](/conversations.yaml)
Document: `DOC-API-MODEL-rpc-error`.
---
# UpstreamError {#overview}
URL: https://docs.travila.ai/api/models/upstream-error
Context from an upstream provider error.
## Usage profiles {#fields}
| Usage | Fields and validation |
|---|---|
| In requests | [View fields](#request) |
| In responses | [View fields](#response) |
| In webhook payloads | [View fields](#webhook) |
## 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` | `integer (int32)` | Optional | HTTP status code returned by the provider. Minimum: -2147483648. Maximum: 2147483647. |
| `rawBody` | `string` | Optional | Raw error body from the provider. Truncated to 512 bytes (enforced at Go level). |
## 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` | `integer (int32)` | Optional | HTTP status code returned by the provider. Minimum: -2147483648. Maximum: 2147483647. |
| `rawBody` | `string` | Optional | Raw error body from the provider. Truncated to 512 bytes (enforced at Go level). |
## In webhook payloads {#webhook}
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
| `provider` | `string` | Optional | Name of the upstream provider that reported the error. |
| `status_code` | `integer (int32)` | Optional | HTTP status code returned by the provider. Minimum: -2147483648. Maximum: 2147483647. |
| `raw_body` | `string` | Optional | Raw error body from the provider. Truncated to 512 bytes (enforced at Go level). |
## 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` |
| [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` |
| [llm.generation_completed](/api/events/llm-generation-completed) | Webhook JSON uses protobuf field names (snake_case). |
| [ErrorDetails](/api/models/error-details#response) | Nested in model |
| [ErrorDetails](/api/models/error-details#request) | Nested in model |
| [ErrorDetails](/api/models/error-details#webhook) | Nested in model |
Download the [public reference contract](/reference/api-contract.json).
- [conversations OpenAPI](/conversations.yaml)
Document: `DOC-API-MODEL-upstream-error`.
---
# Shared API types {#overview}
URL: https://docs.travila.ai/api/shared-types
These support types provide event identity and structured errors where the linked operations and events use them. They are not a universal HTTP error envelope: an error from another operation, authentication layer or upstream can have a different body.
## Support types and actual uses {#support-types}
| Type | Used by |
|---|---|
| [ErrorDetails](/api/models/error-details) | [Send a message and wait for the result](/api/conversations/send-message-sync); [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync); [Submit client-side tool execution results](/api/conversations/submit-client-tool-results); [llm.generation_completed](/api/events/llm-generation-completed) |
| [ErrorInfo](/api/models/error-info) | [Send a message and wait for the result](/api/conversations/send-message-sync); [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync); [Submit client-side tool execution results](/api/conversations/submit-client-tool-results); [llm.generation_completed](/api/events/llm-generation-completed) |
| [EventContext](/api/models/event-context) | [llm.generation_completed](/api/events/llm-generation-completed); [llm.generation_started](/api/events/llm-generation-started); [llm.message_published](/api/events/llm-message-published); [llm.tool_call_approval_required](/api/events/llm-tool-call-approval-required); [llm.tool_call_completed](/api/events/llm-tool-call-completed); [llm.tool_call_started](/api/events/llm-tool-call-started) |
| [FieldViolation](/api/models/field-violation) | [Send a message and wait for the result](/api/conversations/send-message-sync); [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync); [Submit client-side tool execution results](/api/conversations/submit-client-tool-results); [llm.generation_completed](/api/events/llm-generation-completed) |
| [HelpLink](/api/models/help-link) | [Send a message and wait for the result](/api/conversations/send-message-sync); [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync); [Submit client-side tool execution results](/api/conversations/submit-client-tool-results); [llm.generation_completed](/api/events/llm-generation-completed) |
| [ModelError](/api/models/model-error) | [Send a message and wait for the result](/api/conversations/send-message-sync); [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync); [Submit client-side tool execution results](/api/conversations/submit-client-tool-results); [llm.generation_completed](/api/events/llm-generation-completed) |
| [RetryInfo](/api/models/retry-info) | [Send a message and wait for the result](/api/conversations/send-message-sync); [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync); [Submit client-side tool execution results](/api/conversations/submit-client-tool-results); [llm.generation_completed](/api/events/llm-generation-completed) |
| [RpcError](/api/models/rpc-error) | [Send a message and wait for the result](/api/conversations/send-message-sync); [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync); [Submit client-side tool execution results](/api/conversations/submit-client-tool-results); [llm.generation_completed](/api/events/llm-generation-completed) |
| [UpstreamError](/api/models/upstream-error) | [Send a message and wait for the result](/api/conversations/send-message-sync); [Submit client-side tool results and wait for the next segment](/api/conversations/submit-client-tool-results-sync); [Submit client-side tool execution results](/api/conversations/submit-client-tool-results); [llm.generation_completed](/api/events/llm-generation-completed) |
## Models reused across APIs {#reused-domain-models}
Reusable domain models stay with their owning capability. The following types are reached by operations in more than one API bundle; their pages show the exact operation and payload profiles.
| Model | API bundles |
|---|---|
| [Backoff](/api/models/backoff) | [agent-profiles](/api/agent-profiles); [conversations](/api/conversations); [end-users](/api/end-users) |
| [FileResolutionConfig](/api/models/file-resolution-config) | [agent-profiles](/api/agent-profiles); [conversations](/api/conversations); [end-users](/api/end-users) |
| [GenerationConfig](/api/models/generation-config) | [agent-profiles](/api/agent-profiles); [conversations](/api/conversations); [end-users](/api/end-users) |
| [MCPServerReference](/api/models/mcp-server-reference) | [agent-profiles](/api/agent-profiles); [conversations](/api/conversations) |
| [MemoryConfig](/api/models/memory-config) | [agent-profiles](/api/agent-profiles); [conversations](/api/conversations); [end-users](/api/end-users) |
| [ModelRoutingFilter](/api/models/model-routing-filter) | [agent-profiles](/api/agent-profiles); [conversations](/api/conversations); [end-users](/api/end-users) |
| [PercentileThreshold](/api/models/percentile-threshold) | [agent-profiles](/api/agent-profiles); [conversations](/api/conversations); [end-users](/api/end-users) |
| [PluginConfig](/api/models/plugin-config) | [agent-profiles](/api/agent-profiles); [conversations](/api/conversations); [end-users](/api/end-users) |
| [PluginPDFConfig](/api/models/plugin-pdf-config) | [agent-profiles](/api/agent-profiles); [conversations](/api/conversations); [end-users](/api/end-users) |
| [PluginWebConfig](/api/models/plugin-web-config) | [agent-profiles](/api/agent-profiles); [conversations](/api/conversations); [end-users](/api/end-users) |
| [ProviderMaxPrice](/api/models/provider-max-price) | [agent-profiles](/api/agent-profiles); [conversations](/api/conversations); [end-users](/api/end-users) |
| [ProviderPreferences](/api/models/provider-preferences) | [agent-profiles](/api/agent-profiles); [conversations](/api/conversations); [end-users](/api/end-users) |
| [ReasoningOptions](/api/models/reasoning-options) | [agent-profiles](/api/agent-profiles); [conversations](/api/conversations); [end-users](/api/end-users) |
| [ResponseFormat](/api/models/response-format) | [agent-profiles](/api/agent-profiles); [conversations](/api/conversations); [end-users](/api/end-users) |
| [StopOnFailureRule](/api/models/stop-on-failure-rule) | [agent-profiles](/api/agent-profiles); [conversations](/api/conversations); [end-users](/api/end-users) |
| [TimeAwareConfig](/api/models/time-aware-config) | [agent-profiles](/api/agent-profiles); [conversations](/api/conversations); [end-users](/api/end-users) |
| [TimeoutPolicy](/api/models/timeout-policy) | [agent-profiles](/api/agent-profiles); [conversations](/api/conversations); [end-users](/api/end-users) |
| [ToolChoice](/api/models/tool-choice) | [agent-profiles](/api/agent-profiles); [conversations](/api/conversations); [end-users](/api/end-users) |
| [ToolDefinition](/api/models/tool-definition) | [agent-profiles](/api/agent-profiles); [conversations](/api/conversations); [end-users](/api/end-users) |
| [ToolExecutionOrderRule](/api/models/tool-execution-order-rule) | [agent-profiles](/api/agent-profiles); [conversations](/api/conversations); [end-users](/api/end-users) |
| [ToolExecutionPolicy](/api/models/tool-execution-policy) | [agent-profiles](/api/agent-profiles); [conversations](/api/conversations); [end-users](/api/end-users) |
| [TurnContextConfig](/api/models/turn-context-config) | [agent-profiles](/api/agent-profiles); [conversations](/api/conversations); [end-users](/api/end-users) |
| [UsageOptions](/api/models/usage-options) | [agent-profiles](/api/agent-profiles); [conversations](/api/conversations); [end-users](/api/end-users) |
| [WebSearchOptions](/api/models/web-search-options) | [agent-profiles](/api/agent-profiles); [conversations](/api/conversations); [end-users](/api/end-users) |
See the [event catalog](/api/events) for outgoing payloads and the [API reference](/api) for operation-specific request and response bodies.
Document: `DOC-API-shared-types`.
---
# 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.
## 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.
**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 dataset item or annotation queue item being addressed.
#### 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).
- Overview: `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/annotation-queue-item#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.
## 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 dataset item or annotation queue item being addressed.
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/annotation-queue-item#response).
**itemId** `string`
Identifier of the dataset or annotation queue item.
**queueId** `string`
Identifier of the annotation queue.
**objectId** `string`
Identifier of the evaluation object addressed by the comment or queue item.
**objectType** `any`
Kind of evaluation object addressed by the comment or annotation queue item.
Kind of evaluation object a score or evaluation configuration addresses.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `EVAL_TARGET_TYPE_TRACE` | 1 | Canonical | A complete trace identified by its trace identifier. |
| `EVAL_TARGET_TYPE_OBSERVATION` | 2 | Canonical | A specific observation within a trace. |
| `EVAL_TARGET_TYPE_DATASET_RUN` | 3 | Canonical | An evaluation run over a dataset. |
| `EVAL_TARGET_TYPE_SESSION` | 4 | Canonical | A session grouping multiple traces; session scores are attached directly by the harness. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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` | 1 | Canonical | The item is waiting for its annotation to be completed. |
| `ANNOTATION_QUEUE_ITEM_STATUS_COMPLETED` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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).
- Overview: `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.
## 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, or used to filter, the evaluation record.
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).
- Overview: `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.
## 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` | 1 | Canonical | Attach the comment to a trace. |
| `COMMENT_OBJECT_TYPE_OBSERVATION` | 2 | Canonical | Attach the comment to a particular observation. |
| `COMMENT_OBJECT_TYPE_SESSION` | 3 | Canonical | Attach the comment to a session. |
| `COMMENT_OBJECT_TYPE_PROMPT` | 4 | 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: `1`, `2`, `3`, `4`
Must not match:
Type: `any`
Enum: `0`
**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).
- Overview: `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.
## 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, or used to filter, the evaluation record.
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).
- Overview: `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.
## 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, or used to filter, the evaluation record.
Minimum length: 1
**dataType** `any` **required**
Value type used to interpret the evaluation score.
Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_DATA_TYPE_NUMERIC` | 1 | Canonical | A numeric measurement or rating. |
| `SCORE_DATA_TYPE_CATEGORICAL` | 2 | Canonical | A value chosen from a named set of categories. |
| `SCORE_DATA_TYPE_BOOLEAN` | 3 | Canonical | A true-or-false evaluation result. |
| `SCORE_DATA_TYPE_TEXT` | 4 | Canonical | Free-form text supplied by an evaluator or reviewer. |
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: `1`, `2`, `3`, `4`
Must not match:
Type: `any`
Enum: `0`
**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).
- Overview: `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`
Deletes one comment by id.
## 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).
- Overview: `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.
## 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).
- Overview: `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.
## 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 targeted by the score or annotation.
Kind of evaluation object a score or evaluation configuration addresses.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `EVAL_TARGET_TYPE_TRACE` | 1 | Canonical | A complete trace identified by its trace identifier. |
| `EVAL_TARGET_TYPE_OBSERVATION` | 2 | Canonical | A specific observation within a trace. |
| `EVAL_TARGET_TYPE_DATASET_RUN` | 3 | Canonical | An evaluation run over a dataset. |
| `EVAL_TARGET_TYPE_SESSION` | 4 | Canonical | A session grouping multiple traces; session scores are attached directly by the harness. |
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: `1`, `2`, `3`, `4`
Must not match:
Type: `any`
Enum: `0`
**targetId** `string` **required**
Identifier of the evaluation object targeted by the score or annotation.
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).
- Overview: `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: `1.0.0`
Read traces and scores, curate datasets, and register evaluation runs. These are evaluation and observability operations.
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](/core-platform/identity-access/authentication).
### 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. Run registration does not execute a dataset or validate gold-answer eligibility.
### 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
`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](/insights/evaluation)
### 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](/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. See record-dataset-run for limitations on associating traces after they have been recorded.
## Authentication {#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.
Security scheme type: `apiKey`
Parameter location: `header`
Parameter name: `X-API-Key`
## Operations
- [Add a dataset item](/api/evals/add-dataset-item) — `POST /api/v1/evals/add-dataset-item`
- [Complete an annotation queue item](/api/evals/complete-annotation-queue-item) — `POST /api/v1/evals/complete-annotation-queue-item`
- [Create an annotation queue](/api/evals/create-annotation-queue) — `POST /api/v1/evals/create-annotation-queue`
- [Create a comment](/api/evals/create-comment) — `POST /api/v1/evals/create-comment`
- [Create a dataset](/api/evals/create-dataset) — `POST /api/v1/evals/create-dataset`
- [Create a score config](/api/evals/create-score-config) — `POST /api/v1/evals/create-score-config`
- [Delete a comment](/api/evals/delete-comment) — `POST /api/v1/evals/delete-comment`
- [Delete a score](/api/evals/delete-score) — `POST /api/v1/evals/delete-score`
- [Enqueue an item for annotation](/api/evals/enqueue-for-annotation) — `POST /api/v1/evals/enqueue-for-annotation`
- [Get a dataset run](/api/evals/get-dataset-run) — `POST /api/v1/evals/get-dataset-run`
- [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 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 dataset runs](/api/evals/list-dataset-runs) — `POST /api/v1/evals/list-dataset-runs`
- [List datasets](/api/evals/list-datasets) — `POST /api/v1/evals/list-datasets`
- [List observations](/api/evals/list-observations) — `POST /api/v1/evals/list-observations`
- [List score configs](/api/evals/list-score-configs) — `POST /api/v1/evals/list-score-configs`
- [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`
- [Record a dataset run](/api/evals/record-dataset-run) — `POST /api/v1/evals/record-dataset-run`
- [Record a score](/api/evals/record-score) — `POST /api/v1/evals/record-score`
- [Update a dataset item](/api/evals/update-dataset-item) — `POST /api/v1/evals/update-dataset-item`
- [Update a score config](/api/evals/update-score-config) — `POST /api/v1/evals/update-score-config`
Document ID: `DOC-IS-evaluation-api-overview`. [Section identities and revisions](/documentation-manifest.json).
- Overview: `DOC-IS-evaluation-api-overview#overview`
- Field naming: `DOC-IS-evaluation-api-overview#field-naming`
- Authentication: `DOC-IS-evaluation-api-overview#authentication`
- Projects: `DOC-IS-evaluation-api-overview#projects`
- Current API limits: `DOC-IS-evaluation-api-overview#current-adapter-limits`
- Pagination: `DOC-IS-evaluation-api-overview#pagination`
- Reading responses: `DOC-IS-evaluation-api-overview#reading-responses`
---
# 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.
## 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/dataset-run#response).
**runId** `string`
Identifier of the dataset or candidate evaluation 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** `integer(int32)`
Number of dataset items reported for the dataset or run.
Minimum: -2147483648
Maximum: 2147483647
**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).
- Overview: `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.
## 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/eval-overview#response).
**totalTraces** `string(int64)`
Total trace count reported for the selected evaluation window.
Pattern: ^-?\d+$
**tracesByName** `array[NamedCount]`
Trace counts grouped by trace name.
Count of evaluation records grouped under a shared label.
Model reference: [NamedCount](/api/models/named-count#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[TimeSeriesPoint]`
Trace counts grouped into time buckets.
Numeric evaluation measurement associated with a time bucket and series.
Model reference: [TimeSeriesPoint](/api/models/time-series-point#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[TimeSeriesPoint]`
Observation counts grouped by reported log level.
Numeric evaluation measurement associated with a time bucket and series.
Model reference: [TimeSeriesPoint](/api/models/time-series-point#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[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/score-aggregate#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 preserves its original vocabulary.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_SOURCE_JUDGE` | 1 | Canonical | A score produced by an automated judge. |
| `SCORE_SOURCE_HUMAN` | 2 | Canonical | A score entered by a human reviewer through the annotation path. |
| `SCORE_SOURCE_USER` | 3 | Canonical | Feedback supplied by an end user. |
| `SCORE_SOURCE_HARNESS` | 4 | Canonical | A score written by an evaluation harness or another API-based producer. |
| `SCORE_SOURCE_EVAL` | 5 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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[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/time-series-point#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[ProfileQualityRow]`
Evaluation metrics grouped by agent profile.
Aggregated evaluation results and usage for one agent profile.
Model reference: [ProfileQualityRow](/api/models/profile-quality-row#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[LatencyPercentileRow]`
Latency percentile summaries grouped by trace name.
Latency percentiles aggregated for one evaluation trace name.
Model reference: [LatencyPercentileRow](/api/models/latency-percentile-row#response).
**traceName** `string`
Display name used to group or identify the evaluation trace.
**p50** `any`
50th-percentile latency reported for the trace group.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**p90** `any`
90th-percentile latency reported for the trace group.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**p95** `any`
95th-percentile latency reported for the trace group.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**p99** `any`
99th-percentile latency reported for the trace group.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**recentLowScores** `array[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/score#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` | 1 | Canonical | A complete trace identified by its trace identifier. |
| `EVAL_TARGET_TYPE_OBSERVATION` | 2 | Canonical | A specific observation within a trace. |
| `EVAL_TARGET_TYPE_DATASET_RUN` | 3 | Canonical | An evaluation run over a dataset. |
| `EVAL_TARGET_TYPE_SESSION` | 4 | Canonical | A session grouping multiple traces; session scores are attached directly by the harness. |
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)`
Must not match:
Type: `any`
Enum: `0`
**targetId** `string`
Identifier of the evaluation object to which the score applies.
**name** `string`
Metric name identifying the recorded evaluation score.
**dataType** `any`
Score value type used to interpret the numeric, categorical, or boolean value.
Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_DATA_TYPE_NUMERIC` | 1 | Canonical | A numeric measurement or rating. |
| `SCORE_DATA_TYPE_CATEGORICAL` | 2 | Canonical | A value chosen from a named set of categories. |
| `SCORE_DATA_TYPE_BOOLEAN` | 3 | Canonical | A true-or-false evaluation result. |
| `SCORE_DATA_TYPE_TEXT` | 4 | Canonical | Free-form text supplied by an evaluator or reviewer. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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`
String operand or score value used by the selected evaluation type.
**booleanValue** `boolean`
Boolean operand or score value used by the selected evaluation type.
**source** `any`
Source classification reported for the evaluation score.
Platform classification of who produced an evaluation score; the provider source label preserves its original vocabulary.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_SOURCE_JUDGE` | 1 | Canonical | A score produced by an automated judge. |
| `SCORE_SOURCE_HUMAN` | 2 | Canonical | A score entered by a human reviewer through the annotation path. |
| `SCORE_SOURCE_USER` | 3 | Canonical | Feedback supplied by an end user. |
| `SCORE_SOURCE_HARNESS` | 4 | Canonical | A score written by an evaluation harness or another API-based producer. |
| `SCORE_SOURCE_EVAL` | 5 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**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 conversation message or event.
**traceName** `string`
Denormalised for the Scores table's Trace Name column, which would
otherwise need one trace read per row.
**userId** `string`
Identifier of the user associated with the operation.
**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).
- 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.
## 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/session-detail#response).
**summary** `any`
Summary information for the evaluation trace or session.
All of:
Variant 1:
Aggregated trace, usage, and score information for an evaluation session.
Model reference: [SessionSummary](/api/models/session-summary#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]`
Identifiers of the users selected by the operation.
Type: `string`
**traceCount** `integer(int32)`
Number of traces represented by this summary or group.
Minimum: -2147483648
Maximum: 2147483647
**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[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/score#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` | 1 | Canonical | A complete trace identified by its trace identifier. |
| `EVAL_TARGET_TYPE_OBSERVATION` | 2 | Canonical | A specific observation within a trace. |
| `EVAL_TARGET_TYPE_DATASET_RUN` | 3 | Canonical | An evaluation run over a dataset. |
| `EVAL_TARGET_TYPE_SESSION` | 4 | Canonical | A session grouping multiple traces; session scores are attached directly by the harness. |
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)`
Must not match:
Type: `any`
Enum: `0`
**targetId** `string`
Identifier of the evaluation object to which the score applies.
**name** `string`
Metric name identifying the recorded evaluation score.
**dataType** `any`
Score value type used to interpret the numeric, categorical, or boolean value.
Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_DATA_TYPE_NUMERIC` | 1 | Canonical | A numeric measurement or rating. |
| `SCORE_DATA_TYPE_CATEGORICAL` | 2 | Canonical | A value chosen from a named set of categories. |
| `SCORE_DATA_TYPE_BOOLEAN` | 3 | Canonical | A true-or-false evaluation result. |
| `SCORE_DATA_TYPE_TEXT` | 4 | Canonical | Free-form text supplied by an evaluator or reviewer. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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`
String operand or score value used by the selected evaluation type.
**booleanValue** `boolean`
Boolean operand or score value used by the selected evaluation type.
**source** `any`
Source classification reported for the evaluation score.
Platform classification of who produced an evaluation score; the provider source label preserves its original vocabulary.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_SOURCE_JUDGE` | 1 | Canonical | A score produced by an automated judge. |
| `SCORE_SOURCE_HUMAN` | 2 | Canonical | A score entered by a human reviewer through the annotation path. |
| `SCORE_SOURCE_USER` | 3 | Canonical | Feedback supplied by an end user. |
| `SCORE_SOURCE_HARNESS` | 4 | Canonical | A score written by an evaluation harness or another API-based producer. |
| `SCORE_SOURCE_EVAL` | 5 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**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 conversation message or event.
**traceName** `string`
Denormalised for the Scores table's Trace Name column, which would
otherwise need one trace read per row.
**userId** `string`
Identifier of the user associated with the operation.
**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** `integer(int32)`
Number of comments reported on the evaluation object.
Minimum: -2147483648
Maximum: 2147483647
**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[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/trace-summary#response).
**traceId** `string`
Identifier of the evaluation trace.
**name** `string`
Name recorded for the evaluation trace.
**timestamp** `string(date-time)`
Timestamp associated with the conversation message or event.
**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** `integer(int32)`
Number of observations reported for the evaluation object.
Minimum: -2147483648
Maximum: 2147483647
**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** `integer(int32)`
Number of observations reported at error level.
Minimum: -2147483648
Maximum: 2147483647
**warningCount** `integer(int32)`
Number of observations reported at warning level.
Minimum: -2147483648
Maximum: 2147483647
**defaultCount** `integer(int32)`
Number of observations reported at the default level.
Minimum: -2147483648
Maximum: 2147483647
**debugCount** `integer(int32)`
Number of observations reported at debug level.
Minimum: -2147483648
Maximum: 2147483647
**scores** `array[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/score#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` | 1 | Canonical | A complete trace identified by its trace identifier. |
| `EVAL_TARGET_TYPE_OBSERVATION` | 2 | Canonical | A specific observation within a trace. |
| `EVAL_TARGET_TYPE_DATASET_RUN` | 3 | Canonical | An evaluation run over a dataset. |
| `EVAL_TARGET_TYPE_SESSION` | 4 | Canonical | A session grouping multiple traces; session scores are attached directly by the harness. |
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)`
Must not match:
Type: `any`
Enum: `0`
**targetId** `string`
Identifier of the evaluation object to which the score applies.
**name** `string`
Metric name identifying the recorded evaluation score.
**dataType** `any`
Score value type used to interpret the numeric, categorical, or boolean value.
Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_DATA_TYPE_NUMERIC` | 1 | Canonical | A numeric measurement or rating. |
| `SCORE_DATA_TYPE_CATEGORICAL` | 2 | Canonical | A value chosen from a named set of categories. |
| `SCORE_DATA_TYPE_BOOLEAN` | 3 | Canonical | A true-or-false evaluation result. |
| `SCORE_DATA_TYPE_TEXT` | 4 | Canonical | Free-form text supplied by an evaluator or reviewer. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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`
String operand or score value used by the selected evaluation type.
**booleanValue** `boolean`
Boolean operand or score value used by the selected evaluation type.
**source** `any`
Source classification reported for the evaluation score.
Platform classification of who produced an evaluation score; the provider source label preserves its original vocabulary.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_SOURCE_JUDGE` | 1 | Canonical | A score produced by an automated judge. |
| `SCORE_SOURCE_HUMAN` | 2 | Canonical | A score entered by a human reviewer through the annotation path. |
| `SCORE_SOURCE_USER` | 3 | Canonical | Feedback supplied by an end user. |
| `SCORE_SOURCE_HARNESS` | 4 | Canonical | A score written by an evaluation harness or another API-based producer. |
| `SCORE_SOURCE_EVAL` | 5 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**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 conversation message or event.
**traceName** `string`
Denormalised for the Scores table's Trace Name column, which would
otherwise need one trace read per row.
**userId** `string`
Identifier of the user associated with the operation.
**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** `integer(int32)`
Number of comments reported on the evaluation object.
Minimum: -2147483648
Maximum: 2147483647
**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).
- Overview: `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.
## 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/trace-detail#response).
**summary** `any`
Summary information for the evaluation trace or session.
All of:
Variant 1:
Evaluation summary for a conversation turn, including its recorded conversation, message and
profile attribution.
Model reference: [TraceSummary](/api/models/trace-summary#response).
**traceId** `string`
Identifier of the evaluation trace.
**name** `string`
Name recorded for the evaluation trace.
**timestamp** `string(date-time)`
Timestamp associated with the conversation message or event.
**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** `integer(int32)`
Number of observations reported for the evaluation object.
Minimum: -2147483648
Maximum: 2147483647
**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** `integer(int32)`
Number of observations reported at error level.
Minimum: -2147483648
Maximum: 2147483647
**warningCount** `integer(int32)`
Number of observations reported at warning level.
Minimum: -2147483648
Maximum: 2147483647
**defaultCount** `integer(int32)`
Number of observations reported at the default level.
Minimum: -2147483648
Maximum: 2147483647
**debugCount** `integer(int32)`
Number of observations reported at debug level.
Minimum: -2147483648
Maximum: 2147483647
**scores** `array[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/score#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` | 1 | Canonical | A complete trace identified by its trace identifier. |
| `EVAL_TARGET_TYPE_OBSERVATION` | 2 | Canonical | A specific observation within a trace. |
| `EVAL_TARGET_TYPE_DATASET_RUN` | 3 | Canonical | An evaluation run over a dataset. |
| `EVAL_TARGET_TYPE_SESSION` | 4 | Canonical | A session grouping multiple traces; session scores are attached directly by the harness. |
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)`
Must not match:
Type: `any`
Enum: `0`
**targetId** `string`
Identifier of the evaluation object to which the score applies.
**name** `string`
Metric name identifying the recorded evaluation score.
**dataType** `any`
Score value type used to interpret the numeric, categorical, or boolean value.
Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_DATA_TYPE_NUMERIC` | 1 | Canonical | A numeric measurement or rating. |
| `SCORE_DATA_TYPE_CATEGORICAL` | 2 | Canonical | A value chosen from a named set of categories. |
| `SCORE_DATA_TYPE_BOOLEAN` | 3 | Canonical | A true-or-false evaluation result. |
| `SCORE_DATA_TYPE_TEXT` | 4 | Canonical | Free-form text supplied by an evaluator or reviewer. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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`
String operand or score value used by the selected evaluation type.
**booleanValue** `boolean`
Boolean operand or score value used by the selected evaluation type.
**source** `any`
Source classification reported for the evaluation score.
Platform classification of who produced an evaluation score; the provider source label preserves its original vocabulary.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_SOURCE_JUDGE` | 1 | Canonical | A score produced by an automated judge. |
| `SCORE_SOURCE_HUMAN` | 2 | Canonical | A score entered by a human reviewer through the annotation path. |
| `SCORE_SOURCE_USER` | 3 | Canonical | Feedback supplied by an end user. |
| `SCORE_SOURCE_HARNESS` | 4 | Canonical | A score written by an evaluation harness or another API-based producer. |
| `SCORE_SOURCE_EVAL` | 5 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**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 conversation message or event.
**traceName** `string`
Denormalised for the Scores table's Trace Name column, which would
otherwise need one trace read per row.
**userId** `string`
Identifier of the user associated with the operation.
**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** `integer(int32)`
Number of comments reported on the evaluation object.
Minimum: -2147483648
Maximum: 2147483647
**observations** `array[Observation]`
Observations associated with the trace or returned by the query.
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/observation#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.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `OBSERVATION_TYPE_SPAN` | 1 | Canonical | A timed unit of work represented as a span. |
| `OBSERVATION_TYPE_GENERATION` | 2 | Canonical | A model-generation operation and its recorded inputs, outputs and usage. |
| `OBSERVATION_TYPE_EVENT` | 3 | Canonical | A point-in-time event rather than a timed operation. |
| `OBSERVATION_TYPE_TOOL` | 4 | Canonical | Execution of a tool call. |
| `OBSERVATION_TYPE_RETRIEVER` | 5 | Canonical | Retrieval of supporting documents or other context. |
| `OBSERVATION_TYPE_AGENT` | 6 | Canonical | An agent-level operation reported in the trace. |
| `OBSERVATION_TYPE_CHAIN` | 7 | Canonical | A sequence or chain of related processing steps. |
| `OBSERVATION_TYPE_EMBEDDING` | 8 | Canonical | Computation of vector embeddings. |
| `OBSERVATION_TYPE_EVALUATOR` | 9 | Canonical | An evaluator operation that assesses another result. |
| `OBSERVATION_TYPE_GUARDRAIL` | 10 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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` | 1 | Canonical | Detailed diagnostic information intended for debugging. |
| `OBSERVATION_LEVEL_DEFAULT` | 2 | Canonical | Ordinary observation information without an elevated warning or error level. |
| `OBSERVATION_LEVEL_WARNING` | 3 | Canonical | A condition reported at warning severity. |
| `OBSERVATION_LEVEL_ERROR` | 4 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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** `integer(int32)`
Version of the prompt associated with the generation.
Minimum: -2147483648
Maximum: 2147483647
**scores** `array[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/score#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` | 1 | Canonical | A complete trace identified by its trace identifier. |
| `EVAL_TARGET_TYPE_OBSERVATION` | 2 | Canonical | A specific observation within a trace. |
| `EVAL_TARGET_TYPE_DATASET_RUN` | 3 | Canonical | An evaluation run over a dataset. |
| `EVAL_TARGET_TYPE_SESSION` | 4 | Canonical | A session grouping multiple traces; session scores are attached directly by the harness. |
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)`
Must not match:
Type: `any`
Enum: `0`
**targetId** `string`
Identifier of the evaluation object to which the score applies.
**name** `string`
Metric name identifying the recorded evaluation score.
**dataType** `any`
Score value type used to interpret the numeric, categorical, or boolean value.
Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_DATA_TYPE_NUMERIC` | 1 | Canonical | A numeric measurement or rating. |
| `SCORE_DATA_TYPE_CATEGORICAL` | 2 | Canonical | A value chosen from a named set of categories. |
| `SCORE_DATA_TYPE_BOOLEAN` | 3 | Canonical | A true-or-false evaluation result. |
| `SCORE_DATA_TYPE_TEXT` | 4 | Canonical | Free-form text supplied by an evaluator or reviewer. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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`
String operand or score value used by the selected evaluation type.
**booleanValue** `boolean`
Boolean operand or score value used by the selected evaluation type.
**source** `any`
Source classification reported for the evaluation score.
Platform classification of who produced an evaluation score; the provider source label preserves its original vocabulary.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_SOURCE_JUDGE` | 1 | Canonical | A score produced by an automated judge. |
| `SCORE_SOURCE_HUMAN` | 2 | Canonical | A score entered by a human reviewer through the annotation path. |
| `SCORE_SOURCE_USER` | 3 | Canonical | Feedback supplied by an end user. |
| `SCORE_SOURCE_HARNESS` | 4 | Canonical | A score written by an evaluation harness or another API-based producer. |
| `SCORE_SOURCE_EVAL` | 5 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**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 conversation message or event.
**traceName** `string`
Denormalised for the Scores table's Trace Name column, which would
otherwise need one trace read per row.
**userId** `string`
Identifier of the user associated with the operation.
**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** `integer(int32)`
Number of comments reported on the evaluation object.
Minimum: -2147483648
Maximum: 2147483647
**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[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/score#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` | 1 | Canonical | A complete trace identified by its trace identifier. |
| `EVAL_TARGET_TYPE_OBSERVATION` | 2 | Canonical | A specific observation within a trace. |
| `EVAL_TARGET_TYPE_DATASET_RUN` | 3 | Canonical | An evaluation run over a dataset. |
| `EVAL_TARGET_TYPE_SESSION` | 4 | Canonical | A session grouping multiple traces; session scores are attached directly by the harness. |
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)`
Must not match:
Type: `any`
Enum: `0`
**targetId** `string`
Identifier of the evaluation object to which the score applies.
**name** `string`
Metric name identifying the recorded evaluation score.
**dataType** `any`
Score value type used to interpret the numeric, categorical, or boolean value.
Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_DATA_TYPE_NUMERIC` | 1 | Canonical | A numeric measurement or rating. |
| `SCORE_DATA_TYPE_CATEGORICAL` | 2 | Canonical | A value chosen from a named set of categories. |
| `SCORE_DATA_TYPE_BOOLEAN` | 3 | Canonical | A true-or-false evaluation result. |
| `SCORE_DATA_TYPE_TEXT` | 4 | Canonical | Free-form text supplied by an evaluator or reviewer. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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`
String operand or score value used by the selected evaluation type.
**booleanValue** `boolean`
Boolean operand or score value used by the selected evaluation type.
**source** `any`
Source classification reported for the evaluation score.
Platform classification of who produced an evaluation score; the provider source label preserves its original vocabulary.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_SOURCE_JUDGE` | 1 | Canonical | A score produced by an automated judge. |
| `SCORE_SOURCE_HUMAN` | 2 | Canonical | A score entered by a human reviewer through the annotation path. |
| `SCORE_SOURCE_USER` | 3 | Canonical | Feedback supplied by an end user. |
| `SCORE_SOURCE_HARNESS` | 4 | Canonical | A score written by an evaluation harness or another API-based producer. |
| `SCORE_SOURCE_EVAL` | 5 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**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 conversation message or event.
**traceName** `string`
Denormalised for the Scores table's Trace Name column, which would
otherwise need one trace read per row.
**userId** `string`
Identifier of the user associated with the operation.
**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).
- Overview: `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/annotation-queue-item#response-field-objectid) to [get-trace](/api/evals/get-trace). Other target kinds need their matching read operation.
## 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** `integer(int32)`
Page number requested from the backing service.
Minimum: 0
Maximum: 2147483647
**pageSize** `integer(int32)`
Requested maximum number of entries in a result page.
Minimum: 0
Maximum: 100
**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` | 1 | Canonical | The item is waiting for its annotation to be completed. |
| `ANNOTATION_QUEUE_ITEM_STATUS_COMPLETED` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
#### 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[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/annotation-queue-item#response).
**itemId** `string`
Identifier of the dataset or annotation queue item.
**queueId** `string`
Identifier of the annotation queue.
**objectId** `string`
Identifier of the evaluation object addressed by the comment or queue item.
**objectType** `any`
Kind of evaluation object addressed by the comment or annotation queue item.
Kind of evaluation object a score or evaluation configuration addresses.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `EVAL_TARGET_TYPE_TRACE` | 1 | Canonical | A complete trace identified by its trace identifier. |
| `EVAL_TARGET_TYPE_OBSERVATION` | 2 | Canonical | A specific observation within a trace. |
| `EVAL_TARGET_TYPE_DATASET_RUN` | 3 | Canonical | An evaluation run over a dataset. |
| `EVAL_TARGET_TYPE_SESSION` | 4 | Canonical | A session grouping multiple traces; session scores are attached directly by the harness. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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` | 1 | Canonical | The item is waiting for its annotation to be completed. |
| `ANNOTATION_QUEUE_ITEM_STATUS_COMPLETED` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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:
Offset-pagination position, page size and result totals.
Model reference: [EvaluationPageInfo](/api/models/evaluation-page-info#response).
**page** `integer(int32)`
One-based page number.
Minimum: -2147483648
Maximum: 2147483647
**limit** `integer(int32)`
Maximum number of entries requested from the listing.
Minimum: -2147483648
Maximum: 2147483647
**totalItems** `integer(int32)`
Total item count reported for the selected dataset query.
Minimum: -2147483648
Maximum: 2147483647
**totalPages** `integer(int32)`
Total number of pages reported for the current query.
Minimum: -2147483648
Maximum: 2147483647
#### 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).
- Overview: `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.
## 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** `integer(int32)`
Page number requested from the backing service.
Minimum: 0
Maximum: 2147483647
**pageSize** `integer(int32)`
Requested maximum number of entries in a result page.
Minimum: 0
Maximum: 100
#### 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[AnnotationQueue]`
Evaluation annotation queues included in this result page.
Named work queue assigning score configurations to human annotation items.
Model reference: [AnnotationQueue](/api/models/annotation-queue#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** `integer(int32)`
Number of queue items awaiting annotation.
Minimum: -2147483648
Maximum: 2147483647
**completedCount** `integer(int32)`
Number of queue items reported completed.
Minimum: -2147483648
Maximum: 2147483647
**page** `any`
Page number, page size, and result totals returned by the evaluation provider.
All of:
Variant 1:
Offset-pagination position, page size and result totals.
Model reference: [EvaluationPageInfo](/api/models/evaluation-page-info#response).
**page** `integer(int32)`
One-based page number.
Minimum: -2147483648
Maximum: 2147483647
**limit** `integer(int32)`
Maximum number of entries requested from the listing.
Minimum: -2147483648
Maximum: 2147483647
**totalItems** `integer(int32)`
Total item count reported for the selected dataset query.
Minimum: -2147483648
Maximum: 2147483647
**totalPages** `integer(int32)`
Total number of pages reported for the current query.
Minimum: -2147483648
Maximum: 2147483647
#### 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).
- Overview: `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.
## 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` | 1 | Canonical | Attach the comment to a trace. |
| `COMMENT_OBJECT_TYPE_OBSERVATION` | 2 | Canonical | Attach the comment to a particular observation. |
| `COMMENT_OBJECT_TYPE_SESSION` | 3 | Canonical | Attach the comment to a session. |
| `COMMENT_OBJECT_TYPE_PROMPT` | 4 | 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)`
Must not match:
Type: `any`
Enum: `0`
**objectId** `string`
Identifier of the evaluation object to which the comment belongs.
**page** `integer(int32)`
Page number requested from the backing service.
Minimum: 0
Maximum: 2147483647
**pageSize** `integer(int32)`
Requested maximum number of entries in a result page.
Minimum: 0
Maximum: 100
#### 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[Comment]`
Evaluation comments included in this result page.
Authored text attached to a trace, observation, or other evaluation object.
Model reference: [Comment](/api/models/comment#response).
**commentId** `string`
Identifier of the evaluation comment.
**objectType** `any`
Kind of evaluation object addressed by the comment or annotation queue item.
Kind of evaluation object to which a reviewer comment is attached.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `COMMENT_OBJECT_TYPE_TRACE` | 1 | Canonical | Attach the comment to a trace. |
| `COMMENT_OBJECT_TYPE_OBSERVATION` | 2 | Canonical | Attach the comment to a particular observation. |
| `COMMENT_OBJECT_TYPE_SESSION` | 3 | Canonical | Attach the comment to a session. |
| `COMMENT_OBJECT_TYPE_PROMPT` | 4 | 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)`
Must not match:
Type: `any`
Enum: `0`
**objectId** `string`
Identifier of the evaluation object addressed by the comment or queue item.
**content** `string`
Text content of the evaluation comment.
**authorUserId** `string`
Identifier recorded for the user who authored the comment.
**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:
Offset-pagination position, page size and result totals.
Model reference: [EvaluationPageInfo](/api/models/evaluation-page-info#response).
**page** `integer(int32)`
One-based page number.
Minimum: -2147483648
Maximum: 2147483647
**limit** `integer(int32)`
Maximum number of entries requested from the listing.
Minimum: -2147483648
Maximum: 2147483647
**totalItems** `integer(int32)`
Total item count reported for the selected dataset query.
Minimum: -2147483648
Maximum: 2147483647
**totalPages** `integer(int32)`
Total number of pages reported for the current query.
Minimum: -2147483648
Maximum: 2147483647
#### 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).
- Overview: `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.
## 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** `integer(int32)`
Page number requested from the backing service.
Minimum: 0
Maximum: 2147483647
**pageSize** `integer(int32)`
Requested maximum number of entries in a result page.
Minimum: 0
Maximum: 100
**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[DatasetItem]`
Evaluation dataset items in this page.
One evaluation input with its expected output and source trace references.
Model reference: [DatasetItem](/api/models/dataset-item#response).
**itemId** `string`
Identifier of the dataset or annotation queue 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` | 1 | Canonical | The dataset item is active. |
| `DATASET_ITEM_STATUS_ARCHIVED` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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:
Offset-pagination position, page size and result totals.
Model reference: [EvaluationPageInfo](/api/models/evaluation-page-info#response).
**page** `integer(int32)`
One-based page number.
Minimum: -2147483648
Maximum: 2147483647
**limit** `integer(int32)`
Maximum number of entries requested from the listing.
Minimum: -2147483648
Maximum: 2147483647
**totalItems** `integer(int32)`
Total item count reported for the selected dataset query.
Minimum: -2147483648
Maximum: 2147483647
**totalPages** `integer(int32)`
Total number of pages reported for the current query.
Minimum: -2147483648
Maximum: 2147483647
#### 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).
- Overview: `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.
## 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** `integer(int32)`
Requested maximum number of entries in a result page.
Minimum: 0
Maximum: 100
**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[DatasetRun]`
Evaluation dataset runs included in this result page.
Metadata describing one execution of an evaluation dataset.
Model reference: [DatasetRun](/api/models/dataset-run#response).
**runId** `string`
Identifier of the dataset or candidate evaluation 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** `integer(int32)`
Number of dataset items reported for the dataset or run.
Minimum: -2147483648
Maximum: 2147483647
**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/cursor-page-info#response).
**nextCursor** `string`
Pass back as the request's `cursor` for the next page. Empty on the last
page.
**limit** `integer(int32)`
Maximum number of entries requested from the listing.
Minimum: -2147483648
Maximum: 2147483647
**totalItems** `integer(int32)`
Total number of matching items when it can be counted exactly. Absent when the selected
filters do not support an exact total.
Minimum: -2147483648
Maximum: 2147483647
#### 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).
- Overview: `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.
## Authentication
Required:
- API Key via `X-API-Key` header parameter
## Request Body
*Required*
Content type: `application/json`
Inputs for listing evaluation datasets.
**page** `integer(int32)`
Page number requested from the backing service.
Minimum: 0
Maximum: 2147483647
**pageSize** `integer(int32)`
Requested maximum number of entries in a result page.
Minimum: 0
Maximum: 100
#### 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[Dataset]`
Evaluation datasets included in this result page.
Evaluation dataset metadata, item counts, run history, and input/output schemas.
Model reference: [Dataset](/api/models/dataset#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** `integer(int32)`
Number of dataset items reported for the dataset or run.
Minimum: -2147483648
Maximum: 2147483647
**runCount** `integer(int32)`
Number of runs reported for the evaluation dataset.
Minimum: -2147483648
Maximum: 2147483647
**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:
Offset-pagination position, page size and result totals.
Model reference: [EvaluationPageInfo](/api/models/evaluation-page-info#response).
**page** `integer(int32)`
One-based page number.
Minimum: -2147483648
Maximum: 2147483647
**limit** `integer(int32)`
Maximum number of entries requested from the listing.
Minimum: -2147483648
Maximum: 2147483647
**totalItems** `integer(int32)`
Total item count reported for the selected dataset query.
Minimum: -2147483648
Maximum: 2147483647
**totalPages** `integer(int32)`
Total number of pages reported for the current query.
Minimum: -2147483648
Maximum: 2147483647
#### 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).
- Overview: `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.
## 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** `integer(int32)`
Requested maximum number of entries in a result page.
Minimum: 0
Maximum: 100
**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.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `OBSERVATION_TYPE_SPAN` | 1 | Canonical | A timed unit of work represented as a span. |
| `OBSERVATION_TYPE_GENERATION` | 2 | Canonical | A model-generation operation and its recorded inputs, outputs and usage. |
| `OBSERVATION_TYPE_EVENT` | 3 | Canonical | A point-in-time event rather than a timed operation. |
| `OBSERVATION_TYPE_TOOL` | 4 | Canonical | Execution of a tool call. |
| `OBSERVATION_TYPE_RETRIEVER` | 5 | Canonical | Retrieval of supporting documents or other context. |
| `OBSERVATION_TYPE_AGENT` | 6 | Canonical | An agent-level operation reported in the trace. |
| `OBSERVATION_TYPE_CHAIN` | 7 | Canonical | A sequence or chain of related processing steps. |
| `OBSERVATION_TYPE_EMBEDDING` | 8 | Canonical | Computation of vector embeddings. |
| `OBSERVATION_TYPE_EVALUATOR` | 9 | Canonical | An evaluator operation that assesses another result. |
| `OBSERVATION_TYPE_GUARDRAIL` | 10 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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` | 1 | Canonical | Detailed diagnostic information intended for debugging. |
| `OBSERVATION_LEVEL_DEFAULT` | 2 | Canonical | Ordinary observation information without an elevated warning or error level. |
| `OBSERVATION_LEVEL_WARNING` | 3 | Canonical | A condition reported at warning severity. |
| `OBSERVATION_LEVEL_ERROR` | 4 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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[EvalFilter]`
Structured filters applied to the evaluation record query.
Typed comparison operand and column selector for querying evaluation-provider records.
Model reference: [EvalFilter](/api/models/eval-filter#request).
**type** `any` **required**
Discriminator selecting the evaluation filter’s operand type.
Operand shape and comparison vocabulary for an evaluation-record filter.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `EVAL_FILTER_TYPE_DATETIME` | 1 | Canonical | Compare a date-time value using ordered comparisons. |
| `EVAL_FILTER_TYPE_STRING` | 2 | Canonical | Compare text using equality or supported substring and prefix or suffix operators. |
| `EVAL_FILTER_TYPE_NUMBER` | 3 | Canonical | Compare a numeric value using equality or ordered comparisons. |
| `EVAL_FILTER_TYPE_STRING_OPTIONS` | 4 | Canonical | Match a string against a set of allowed or excluded choices. |
| `EVAL_FILTER_TYPE_CATEGORY_OPTIONS` | 5 | Canonical | Match a category against a set of allowed or excluded choices. |
| `EVAL_FILTER_TYPE_ARRAY_OPTIONS` | 6 | Canonical | Match array contents using any-of, none-of or all-of selection. |
| `EVAL_FILTER_TYPE_BOOLEAN` | 7 | Canonical | Compare a boolean value for equality or inequality. |
| `EVAL_FILTER_TYPE_NULL` | 8 | Canonical | Test whether the selected property is null or non-null. |
| `EVAL_FILTER_TYPE_STRING_OBJECT` | 9 | Canonical | Compare a string-valued member identified by a key, such as a metadata property. |
| `EVAL_FILTER_TYPE_NUMBER_OBJECT` | 10 | Canonical | Compare a numeric member identified by a key, such as a named score. |
| `EVAL_FILTER_TYPE_BOOLEAN_OBJECT` | 11 | Canonical | Compare a boolean member identified by a key. |
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: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`
Must not match:
Type: `any`
Enum: `0`
**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`
Exactly one value field is meaningful, chosen by type — flat siblings
rather than a oneof, per repo convention.
**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 or score value used by the selected evaluation type.
**stringValues** `array[string]`
The *_OPTIONS 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[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/observation#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.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `OBSERVATION_TYPE_SPAN` | 1 | Canonical | A timed unit of work represented as a span. |
| `OBSERVATION_TYPE_GENERATION` | 2 | Canonical | A model-generation operation and its recorded inputs, outputs and usage. |
| `OBSERVATION_TYPE_EVENT` | 3 | Canonical | A point-in-time event rather than a timed operation. |
| `OBSERVATION_TYPE_TOOL` | 4 | Canonical | Execution of a tool call. |
| `OBSERVATION_TYPE_RETRIEVER` | 5 | Canonical | Retrieval of supporting documents or other context. |
| `OBSERVATION_TYPE_AGENT` | 6 | Canonical | An agent-level operation reported in the trace. |
| `OBSERVATION_TYPE_CHAIN` | 7 | Canonical | A sequence or chain of related processing steps. |
| `OBSERVATION_TYPE_EMBEDDING` | 8 | Canonical | Computation of vector embeddings. |
| `OBSERVATION_TYPE_EVALUATOR` | 9 | Canonical | An evaluator operation that assesses another result. |
| `OBSERVATION_TYPE_GUARDRAIL` | 10 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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` | 1 | Canonical | Detailed diagnostic information intended for debugging. |
| `OBSERVATION_LEVEL_DEFAULT` | 2 | Canonical | Ordinary observation information without an elevated warning or error level. |
| `OBSERVATION_LEVEL_WARNING` | 3 | Canonical | A condition reported at warning severity. |
| `OBSERVATION_LEVEL_ERROR` | 4 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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** `integer(int32)`
Version of the prompt associated with the generation.
Minimum: -2147483648
Maximum: 2147483647
**scores** `array[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/score#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` | 1 | Canonical | A complete trace identified by its trace identifier. |
| `EVAL_TARGET_TYPE_OBSERVATION` | 2 | Canonical | A specific observation within a trace. |
| `EVAL_TARGET_TYPE_DATASET_RUN` | 3 | Canonical | An evaluation run over a dataset. |
| `EVAL_TARGET_TYPE_SESSION` | 4 | Canonical | A session grouping multiple traces; session scores are attached directly by the harness. |
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)`
Must not match:
Type: `any`
Enum: `0`
**targetId** `string`
Identifier of the evaluation object to which the score applies.
**name** `string`
Metric name identifying the recorded evaluation score.
**dataType** `any`
Score value type used to interpret the numeric, categorical, or boolean value.
Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_DATA_TYPE_NUMERIC` | 1 | Canonical | A numeric measurement or rating. |
| `SCORE_DATA_TYPE_CATEGORICAL` | 2 | Canonical | A value chosen from a named set of categories. |
| `SCORE_DATA_TYPE_BOOLEAN` | 3 | Canonical | A true-or-false evaluation result. |
| `SCORE_DATA_TYPE_TEXT` | 4 | Canonical | Free-form text supplied by an evaluator or reviewer. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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`
String operand or score value used by the selected evaluation type.
**booleanValue** `boolean`
Boolean operand or score value used by the selected evaluation type.
**source** `any`
Source classification reported for the evaluation score.
Platform classification of who produced an evaluation score; the provider source label preserves its original vocabulary.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_SOURCE_JUDGE` | 1 | Canonical | A score produced by an automated judge. |
| `SCORE_SOURCE_HUMAN` | 2 | Canonical | A score entered by a human reviewer through the annotation path. |
| `SCORE_SOURCE_USER` | 3 | Canonical | Feedback supplied by an end user. |
| `SCORE_SOURCE_HARNESS` | 4 | Canonical | A score written by an evaluation harness or another API-based producer. |
| `SCORE_SOURCE_EVAL` | 5 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**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 conversation message or event.
**traceName** `string`
Denormalised for the Scores table's Trace Name column, which would
otherwise need one trace read per row.
**userId** `string`
Identifier of the user associated with the operation.
**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** `integer(int32)`
Number of comments reported on the evaluation object.
Minimum: -2147483648
Maximum: 2147483647
**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/cursor-page-info#response).
**nextCursor** `string`
Pass back as the request's `cursor` for the next page. Empty on the last
page.
**limit** `integer(int32)`
Maximum number of entries requested from the listing.
Minimum: -2147483648
Maximum: 2147483647
**totalItems** `integer(int32)`
Total number of matching items when it can be counted exactly. Absent when the selected
filters do not support an exact total.
Minimum: -2147483648
Maximum: 2147483647
#### 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).
- Overview: `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.
## 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** `integer(int32)`
Page number requested from the backing service.
Minimum: 0
Maximum: 2147483647
**pageSize** `integer(int32)`
Requested maximum number of entries in a result page.
Minimum: 0
Maximum: 100
**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[ScoreConfig]`
Evaluation score configurations included in this result page.
Score definition specifying its value type, bounds, and allowed categories.
Model reference: [ScoreConfig](/api/models/score-config#response).
**configId** `string`
Identifier of the score configuration defining the score’s value domain.
**name** `string`
Name identifying the score definition.
**dataType** `any`
Score value type used to interpret the numeric, categorical, or boolean value.
Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_DATA_TYPE_NUMERIC` | 1 | Canonical | A numeric measurement or rating. |
| `SCORE_DATA_TYPE_CATEGORICAL` | 2 | Canonical | A value chosen from a named set of categories. |
| `SCORE_DATA_TYPE_BOOLEAN` | 3 | Canonical | A true-or-false evaluation result. |
| `SCORE_DATA_TYPE_TEXT` | 4 | Canonical | Free-form text supplied by an evaluator or reviewer. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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[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/score-config-category#response).
**label** `string`
Label identifying the prompt version or 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:
Offset-pagination position, page size and result totals.
Model reference: [EvaluationPageInfo](/api/models/evaluation-page-info#response).
**page** `integer(int32)`
One-based page number.
Minimum: -2147483648
Maximum: 2147483647
**limit** `integer(int32)`
Maximum number of entries requested from the listing.
Minimum: -2147483648
Maximum: 2147483647
**totalItems** `integer(int32)`
Total item count reported for the selected dataset query.
Minimum: -2147483648
Maximum: 2147483647
**totalPages** `integer(int32)`
Total number of pages reported for the current query.
Minimum: -2147483648
Maximum: 2147483647
#### 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).
- Overview: `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.
## 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** `integer(int32)`
Requested maximum number of entries in a result page.
Minimum: 0
Maximum: 100
**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` | 1 | Canonical | A complete trace identified by its trace identifier. |
| `EVAL_TARGET_TYPE_OBSERVATION` | 2 | Canonical | A specific observation within a trace. |
| `EVAL_TARGET_TYPE_DATASET_RUN` | 3 | Canonical | An evaluation run over a dataset. |
| `EVAL_TARGET_TYPE_SESSION` | 4 | Canonical | A session grouping multiple traces; session scores are attached directly by the harness. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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 preserves its original vocabulary.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_SOURCE_JUDGE` | 1 | Canonical | A score produced by an automated judge. |
| `SCORE_SOURCE_HUMAN` | 2 | Canonical | A score entered by a human reviewer through the annotation path. |
| `SCORE_SOURCE_USER` | 3 | Canonical | Feedback supplied by an end user. |
| `SCORE_SOURCE_HARNESS` | 4 | Canonical | A score written by an evaluation harness or another API-based producer. |
| `SCORE_SOURCE_EVAL` | 5 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_DATA_TYPE_NUMERIC` | 1 | Canonical | A numeric measurement or rating. |
| `SCORE_DATA_TYPE_CATEGORICAL` | 2 | Canonical | A value chosen from a named set of categories. |
| `SCORE_DATA_TYPE_BOOLEAN` | 3 | Canonical | A true-or-false evaluation result. |
| `SCORE_DATA_TYPE_TEXT` | 4 | Canonical | Free-form text supplied by an evaluator or reviewer. |
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)`
Must not match:
Type: `any`
Enum: `0`
**traceId** `string`
Identifier of the evaluation trace.
**filters** `array[EvalFilter]`
Structured filters applied to the evaluation record query.
Typed comparison operand and column selector for querying evaluation-provider records.
Model reference: [EvalFilter](/api/models/eval-filter#request).
**type** `any` **required**
Discriminator selecting the evaluation filter’s operand type.
Operand shape and comparison vocabulary for an evaluation-record filter.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `EVAL_FILTER_TYPE_DATETIME` | 1 | Canonical | Compare a date-time value using ordered comparisons. |
| `EVAL_FILTER_TYPE_STRING` | 2 | Canonical | Compare text using equality or supported substring and prefix or suffix operators. |
| `EVAL_FILTER_TYPE_NUMBER` | 3 | Canonical | Compare a numeric value using equality or ordered comparisons. |
| `EVAL_FILTER_TYPE_STRING_OPTIONS` | 4 | Canonical | Match a string against a set of allowed or excluded choices. |
| `EVAL_FILTER_TYPE_CATEGORY_OPTIONS` | 5 | Canonical | Match a category against a set of allowed or excluded choices. |
| `EVAL_FILTER_TYPE_ARRAY_OPTIONS` | 6 | Canonical | Match array contents using any-of, none-of or all-of selection. |
| `EVAL_FILTER_TYPE_BOOLEAN` | 7 | Canonical | Compare a boolean value for equality or inequality. |
| `EVAL_FILTER_TYPE_NULL` | 8 | Canonical | Test whether the selected property is null or non-null. |
| `EVAL_FILTER_TYPE_STRING_OBJECT` | 9 | Canonical | Compare a string-valued member identified by a key, such as a metadata property. |
| `EVAL_FILTER_TYPE_NUMBER_OBJECT` | 10 | Canonical | Compare a numeric member identified by a key, such as a named score. |
| `EVAL_FILTER_TYPE_BOOLEAN_OBJECT` | 11 | Canonical | Compare a boolean member identified by a key. |
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: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`
Must not match:
Type: `any`
Enum: `0`
**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`
Exactly one value field is meaningful, chosen by type — flat siblings
rather than a oneof, per repo convention.
**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 or score value used by the selected evaluation type.
**stringValues** `array[string]`
The *_OPTIONS 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[Score]`
Evaluation scores included in this result page.
Evaluation score with its value, source, target identity, and generation attribution.
Model reference: [Score](/api/models/score#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` | 1 | Canonical | A complete trace identified by its trace identifier. |
| `EVAL_TARGET_TYPE_OBSERVATION` | 2 | Canonical | A specific observation within a trace. |
| `EVAL_TARGET_TYPE_DATASET_RUN` | 3 | Canonical | An evaluation run over a dataset. |
| `EVAL_TARGET_TYPE_SESSION` | 4 | Canonical | A session grouping multiple traces; session scores are attached directly by the harness. |
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)`
Must not match:
Type: `any`
Enum: `0`
**targetId** `string`
Identifier of the evaluation object to which the score applies.
**name** `string`
Metric name identifying the recorded evaluation score.
**dataType** `any`
Score value type used to interpret the numeric, categorical, or boolean value.
Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_DATA_TYPE_NUMERIC` | 1 | Canonical | A numeric measurement or rating. |
| `SCORE_DATA_TYPE_CATEGORICAL` | 2 | Canonical | A value chosen from a named set of categories. |
| `SCORE_DATA_TYPE_BOOLEAN` | 3 | Canonical | A true-or-false evaluation result. |
| `SCORE_DATA_TYPE_TEXT` | 4 | Canonical | Free-form text supplied by an evaluator or reviewer. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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`
String operand or score value used by the selected evaluation type.
**booleanValue** `boolean`
Boolean operand or score value used by the selected evaluation type.
**source** `any`
Source classification reported for the evaluation score.
Platform classification of who produced an evaluation score; the provider source label preserves its original vocabulary.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_SOURCE_JUDGE` | 1 | Canonical | A score produced by an automated judge. |
| `SCORE_SOURCE_HUMAN` | 2 | Canonical | A score entered by a human reviewer through the annotation path. |
| `SCORE_SOURCE_USER` | 3 | Canonical | Feedback supplied by an end user. |
| `SCORE_SOURCE_HARNESS` | 4 | Canonical | A score written by an evaluation harness or another API-based producer. |
| `SCORE_SOURCE_EVAL` | 5 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**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 conversation message or event.
**traceName** `string`
Denormalised for the Scores table's Trace Name column, which would
otherwise need one trace read per row.
**userId** `string`
Identifier of the user associated with the operation.
**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/cursor-page-info#response).
**nextCursor** `string`
Pass back as the request's `cursor` for the next page. Empty on the last
page.
**limit** `integer(int32)`
Maximum number of entries requested from the listing.
Minimum: -2147483648
Maximum: 2147483647
**totalItems** `integer(int32)`
Total number of matching items when it can be counted exactly. Absent when the selected
filters do not support an exact total.
Minimum: -2147483648
Maximum: 2147483647
#### 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).
- Overview: `DOC-IS-evaluation-api-listScores#overview`
- Request: `DOC-IS-evaluation-api-listScores#request`
- Responses: `DOC-IS-evaluation-api-listScores#responses`
- Filtering by what the rating is about: `DOC-IS-evaluation-api-listScores#filtering-by-what-the-rating-is-about`
- Reading the result honestly: `DOC-IS-evaluation-api-listScores#reading-the-result-honestly`
---
# 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.
## 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** `integer(int32)`
Requested maximum number of entries in a result page.
Minimum: 0
Maximum: 100
**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[EvalFilter]`
Structured filters applied to the evaluation record query.
Typed comparison operand and column selector for querying evaluation-provider records.
Model reference: [EvalFilter](/api/models/eval-filter#request).
**type** `any` **required**
Discriminator selecting the evaluation filter’s operand type.
Operand shape and comparison vocabulary for an evaluation-record filter.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `EVAL_FILTER_TYPE_DATETIME` | 1 | Canonical | Compare a date-time value using ordered comparisons. |
| `EVAL_FILTER_TYPE_STRING` | 2 | Canonical | Compare text using equality or supported substring and prefix or suffix operators. |
| `EVAL_FILTER_TYPE_NUMBER` | 3 | Canonical | Compare a numeric value using equality or ordered comparisons. |
| `EVAL_FILTER_TYPE_STRING_OPTIONS` | 4 | Canonical | Match a string against a set of allowed or excluded choices. |
| `EVAL_FILTER_TYPE_CATEGORY_OPTIONS` | 5 | Canonical | Match a category against a set of allowed or excluded choices. |
| `EVAL_FILTER_TYPE_ARRAY_OPTIONS` | 6 | Canonical | Match array contents using any-of, none-of or all-of selection. |
| `EVAL_FILTER_TYPE_BOOLEAN` | 7 | Canonical | Compare a boolean value for equality or inequality. |
| `EVAL_FILTER_TYPE_NULL` | 8 | Canonical | Test whether the selected property is null or non-null. |
| `EVAL_FILTER_TYPE_STRING_OBJECT` | 9 | Canonical | Compare a string-valued member identified by a key, such as a metadata property. |
| `EVAL_FILTER_TYPE_NUMBER_OBJECT` | 10 | Canonical | Compare a numeric member identified by a key, such as a named score. |
| `EVAL_FILTER_TYPE_BOOLEAN_OBJECT` | 11 | Canonical | Compare a boolean member identified by a key. |
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: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`
Must not match:
Type: `any`
Enum: `0`
**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`
Exactly one value field is meaningful, chosen by type — flat siblings
rather than a oneof, per repo convention.
**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 or score value used by the selected evaluation type.
**stringValues** `array[string]`
The *_OPTIONS 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[SessionSummary]`
Evaluation session summaries included in this result page.
Aggregated trace, usage, and score information for an evaluation session.
Model reference: [SessionSummary](/api/models/session-summary#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]`
Identifiers of the users selected by the operation.
Type: `string`
**traceCount** `integer(int32)`
Number of traces represented by this summary or group.
Minimum: -2147483648
Maximum: 2147483647
**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[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/score#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` | 1 | Canonical | A complete trace identified by its trace identifier. |
| `EVAL_TARGET_TYPE_OBSERVATION` | 2 | Canonical | A specific observation within a trace. |
| `EVAL_TARGET_TYPE_DATASET_RUN` | 3 | Canonical | An evaluation run over a dataset. |
| `EVAL_TARGET_TYPE_SESSION` | 4 | Canonical | A session grouping multiple traces; session scores are attached directly by the harness. |
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)`
Must not match:
Type: `any`
Enum: `0`
**targetId** `string`
Identifier of the evaluation object to which the score applies.
**name** `string`
Metric name identifying the recorded evaluation score.
**dataType** `any`
Score value type used to interpret the numeric, categorical, or boolean value.
Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_DATA_TYPE_NUMERIC` | 1 | Canonical | A numeric measurement or rating. |
| `SCORE_DATA_TYPE_CATEGORICAL` | 2 | Canonical | A value chosen from a named set of categories. |
| `SCORE_DATA_TYPE_BOOLEAN` | 3 | Canonical | A true-or-false evaluation result. |
| `SCORE_DATA_TYPE_TEXT` | 4 | Canonical | Free-form text supplied by an evaluator or reviewer. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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`
String operand or score value used by the selected evaluation type.
**booleanValue** `boolean`
Boolean operand or score value used by the selected evaluation type.
**source** `any`
Source classification reported for the evaluation score.
Platform classification of who produced an evaluation score; the provider source label preserves its original vocabulary.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_SOURCE_JUDGE` | 1 | Canonical | A score produced by an automated judge. |
| `SCORE_SOURCE_HUMAN` | 2 | Canonical | A score entered by a human reviewer through the annotation path. |
| `SCORE_SOURCE_USER` | 3 | Canonical | Feedback supplied by an end user. |
| `SCORE_SOURCE_HARNESS` | 4 | Canonical | A score written by an evaluation harness or another API-based producer. |
| `SCORE_SOURCE_EVAL` | 5 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**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 conversation message or event.
**traceName** `string`
Denormalised for the Scores table's Trace Name column, which would
otherwise need one trace read per row.
**userId** `string`
Identifier of the user associated with the operation.
**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** `integer(int32)`
Number of comments reported on the evaluation object.
Minimum: -2147483648
Maximum: 2147483647
**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/cursor-page-info#response).
**nextCursor** `string`
Pass back as the request's `cursor` for the next page. Empty on the last
page.
**limit** `integer(int32)`
Maximum number of entries requested from the listing.
Minimum: -2147483648
Maximum: 2147483647
**totalItems** `integer(int32)`
Total number of matching items when it can be counted exactly. Absent when the selected
filters do not support an exact total.
Minimum: -2147483648
Maximum: 2147483647
#### 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).
- Overview: `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.
## Authentication
Required:
- API Key via `X-API-Key` header parameter
## Request Body
*Required*
Content type: `application/json`
Inputs for listing evaluation trace records.
**pageSize** `integer(int32)`
Requested maximum number of entries in a result page.
Minimum: 0
Maximum: 100
**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` | 1 | Canonical | Detailed diagnostic information intended for debugging. |
| `OBSERVATION_LEVEL_DEFAULT` | 2 | Canonical | Ordinary observation information without an elevated warning or error level. |
| `OBSERVATION_LEVEL_WARNING` | 3 | Canonical | A condition reported at warning severity. |
| `OBSERVATION_LEVEL_ERROR` | 4 | 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)`
Must not match:
Type: `any`
Enum: `0`
**orderBy** `string`
Ordering expression passed to the evaluation record query.
Maximum length: 64
**filters** `array[EvalFilter]`
Structured filters applied to the evaluation record query.
Typed comparison operand and column selector for querying evaluation-provider records.
Model reference: [EvalFilter](/api/models/eval-filter#request).
**type** `any` **required**
Discriminator selecting the evaluation filter’s operand type.
Operand shape and comparison vocabulary for an evaluation-record filter.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `EVAL_FILTER_TYPE_DATETIME` | 1 | Canonical | Compare a date-time value using ordered comparisons. |
| `EVAL_FILTER_TYPE_STRING` | 2 | Canonical | Compare text using equality or supported substring and prefix or suffix operators. |
| `EVAL_FILTER_TYPE_NUMBER` | 3 | Canonical | Compare a numeric value using equality or ordered comparisons. |
| `EVAL_FILTER_TYPE_STRING_OPTIONS` | 4 | Canonical | Match a string against a set of allowed or excluded choices. |
| `EVAL_FILTER_TYPE_CATEGORY_OPTIONS` | 5 | Canonical | Match a category against a set of allowed or excluded choices. |
| `EVAL_FILTER_TYPE_ARRAY_OPTIONS` | 6 | Canonical | Match array contents using any-of, none-of or all-of selection. |
| `EVAL_FILTER_TYPE_BOOLEAN` | 7 | Canonical | Compare a boolean value for equality or inequality. |
| `EVAL_FILTER_TYPE_NULL` | 8 | Canonical | Test whether the selected property is null or non-null. |
| `EVAL_FILTER_TYPE_STRING_OBJECT` | 9 | Canonical | Compare a string-valued member identified by a key, such as a metadata property. |
| `EVAL_FILTER_TYPE_NUMBER_OBJECT` | 10 | Canonical | Compare a numeric member identified by a key, such as a named score. |
| `EVAL_FILTER_TYPE_BOOLEAN_OBJECT` | 11 | Canonical | Compare a boolean member identified by a key. |
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: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`
Must not match:
Type: `any`
Enum: `0`
**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`
Exactly one value field is meaningful, chosen by type — flat siblings
rather than a oneof, per repo convention.
**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 or score value used by the selected evaluation type.
**stringValues** `array[string]`
The *_OPTIONS 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[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/trace-summary#response).
**traceId** `string`
Identifier of the evaluation trace.
**name** `string`
Name recorded for the evaluation trace.
**timestamp** `string(date-time)`
Timestamp associated with the conversation message or event.
**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** `integer(int32)`
Number of observations reported for the evaluation object.
Minimum: -2147483648
Maximum: 2147483647
**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** `integer(int32)`
Number of observations reported at error level.
Minimum: -2147483648
Maximum: 2147483647
**warningCount** `integer(int32)`
Number of observations reported at warning level.
Minimum: -2147483648
Maximum: 2147483647
**defaultCount** `integer(int32)`
Number of observations reported at the default level.
Minimum: -2147483648
Maximum: 2147483647
**debugCount** `integer(int32)`
Number of observations reported at debug level.
Minimum: -2147483648
Maximum: 2147483647
**scores** `array[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/score#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` | 1 | Canonical | A complete trace identified by its trace identifier. |
| `EVAL_TARGET_TYPE_OBSERVATION` | 2 | Canonical | A specific observation within a trace. |
| `EVAL_TARGET_TYPE_DATASET_RUN` | 3 | Canonical | An evaluation run over a dataset. |
| `EVAL_TARGET_TYPE_SESSION` | 4 | Canonical | A session grouping multiple traces; session scores are attached directly by the harness. |
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)`
Must not match:
Type: `any`
Enum: `0`
**targetId** `string`
Identifier of the evaluation object to which the score applies.
**name** `string`
Metric name identifying the recorded evaluation score.
**dataType** `any`
Score value type used to interpret the numeric, categorical, or boolean value.
Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_DATA_TYPE_NUMERIC` | 1 | Canonical | A numeric measurement or rating. |
| `SCORE_DATA_TYPE_CATEGORICAL` | 2 | Canonical | A value chosen from a named set of categories. |
| `SCORE_DATA_TYPE_BOOLEAN` | 3 | Canonical | A true-or-false evaluation result. |
| `SCORE_DATA_TYPE_TEXT` | 4 | Canonical | Free-form text supplied by an evaluator or reviewer. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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`
String operand or score value used by the selected evaluation type.
**booleanValue** `boolean`
Boolean operand or score value used by the selected evaluation type.
**source** `any`
Source classification reported for the evaluation score.
Platform classification of who produced an evaluation score; the provider source label preserves its original vocabulary.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_SOURCE_JUDGE` | 1 | Canonical | A score produced by an automated judge. |
| `SCORE_SOURCE_HUMAN` | 2 | Canonical | A score entered by a human reviewer through the annotation path. |
| `SCORE_SOURCE_USER` | 3 | Canonical | Feedback supplied by an end user. |
| `SCORE_SOURCE_HARNESS` | 4 | Canonical | A score written by an evaluation harness or another API-based producer. |
| `SCORE_SOURCE_EVAL` | 5 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**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 conversation message or event.
**traceName** `string`
Denormalised for the Scores table's Trace Name column, which would
otherwise need one trace read per row.
**userId** `string`
Identifier of the user associated with the operation.
**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** `integer(int32)`
Number of comments reported on the evaluation object.
Minimum: -2147483648
Maximum: 2147483647
**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/cursor-page-info#response).
**nextCursor** `string`
Pass back as the request's `cursor` for the next page. Empty on the last
page.
**limit** `integer(int32)`
Maximum number of entries requested from the listing.
Minimum: -2147483648
Maximum: 2147483647
**totalItems** `integer(int32)`
Total number of matching items when it can be counted exactly. Absent when the selected
filters do not support an exact total.
Minimum: -2147483648
Maximum: 2147483647
#### 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).
- Overview: `DOC-IS-evaluation-api-listTraces#overview`
- Request: `DOC-IS-evaluation-api-listTraces#request`
- Responses: `DOC-IS-evaluation-api-listTraces#responses`
- Filtering by entity: `DOC-IS-evaluation-api-listTraces#filtering-by-entity`
- Trace query support: `DOC-IS-evaluation-api-listTraces#trace-query-support`
---
# Record a dataset run
URL: https://docs.travila.ai/api/evals/record-dataset-run
**POST** `/api/v1/evals/record-dataset-run`
Registers a run and the supplied dataset-item/trace references. This call does not execute the dataset, create its scores, or enforce expected-output eligibility. `profileRevisionHash` is caller-supplied provenance; it does not prove a complete resolved configuration or deterministic replay.
This operation associates traces after they have been recorded, only where the evaluation configuration supports that workflow. Other configurations can return HTTP 200 without creating those associations. Inspect the run and expected items before treating it as recorded. This reference does not yet document experiment-context input on message requests.
## Authentication
Required:
- API Key via `X-API-Key` header parameter
## Request Body
*Required*
Content type: `application/json`
Records a dataset run. This is the RPC that motivated a public eval surface:
a harness executes a run and has to be able to post it, and until now the
only route in was the console's own admin edge.
**datasetId** `string` **required**
Identifier of the evaluation dataset.
Minimum length: 1
**runName** `string` **required**
Name assigned to the evaluation dataset run.
Minimum length: 1
**profileRevisionHash** `string`
Content hash identifying the agent profile revision recorded for the dataset run.
**metadataJson** `string`
Additional evaluation metadata serialized as JSON text.
**description** `string`
Human-readable explanation of the evaluation record.
**items** `array[DatasetRunItem]` **required**
Dataset-item and generated-trace pairs included in the run.
Minimum items: 1
One item of a dataset run: which dataset item was executed, and the trace it
produced.
Model reference: [DatasetRunItem](/api/models/dataset-run-item#request).
**datasetItemId** `string` **required**
Identifier of the dataset item used by this evaluation run.
Minimum length: 1
**traceId** `string` **required**
Identifier of the evaluation trace.
Minimum length: 1
**observationId** `string`
Optional: pin the run to one observation inside the trace rather than the
whole turn, for a harness that scores a single generation.
#### evals-recordDatasetRun-request
Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.
```json
{
"datasetId": "example_123",
"runName": "example",
"items": [
{
"datasetItemId": "example_123",
"traceId": "example_123"
}
]
}
```
#### 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
{
"datasetId": "support-assistant-regressions",
"runName": "nightly-2026-08-14",
"profileRevisionHash": "a1b2c3…",
"items": [
{
"datasetItemId": "di_001",
"traceId": "trc_a1b2c3"
}
]
}
```
## Responses
### 200 — OK
Content type: `application/json`
Result of recording a named run against an evaluation dataset.
**runId** `string`
Identifier of the recorded evaluation dataset run.
#### evals-recordDatasetRun-response
Illustrative response shape; omitted default fields and actual outcomes depend on the operation.
```json
{
"runId": "example_123"
}
```
Document ID: `DOC-IS-evaluation-api-recordDatasetRun`. [Section identities and revisions](/documentation-manifest.json).
- Overview: `DOC-IS-evaluation-api-recordDatasetRun#overview`
- Request: `DOC-IS-evaluation-api-recordDatasetRun#request`
- Responses: `DOC-IS-evaluation-api-recordDatasetRun#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
```json
{
"targetType": "EVAL_TARGET_TYPE_TRACE",
"targetId": "",
"name": "helpfulness",
"dataType": "SCORE_DATA_TYPE_NUMERIC",
"numericValue": 4,
"configId": ""
}
```
### 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.
## 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.
**targetType** `any` **required**
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` | 1 | Canonical | A complete trace identified by its trace identifier. |
| `EVAL_TARGET_TYPE_OBSERVATION` | 2 | Canonical | A specific observation within a trace. |
| `EVAL_TARGET_TYPE_DATASET_RUN` | 3 | Canonical | An evaluation run over a dataset. |
| `EVAL_TARGET_TYPE_SESSION` | 4 | Canonical | A session grouping multiple traces; session scores are attached directly by the harness. |
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: `1`, `2`, `3`, `4`
Must not match:
Type: `any`
Enum: `0`
**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.
Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_DATA_TYPE_NUMERIC` | 1 | Canonical | A numeric measurement or rating. |
| `SCORE_DATA_TYPE_CATEGORICAL` | 2 | Canonical | A value chosen from a named set of categories. |
| `SCORE_DATA_TYPE_BOOLEAN` | 3 | Canonical | A true-or-false evaluation result. |
| `SCORE_DATA_TYPE_TEXT` | 4 | Canonical | Free-form text supplied by an evaluator or reviewer. |
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: `1`, `2`, `3`, `4`
Must not match:
Type: `any`
Enum: `0`
**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 or annotation.
Kind of evaluation object a score or evaluation configuration addresses.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `EVAL_TARGET_TYPE_TRACE` | 1 | Canonical | A complete trace identified by its trace identifier. |
| `EVAL_TARGET_TYPE_OBSERVATION` | 2 | Canonical | A specific observation within a trace. |
| `EVAL_TARGET_TYPE_DATASET_RUN` | 3 | Canonical | An evaluation run over a dataset. |
| `EVAL_TARGET_TYPE_SESSION` | 4 | Canonical | A session grouping multiple traces; session scores are attached directly by the harness. |
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)`
Must not match:
Type: `any`
Enum: `0`
#### 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).
- Overview: `DOC-IS-evaluation-api-recordScore#overview`
- Request: `DOC-IS-evaluation-api-recordScore#request`
- Responses: `DOC-IS-evaluation-api-recordScore#responses`
- Resolving the rated turn: `DOC-IS-evaluation-api-recordScore#resolving-the-rated-turn`
- Supported ratings: `DOC-IS-evaluation-api-recordScore#supported-ratings`
- Examples: `DOC-IS-evaluation-api-recordScore#examples`
- Re-rating and withdrawing: `DOC-IS-evaluation-api-recordScore#re-rating-and-withdrawing`
---
# 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.
## 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 dataset item or annotation queue item being addressed.
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` | 1 | Canonical | The dataset item is active. |
| `DATASET_ITEM_STATUS_ARCHIVED` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
#### 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 dataset item or annotation queue item being addressed.
#### 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).
- Overview: `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".
## 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`
Name assigned to, or used to filter, the evaluation record.
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/score-config#response).
**configId** `string`
Identifier of the score configuration defining the score’s value domain.
**name** `string`
Name identifying the score definition.
**dataType** `any`
Score value type used to interpret the numeric, categorical, or boolean value.
Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_DATA_TYPE_NUMERIC` | 1 | Canonical | A numeric measurement or rating. |
| `SCORE_DATA_TYPE_CATEGORICAL` | 2 | Canonical | A value chosen from a named set of categories. |
| `SCORE_DATA_TYPE_BOOLEAN` | 3 | Canonical | A true-or-false evaluation result. |
| `SCORE_DATA_TYPE_TEXT` | 4 | Canonical | Free-form text supplied by an evaluator or reviewer. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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[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/score-config-category#response).
**label** `string`
Label identifying the prompt version or 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).
- Overview: `DOC-IS-evaluation-api-updateScoreConfig#overview`
- Request: `DOC-IS-evaluation-api-updateScoreConfig#request`
- Responses: `DOC-IS-evaluation-api-updateScoreConfig#responses`
---
# AnnotationQueueItem {#overview}
URL: https://docs.travila.ai/api/models/annotation-queue-item
Evaluation object assigned to an annotation queue with completion state and attribution.
## 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 dataset or annotation queue item. |
| `queueId` | `string` | Optional | Identifier of the annotation queue. |
| `objectId` | `string` | Optional | Identifier of the evaluation object addressed by the comment or 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 | Kind of evaluation object addressed by the comment or annotation queue item. |
| `status` | `string` (`ANNOTATION_QUEUE_ITEM_STATUS_PENDING`, `ANNOTATION_QUEUE_ITEM_STATUS_COMPLETED`) or `integer (int32)` | Optional | 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` | 1 | Canonical | A complete trace identified by its trace identifier. |
| `EVAL_TARGET_TYPE_OBSERVATION` | 2 | Canonical | A specific observation within a trace. |
| `EVAL_TARGET_TYPE_DATASET_RUN` | 3 | Canonical | An evaluation run over a dataset. |
| `EVAL_TARGET_TYPE_SESSION` | 4 | Canonical | A session grouping multiple traces; session scores are attached directly by the harness. |
### 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` | 1 | Canonical | The item is waiting for its annotation to be completed. |
| `ANNOTATION_QUEUE_ITEM_STATUS_COMPLETED` | 2 | 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)
Document: `DOC-API-MODEL-annotation-queue-item`.
---
# AnnotationQueue {#overview}
URL: https://docs.travila.ai/api/models/annotation-queue
Named work queue assigning score configurations to human annotation items.
## 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` | `integer (int32)` | Optional | Number of queue items awaiting annotation. Minimum: -2147483648. Maximum: 2147483647. |
| `completedCount` | `integer (int32)` | Optional | Number of queue items reported completed. Minimum: -2147483648. Maximum: 2147483647. |
## 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)
Document: `DOC-API-MODEL-annotation-queue`.
---
# Comment {#overview}
URL: https://docs.travila.ai/api/models/comment
Authored text attached to a trace, observation, or other evaluation object.
## 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 | Kind of evaluation object addressed by the comment or annotation queue item. |
| `objectId` | `string` | Optional | Identifier of the evaluation object addressed by the comment or queue item. |
| `content` | `string` | Optional | Text content of the evaluation comment. |
| `authorUserId` | `string` | Optional | Identifier recorded for the user who authored the comment. |
| `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` | 1 | Canonical | Attach the comment to a trace. |
| `COMMENT_OBJECT_TYPE_OBSERVATION` | 2 | Canonical | Attach the comment to a particular observation. |
| `COMMENT_OBJECT_TYPE_SESSION` | 3 | Canonical | Attach the comment to a session. |
| `COMMENT_OBJECT_TYPE_PROMPT` | 4 | 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)
Document: `DOC-API-MODEL-comment`.
---
# CursorPageInfo {#overview}
URL: https://docs.travila.ai/api/models/cursor-page-info
Opaque-cursor pagination details. A cursor is used to request the next page; arbitrary
page-number seeking is not supported.
## 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` | `integer (int32)` | Optional | Maximum number of entries requested from the listing. Minimum: -2147483648. Maximum: 2147483647. |
| `totalItems` | `integer (int32)` | 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. Minimum: -2147483648. Maximum: 2147483647. |
## 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)
Document: `DOC-API-MODEL-cursor-page-info`.
---
# DatasetItem {#overview}
URL: https://docs.travila.ai/api/models/dataset-item
One evaluation input with its expected output and source trace references.
## 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 dataset or annotation queue 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 | 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` | 1 | Canonical | The dataset item is active. |
| `DATASET_ITEM_STATUS_ARCHIVED` | 2 | 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)
Document: `DOC-API-MODEL-dataset-item`.
---
# DatasetRunItem {#overview}
URL: https://docs.travila.ai/api/models/dataset-run-item
One item of a dataset run: which dataset item was executed, and the trace it
produced.
## 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 |
|---|---|---|---|
| `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` |
## Where used {#where-used}
| Reference | Relationship |
|---|---|
| [Record a dataset run](/api/evals/record-dataset-run) | `POST /api/v1/evals/record-dataset-run` |
Download the [public reference contract](/reference/api-contract.json).
- [evals OpenAPI](/evals.yaml)
Document: `DOC-API-MODEL-dataset-run-item`.
---
# DatasetRun {#overview}
URL: https://docs.travila.ai/api/models/dataset-run
Metadata describing one execution of an evaluation dataset.
## 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 dataset or candidate evaluation 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` | `integer (int32)` | Optional | Number of dataset items reported for the dataset or run. Minimum: -2147483648. Maximum: 2147483647. |
| `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)
Document: `DOC-API-MODEL-dataset-run`.
---
# Dataset {#overview}
URL: https://docs.travila.ai/api/models/dataset
Evaluation dataset metadata, item counts, run history, and input/output schemas.
## 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` | `integer (int32)` | Optional | Number of dataset items reported for the dataset or run. Minimum: -2147483648. Maximum: 2147483647. |
| `runCount` | `integer (int32)` | Optional | Number of runs reported for the evaluation dataset. Minimum: -2147483648. Maximum: 2147483647. |
| `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)
Document: `DOC-API-MODEL-dataset`.
---
# EvalFilter {#overview}
URL: https://docs.travila.ai/api/models/eval-filter
Typed comparison operand and column selector for querying evaluation-provider records.
## 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)` (`1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`) | **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 | Exactly one value field is meaningful, chosen by type — flat siblings rather than a oneof, per repo convention. |
| `numberValue` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Numeric operand used by the evaluation filter. |
| `booleanValue` | `boolean` | Optional | Boolean operand or score value used by the selected evaluation type. |
| `stringValues` | Array of `string` | Optional | The *_OPTIONS 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.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `EVAL_FILTER_TYPE_DATETIME` | 1 | Canonical | Compare a date-time value using ordered comparisons. |
| `EVAL_FILTER_TYPE_STRING` | 2 | Canonical | Compare text using equality or supported substring and prefix or suffix operators. |
| `EVAL_FILTER_TYPE_NUMBER` | 3 | Canonical | Compare a numeric value using equality or ordered comparisons. |
| `EVAL_FILTER_TYPE_STRING_OPTIONS` | 4 | Canonical | Match a string against a set of allowed or excluded choices. |
| `EVAL_FILTER_TYPE_CATEGORY_OPTIONS` | 5 | Canonical | Match a category against a set of allowed or excluded choices. |
| `EVAL_FILTER_TYPE_ARRAY_OPTIONS` | 6 | Canonical | Match array contents using any-of, none-of or all-of selection. |
| `EVAL_FILTER_TYPE_BOOLEAN` | 7 | Canonical | Compare a boolean value for equality or inequality. |
| `EVAL_FILTER_TYPE_NULL` | 8 | Canonical | Test whether the selected property is null or non-null. |
| `EVAL_FILTER_TYPE_STRING_OBJECT` | 9 | Canonical | Compare a string-valued member identified by a key, such as a metadata property. |
| `EVAL_FILTER_TYPE_NUMBER_OBJECT` | 10 | Canonical | Compare a numeric member identified by a key, such as a named score. |
| `EVAL_FILTER_TYPE_BOOLEAN_OBJECT` | 11 | Canonical | Compare a boolean member identified by a key. |
## 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` |
| `type` | Disallowed values | `0` |
| `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)
Document: `DOC-API-MODEL-eval-filter`.
---
# EvalOverview {#overview}
URL: https://docs.travila.ai/api/models/eval-overview
Aggregated trace, score, latency, and profile metrics for an evaluation window.
## 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/named-count#response) | Optional | Trace counts grouped by trace name. |
| `tracesOverTime` | Array of [TimeSeriesPoint](/api/models/time-series-point#response) | Optional | Trace counts grouped into time buckets. |
| `observationsByLevel` | Array of [TimeSeriesPoint](/api/models/time-series-point#response) | Optional | Observation counts grouped by reported log level. |
| `scores` | Array of [ScoreAggregate](/api/models/score-aggregate#response) | Optional | Score aggregates grouped separately by metric name and source. |
| `scoreMovingAverage` | Array of [TimeSeriesPoint](/api/models/time-series-point#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/profile-quality-row#response) | Optional | Evaluation metrics grouped by agent profile. |
| `latencyPercentiles` | Array of [LatencyPercentileRow](/api/models/latency-percentile-row#response) | Optional | Latency percentile summaries grouped by trace name. |
| `recentLowScores` | Array of [Score](/api/models/score#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)
Document: `DOC-API-MODEL-eval-overview`.
---
# EvaluationPageInfo {#overview}
URL: https://docs.travila.ai/api/models/evaluation-page-info
Offset-pagination position, page size and result totals.
## 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` | `integer (int32)` | Optional | One-based page number. Minimum: -2147483648. Maximum: 2147483647. |
| `limit` | `integer (int32)` | Optional | Maximum number of entries requested from the listing. Minimum: -2147483648. Maximum: 2147483647. |
| `totalItems` | `integer (int32)` | Optional | Total item count reported for the selected dataset query. Minimum: -2147483648. Maximum: 2147483647. |
| `totalPages` | `integer (int32)` | Optional | Total number of pages reported for the current query. Minimum: -2147483648. Maximum: 2147483647. |
## 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)
Document: `DOC-API-MODEL-evaluation-page-info`.
---
# ExperimentContext {#overview}
URL: https://docs.travila.ai/api/models/experiment-context
Dataset-run attribution attached when a scripted evaluation turn is sent. Supported on
SendMessageRequest and SendMessageSyncRequest; ordinary conversation traffic leaves it unset.
## 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)
Document: `DOC-API-MODEL-experiment-context`.
---
# LatencyPercentileRow {#overview}
URL: https://docs.travila.ai/api/models/latency-percentile-row
Latency percentiles aggregated for one evaluation trace name.
## 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 reported for the trace group. |
| `p90` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | 90th-percentile latency reported for the trace group. |
| `p95` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | 95th-percentile latency reported for the trace group. |
| `p99` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | 99th-percentile latency reported for the trace group. |
## Where used {#where-used}
| Reference | Relationship |
|---|---|
| [Get the eval overview](/api/evals/get-overview) | `POST /api/v1/evals/get-overview` |
| [EvalOverview](/api/models/eval-overview#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json).
- [evals OpenAPI](/evals.yaml)
Document: `DOC-API-MODEL-latency-percentile-row`.
---
# MessageFeedback {#overview}
URL: https://docs.travila.ai/api/models/message-feedback
One user's feedback on an assistant-generated message.
## Usage profiles {#fields}
| Usage | Fields and validation |
|---|---|
| In requests | [View fields](#request) |
| In responses | [View fields](#response) |
| In webhook payloads | [View fields](#webhook) |
## 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)` (`1`, `2`) | **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` | `integer (int32)` | Optional | Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent. Minimum: 0. Maximum: 10. |
| `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` | 1 | Canonical | Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice. |
| `FEEDBACK_KIND_SCALE` | 2 | Canonical | Feedback expressed as an integer rating from 1 through 10. |
## 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` | Defined enum value | `true` |
| `kind` | Disallowed values | `0` |
| `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` | `integer (int32)` | Optional | Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent. Minimum: -2147483648. Maximum: 2147483647. |
| `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` | 1 | Canonical | Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice. |
| `FEEDBACK_KIND_SCALE` | 2 | Canonical | Feedback expressed as an integer rating from 1 through 10. |
## 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` | Defined enum value | `true` |
| `kind` | Disallowed values | `0` |
| `rating` | At most | `10` |
| `rating` | At least | `0` |
| `reason` | Maximum length | `1000` |
## In webhook payloads {#webhook}
Webhook JSON uses protobuf field names (snake_case).
| 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. |
| `thumb_up` | `boolean` | Optional | Positive when true and negative when false; used for THUMB feedback. |
| `rating` | `integer (int32)` | Optional | Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent. Minimum: -2147483648. Maximum: 2147483647. |
| `reason` | `string` | Optional | Optional explanation for the rating. |
| `rated_at` | `string (date-time)` | Optional | Timestamp when feedback was submitted (server-set) |
| `rated_by` | `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` {#webhook-values-kind}
Value scale used to interpret recorded feedback.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FEEDBACK_KIND_THUMB` | 1 | Canonical | Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice. |
| `FEEDBACK_KIND_SCALE` | 2 | Canonical | Feedback expressed as an integer rating from 1 through 10. |
## Request validation {#webhook-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` | Defined enum value | `true` |
| `kind` | Disallowed values | `0` |
| `rating` | At most | `10` |
| `rating` | At least | `0` |
| `reason` | Maximum length | `1000` |
## Where used {#where-used}
| Reference | Relationship |
|---|---|
| [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` |
| [Send a message and wait for the result](/api/conversations/send-message-sync) | `POST /api/v1/llm/send-message-sync` |
| [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` |
| [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` |
| [llm.message_published](/api/events/llm-message-published) | Webhook JSON uses protobuf field names (snake_case). |
| [Message](/api/models/message#response) | Nested in model |
| [Message](/api/models/message#request) | Nested in model |
| [Message](/api/models/message#webhook) | Nested in model |
Download the [public reference contract](/reference/api-contract.json).
- [conversations OpenAPI](/conversations.yaml)
Document: `DOC-API-MODEL-message-feedback`.
---
# NamedCount {#overview}
URL: https://docs.travila.ai/api/models/named-count
Count of evaluation records grouped under a shared label.
## 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` |
| [EvalOverview](/api/models/eval-overview#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json).
- [evals OpenAPI](/evals.yaml)
Document: `DOC-API-MODEL-named-count`.
---
# Observation {#overview}
URL: https://docs.travila.ai/api/models/observation
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.
## 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 | 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 | 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` | `integer (int32)` | Optional | Version of the prompt associated with the generation. Minimum: -2147483648. Maximum: 2147483647. |
| `scores` | Array of [Score](/api/models/score#response) | Optional | Evaluation scores returned for the selected objects or query. |
| `commentCount` | `integer (int32)` | Optional | Number of comments reported on the evaluation object. Minimum: -2147483648. Maximum: 2147483647. |
| `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.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `OBSERVATION_TYPE_SPAN` | 1 | Canonical | A timed unit of work represented as a span. |
| `OBSERVATION_TYPE_GENERATION` | 2 | Canonical | A model-generation operation and its recorded inputs, outputs and usage. |
| `OBSERVATION_TYPE_EVENT` | 3 | Canonical | A point-in-time event rather than a timed operation. |
| `OBSERVATION_TYPE_TOOL` | 4 | Canonical | Execution of a tool call. |
| `OBSERVATION_TYPE_RETRIEVER` | 5 | Canonical | Retrieval of supporting documents or other context. |
| `OBSERVATION_TYPE_AGENT` | 6 | Canonical | An agent-level operation reported in the trace. |
| `OBSERVATION_TYPE_CHAIN` | 7 | Canonical | A sequence or chain of related processing steps. |
| `OBSERVATION_TYPE_EMBEDDING` | 8 | Canonical | Computation of vector embeddings. |
| `OBSERVATION_TYPE_EVALUATOR` | 9 | Canonical | An evaluator operation that assesses another result. |
| `OBSERVATION_TYPE_GUARDRAIL` | 10 | 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` | 1 | Canonical | Detailed diagnostic information intended for debugging. |
| `OBSERVATION_LEVEL_DEFAULT` | 2 | Canonical | Ordinary observation information without an elevated warning or error level. |
| `OBSERVATION_LEVEL_WARNING` | 3 | Canonical | A condition reported at warning severity. |
| `OBSERVATION_LEVEL_ERROR` | 4 | 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` |
| [TraceDetail](/api/models/trace-detail#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json).
- [evals OpenAPI](/evals.yaml)
Document: `DOC-API-MODEL-observation`.
---
# ProfileQualityRow {#overview}
URL: https://docs.travila.ai/api/models/profile-quality-row
Aggregated evaluation results and usage for one agent profile.
## 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` |
| [EvalOverview](/api/models/eval-overview#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json).
- [evals OpenAPI](/evals.yaml)
Document: `DOC-API-MODEL-profile-quality-row`.
---
# ScoreAggregate {#overview}
URL: https://docs.travila.ai/api/models/score-aggregate
Count and average for scores grouped by name and source.
## 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 | 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 preserves its original vocabulary.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_SOURCE_JUDGE` | 1 | Canonical | A score produced by an automated judge. |
| `SCORE_SOURCE_HUMAN` | 2 | Canonical | A score entered by a human reviewer through the annotation path. |
| `SCORE_SOURCE_USER` | 3 | Canonical | Feedback supplied by an end user. |
| `SCORE_SOURCE_HARNESS` | 4 | Canonical | A score written by an evaluation harness or another API-based producer. |
| `SCORE_SOURCE_EVAL` | 5 | 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` |
| [EvalOverview](/api/models/eval-overview#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json).
- [evals OpenAPI](/evals.yaml)
Document: `DOC-API-MODEL-score-aggregate`.
---
# ScoreConfigCategory {#overview}
URL: https://docs.travila.ai/api/models/score-config-category
Named category and associated numeric value in a categorical score definition.
## 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 the prompt version or 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` |
| [ScoreConfig](/api/models/score-config#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json).
- [evals OpenAPI](/evals.yaml)
Document: `DOC-API-MODEL-score-config-category`.
---
# ScoreConfig {#overview}
URL: https://docs.travila.ai/api/models/score-config
Score definition specifying its value type, bounds, and allowed categories.
## 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 | Score value type used to interpret the numeric, categorical, or boolean value. |
| `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/score-config-category#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}
Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_DATA_TYPE_NUMERIC` | 1 | Canonical | A numeric measurement or rating. |
| `SCORE_DATA_TYPE_CATEGORICAL` | 2 | Canonical | A value chosen from a named set of categories. |
| `SCORE_DATA_TYPE_BOOLEAN` | 3 | Canonical | A true-or-false evaluation result. |
| `SCORE_DATA_TYPE_TEXT` | 4 | Canonical | Free-form text supplied by an evaluator or reviewer. |
## 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)
Document: `DOC-API-MODEL-score-config`.
---
# Score {#overview}
URL: https://docs.travila.ai/api/models/score
Evaluation score with its value, source, target identity, and generation attribution.
## 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 | 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 | Score value type used to interpret the numeric, categorical, or boolean value. |
| `numericValue` | `number (double)` or `string` (`NaN`, `Infinity`, `-Infinity`) | Optional | Numeric score value reported by the evaluator. |
| `stringValue` | `string` | Optional | String operand or score value used by the selected evaluation type. |
| `booleanValue` | `boolean` | Optional | Boolean operand or score value used by the selected evaluation type. |
| `source` | `string` (`SCORE_SOURCE_JUDGE`, `SCORE_SOURCE_HUMAN`, `SCORE_SOURCE_USER`, `SCORE_SOURCE_HARNESS`, `SCORE_SOURCE_EVAL`) or `integer (int32)` | Optional | 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. |
| `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 conversation message or event. |
| `traceName` | `string` | Optional | Denormalised for the Scores table's Trace Name column, which would otherwise need one trace read per row. |
| `userId` | `string` | Optional | Identifier of the user associated with the operation. |
| `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` | 1 | Canonical | A complete trace identified by its trace identifier. |
| `EVAL_TARGET_TYPE_OBSERVATION` | 2 | Canonical | A specific observation within a trace. |
| `EVAL_TARGET_TYPE_DATASET_RUN` | 3 | Canonical | An evaluation run over a dataset. |
| `EVAL_TARGET_TYPE_SESSION` | 4 | Canonical | A session grouping multiple traces; session scores are attached directly by the harness. |
### Values of `dataType` {#response-values-datatype}
Data representation of an evaluation score or score configuration.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_DATA_TYPE_NUMERIC` | 1 | Canonical | A numeric measurement or rating. |
| `SCORE_DATA_TYPE_CATEGORICAL` | 2 | Canonical | A value chosen from a named set of categories. |
| `SCORE_DATA_TYPE_BOOLEAN` | 3 | Canonical | A true-or-false evaluation result. |
| `SCORE_DATA_TYPE_TEXT` | 4 | Canonical | Free-form text supplied by an evaluator or reviewer. |
### Values of `source` {#response-values-source}
Platform classification of who produced an evaluation score; the provider source label preserves its original vocabulary.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `SCORE_SOURCE_JUDGE` | 1 | Canonical | A score produced by an automated judge. |
| `SCORE_SOURCE_HUMAN` | 2 | Canonical | A score entered by a human reviewer through the annotation path. |
| `SCORE_SOURCE_USER` | 3 | Canonical | Feedback supplied by an end user. |
| `SCORE_SOURCE_HARNESS` | 4 | Canonical | A score written by an evaluation harness or another API-based producer. |
| `SCORE_SOURCE_EVAL` | 5 | 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` |
| [EvalOverview](/api/models/eval-overview#response) | Nested in model |
| [Observation](/api/models/observation#response) | Nested in model |
| [SessionSummary](/api/models/session-summary#response) | Nested in model |
| [TraceDetail](/api/models/trace-detail#response) | Nested in model |
| [TraceSummary](/api/models/trace-summary#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json).
- [evals OpenAPI](/evals.yaml)
Document: `DOC-API-MODEL-score`.
---
# SessionDetail {#overview}
URL: https://docs.travila.ai/api/models/session-detail
Evaluation session summary together with the traces belonging to the session.
## 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/session-summary#response) | Optional | Summary information for the evaluation trace or session. |
| `traces` | Array of [TraceSummary](/api/models/trace-summary#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)
Document: `DOC-API-MODEL-session-detail`.
---
# SessionSummary {#overview}
URL: https://docs.travila.ai/api/models/session-summary
Aggregated trace, usage, and score information for an evaluation session.
## 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 | Identifiers of the users selected by the operation. |
| `traceCount` | `integer (int32)` | Optional | Number of traces represented by this summary or group. Minimum: -2147483648. Maximum: 2147483647. |
| `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/score#response) | Optional | Evaluation scores returned for the selected objects or query. |
| `commentCount` | `integer (int32)` | Optional | Number of comments reported on the evaluation object. Minimum: -2147483648. Maximum: 2147483647. |
| `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` |
| [SessionDetail](/api/models/session-detail#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json).
- [evals OpenAPI](/evals.yaml)
Document: `DOC-API-MODEL-session-summary`.
---
# TimeSeriesPoint {#overview}
URL: https://docs.travila.ai/api/models/time-series-point
Numeric evaluation measurement associated with a time bucket and series.
## 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` |
| [EvalOverview](/api/models/eval-overview#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json).
- [evals OpenAPI](/evals.yaml)
Document: `DOC-API-MODEL-time-series-point`.
---
# TraceDetail {#overview}
URL: https://docs.travila.ai/api/models/trace-detail
Evaluation trace summary together with its observations and attached scores.
## 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/trace-summary#response) | Optional | Summary information for the evaluation trace or session. |
| `observations` | Array of [Observation](/api/models/observation#response) | Optional | Observations associated with the trace or returned by the query. |
| `scores` | Array of [Score](/api/models/score#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)
Document: `DOC-API-MODEL-trace-detail`.
---
# TraceSummary {#overview}
URL: https://docs.travila.ai/api/models/trace-summary
Evaluation summary for a conversation turn, including its recorded conversation, message and
profile attribution.
## 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 conversation message or event. |
| `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` | `integer (int32)` | Optional | Number of observations reported for the evaluation object. Minimum: -2147483648. Maximum: 2147483647. |
| `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` | `integer (int32)` | Optional | Number of observations reported at error level. Minimum: -2147483648. Maximum: 2147483647. |
| `warningCount` | `integer (int32)` | Optional | Number of observations reported at warning level. Minimum: -2147483648. Maximum: 2147483647. |
| `defaultCount` | `integer (int32)` | Optional | Number of observations reported at the default level. Minimum: -2147483648. Maximum: 2147483647. |
| `debugCount` | `integer (int32)` | Optional | Number of observations reported at debug level. Minimum: -2147483648. Maximum: 2147483647. |
| `scores` | Array of [Score](/api/models/score#response) | Optional | Evaluation scores returned for the selected objects or query. |
| `commentCount` | `integer (int32)` | Optional | Number of comments reported on the evaluation object. Minimum: -2147483648. Maximum: 2147483647. |
## 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` |
| [SessionDetail](/api/models/session-detail#response) | Nested in model |
| [TraceDetail](/api/models/trace-detail#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json).
- [evals OpenAPI](/evals.yaml)
Document: `DOC-API-MODEL-trace-summary`.
---
# Use your own services in an assistant {#custom-mcp-servers}
URL: https://docs.travila.ai/integrations/tools-connections/features/custom-mcp-servers
**Section:** `DOC-IN-tools-connections-custom-mcp-feature#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}
**Section:** `DOC-IN-tools-connections-custom-mcp-feature#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}
**Section:** `DOC-IN-tools-connections-custom-mcp-feature#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}
**Section:** `DOC-IN-tools-connections-custom-mcp-feature#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}
**Section:** `DOC-IN-tools-connections-custom-mcp-feature#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)
Document ID: `DOC-IN-tools-connections-custom-mcp-feature`. Section identities and revisions.
---
# Connected account selection {#overview}
URL: https://docs.travila.ai/api/connected-apps/account-selection
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/mcp-server-reference#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/tool-call#response-field-clienttooldeadlineat) and configure [`toolPolicy.clientToolTimeoutMs`](/api/models/tool-execution-policy#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.
---
# 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.
## 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 (JWT) 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").
#### 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).
- Overview: `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.
## 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 (JWT) 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).
- Overview: `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.
## 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 (JWT) 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** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
#### 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).
- Overview: `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.
## 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 (JWT) 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** `integer(int32)`
Maximum number of entries requested from the listing.
Minimum: -2147483648
Maximum: 2147483647
**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[Account]`
Pipedream connected accounts returned for this page.
Connected account (external user's OAuth connection to an app)
Model reference: [Account](/api/models/account#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.
**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/pipedream-page-info#response).
**count** `integer(int32)`
Items in current page.
Minimum: -2147483648
Maximum: 2147483647
**totalCount** `integer(int32)`
Total items matching query.
Minimum: -2147483648
Maximum: 2147483647
**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).
- Overview: `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.
## 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 (JWT) 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** `integer(int32)`
Maximum number of entries requested from the listing.
Minimum: -2147483648
Maximum: 2147483647
#### 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[AppCategory]`
Pipedream app categories returned for this page.
App category
Model reference: [AppCategory](/api/models/app-category#response).
**id** `string`
Identifier of the app category record.
**nameSlug** `string`
Pipedream app slug identifying the catalog entry.
**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/pipedream-page-info#response).
**count** `integer(int32)`
Items in current page.
Minimum: -2147483648
Maximum: 2147483647
**totalCount** `integer(int32)`
Total items matching query.
Minimum: -2147483648
Maximum: 2147483647
**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).
- Overview: `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.
## 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 (JWT) 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** `integer(int32)`
Maximum number of entries requested from the listing.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Sort by the app's display name. |
| `APP_SORT_KEY_NAME_SLUG` | 2 | Canonical | Sort by the app's stable name slug. |
| `APP_SORT_KEY_FEATURED_WEIGHT` | 3 | Canonical | Sort by the catalog's featured-app ranking 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)`
Must not match:
Type: `any`
Enum: `0`
**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` | 1 | Canonical | Order results from lower to higher values of the selected sort key. |
| `SORT_DIRECTION_DESC` | 2 | Canonical | Order results from higher to lower values of the selected sort key. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `SORT_DIRECTION_ASC`, `SORT_DIRECTION_DESC`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
#### 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[App]`
Pipedream app catalog entries returned for this page.
App metadata
Model reference: [App](/api/models/app#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 connected account or app.
Credential mechanism an integration app uses when connecting an account.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `AUTH_TYPE_KEYS` | 1 | Canonical | The app uses API-key credentials. |
| `AUTH_TYPE_OAUTH` | 2 | Canonical | The app uses an OAuth authorization flow. |
| `AUTH_TYPE_NONE` | 3 | Canonical | The app does not require authentication credentials. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `AUTH_TYPE_KEYS`, `AUTH_TYPE_OAUTH`, `AUTH_TYPE_NONE`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**description** `string`
Human-readable description of the resource.
**imgSrc** `string`
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** `integer(int32)`
Provider weight used to order featured apps.
Minimum: -2147483648
Maximum: 2147483647
**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/pipedream-page-info#response).
**count** `integer(int32)`
Items in current page.
Minimum: -2147483648
Maximum: 2147483647
**totalCount** `integer(int32)`
Total items matching query.
Minimum: -2147483648
Maximum: 2147483647
**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).
- Overview: `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.
## 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 (JWT) 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.
**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**
URL associated with the resource or outbound 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** `integer(int32)`
HTTP status code returned by the connected app’s API.
Minimum: -2147483648
Maximum: 2147483647
**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).
- Overview: `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.
## 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 (JWT) 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/app#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 connected account or app.
Credential mechanism an integration app uses when connecting an account.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `AUTH_TYPE_KEYS` | 1 | Canonical | The app uses API-key credentials. |
| `AUTH_TYPE_OAUTH` | 2 | Canonical | The app uses an OAuth authorization flow. |
| `AUTH_TYPE_NONE` | 3 | Canonical | The app does not require authentication credentials. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `AUTH_TYPE_KEYS`, `AUTH_TYPE_OAUTH`, `AUTH_TYPE_NONE`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**description** `string`
Human-readable description of the resource.
**imgSrc** `string`
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** `integer(int32)`
Provider weight used to order featured apps.
Minimum: -2147483648
Maximum: 2147483647
#### 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).
- Overview: `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`
---
# Third-Party Integrations APIs
URL: https://docs.travila.ai/api/connected-apps
Version: `1.0.0`
Connect end-user accounts through the optional hosted Pipedream integration. This API requires Pipedream Connect to be enabled for your account.
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](/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](/integrations/tools-connections/connected-apps)
### 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](/api).
## Authentication {#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.
Security scheme type: `apiKey`
Parameter location: `header`
Parameter name: `X-API-Key`
### 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`.
Security scheme type: `apiKey`
Parameter location: `header`
Parameter name: `X-On-Behalf-Of`
### 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`.
Security scheme type: `http`
HTTP authorization scheme: `bearer`
Bearer format: `JWT`
## Operations
- [Start connecting an app](/api/connected-apps/pipedream-create-connect-token) — `POST /api/v1/integrations/pipedream/create-connect-token`
- [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`
- [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`
- [Call a connected app's API as the user](/api/connected-apps/pipedream-proxy-for-current-user) — `POST /api/v1/integrations/pipedream/proxy`
- [Retrieve one app by slug](/api/connected-apps/pipedream-retrieve-app) — `POST /api/v1/integrations/pipedream/retrieve-app`
Document ID: `DOC-IN-tools-connections-apps-api-overview`. [Section identities and revisions](/documentation-manifest.json).
- Overview: `DOC-IN-tools-connections-apps-api-overview#overview`
- JSON conventions: `DOC-IN-tools-connections-apps-api-overview#json-conventions`
- Authentication: `DOC-IN-tools-connections-apps-api-overview#authentication`
- Everything Is Scoped To The Calling User: `DOC-IN-tools-connections-apps-api-overview#everything-is-scoped-to-the-calling-user`
- Pagination: `DOC-IN-tools-connections-apps-api-overview#pagination`
---
# 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.
## 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 record supplied to or returned by the operation.
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}".
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.
Model reference: [CustomMCPServer](/api/models/custom-mcp-server#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.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CUSTOM_MCP_SERVER_AUTH_TYPE_NONE` | 1 | Canonical | Send requests without attaching a secret for authentication. |
| `CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER` | 2 | Canonical | Send the secret as a Bearer token in the Authorization header. |
| `CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER` | 3 | Canonical | Send the secret in the configured custom header. |
| `CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY` | 4 | Canonical | Add the secret as the configured URL query parameter when connecting; the stored endpoint remains the base URL. |
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: `1`, `2`, `3`, `4`
Must not match:
Type: `any`
Enum: `0`
**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.
Model reference: [SecretRef](/api/models/secret-ref#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})?$
**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.
**authQueryParam** `string`
Required for QUERY auth; the vendor's parameter name (e.g. "tavilyApiKey").
Empty is allowed — populated only for QUERY auth.
Pattern: ^([A-Za-z0-9._~-]{1,128})?$
#### 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 record supplied to or returned by the operation.
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}".
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.
Model reference: [CustomMCPServer](/api/models/custom-mcp-server#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.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CUSTOM_MCP_SERVER_AUTH_TYPE_NONE` | 1 | Canonical | Send requests without attaching a secret for authentication. |
| `CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER` | 2 | Canonical | Send the secret as a Bearer token in the Authorization header. |
| `CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER` | 3 | Canonical | Send the secret in the configured custom header. |
| `CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY` | 4 | Canonical | Add the secret as the configured URL query parameter when connecting; the stored endpoint remains the base URL. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
Model reference: [SecretRef](/api/models/secret-ref#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.
**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.
**authQueryParam** `string`
Required for QUERY auth; the vendor's parameter name (e.g. "tavilyApiKey").
Empty is allowed — populated only for QUERY auth.
#### 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).
- Overview: `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`
---
# Custom MCP Server APIs
URL: https://docs.travila.ai/api/mcp-servers
Version: `1.0.0`
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.
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](/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.
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](/integrations/tools-connections/custom-mcp-servers)
### 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](/api).
## Authentication {#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.
Security scheme type: `apiKey`
Parameter location: `header`
Parameter name: `X-API-Key`
## Operations
- [Register a custom MCP server](/api/mcp-servers/create-custom-mcp-server) — `POST /api/v1/mcp-servers/create`
- [Delete a custom MCP server](/api/mcp-servers/delete-custom-mcp-server) — `POST /api/v1/mcp-servers/delete`
- [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`
- [Test a custom MCP server connection](/api/mcp-servers/test-custom-mcp-server-connection) — `POST /api/v1/mcp-servers/test-connection`
- [Update a custom MCP server](/api/mcp-servers/update-custom-mcp-server) — `POST /api/v1/mcp-servers/update`
Document ID: `DOC-IN-tools-connections-servers-api-overview`. [Section identities and revisions](/documentation-manifest.json).
- Overview: `DOC-IN-tools-connections-servers-api-overview#overview`
- JSON conventions: `DOC-IN-tools-connections-servers-api-overview#json-conventions`
- Authentication: `DOC-IN-tools-connections-servers-api-overview#authentication`
- Scoping: `DOC-IN-tools-connections-servers-api-overview#scoping`
- Credentials: `DOC-IN-tools-connections-servers-api-overview#credentials`
---
# 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).
## 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).
- Overview: `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.
## 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 record supplied to or returned by the operation.
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}".
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.
Model reference: [CustomMCPServer](/api/models/custom-mcp-server#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.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CUSTOM_MCP_SERVER_AUTH_TYPE_NONE` | 1 | Canonical | Send requests without attaching a secret for authentication. |
| `CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER` | 2 | Canonical | Send the secret as a Bearer token in the Authorization header. |
| `CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER` | 3 | Canonical | Send the secret in the configured custom header. |
| `CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY` | 4 | Canonical | Add the secret as the configured URL query parameter when connecting; the stored endpoint remains the base URL. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
Model reference: [SecretRef](/api/models/secret-ref#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.
**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.
**authQueryParam** `string`
Required for QUERY auth; the vendor's parameter name (e.g. "tavilyApiKey").
Empty is allowed — populated only for QUERY auth.
#### 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).
- Overview: `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.
## 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[CustomMCPServer]`
MCP server configurations or statuses returned by the operation.
A project-scoped, HTTP-only MCP server definition, keyed
(tenant_id, project_id, server_id). Its wire ID is "custom:{server_id}".
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.
Model reference: [CustomMCPServer](/api/models/custom-mcp-server#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.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CUSTOM_MCP_SERVER_AUTH_TYPE_NONE` | 1 | Canonical | Send requests without attaching a secret for authentication. |
| `CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER` | 2 | Canonical | Send the secret as a Bearer token in the Authorization header. |
| `CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER` | 3 | Canonical | Send the secret in the configured custom header. |
| `CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY` | 4 | Canonical | Add the secret as the configured URL query parameter when connecting; the stored endpoint remains the base URL. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
Model reference: [SecretRef](/api/models/secret-ref#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.
**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.
**authQueryParam** `string`
Required for QUERY auth; the vendor's parameter name (e.g. "tavilyApiKey").
Empty is allowed — populated only for QUERY auth.
**total** `integer(int32)`
Total number of entries reported by the listing.
Minimum: -2147483648
Maximum: 2147483647
#### 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).
- Overview: `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`
---
# 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.
## 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** `integer(int32)`
Number of tools reported by the MCP server.
Minimum: -2147483648
Maximum: 2147483647
**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).
- Overview: `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/custom-mcp-server#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`.
## 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 record supplied to or returned by the operation.
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}".
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.
Model reference: [CustomMCPServer](/api/models/custom-mcp-server#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.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CUSTOM_MCP_SERVER_AUTH_TYPE_NONE` | 1 | Canonical | Send requests without attaching a secret for authentication. |
| `CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER` | 2 | Canonical | Send the secret as a Bearer token in the Authorization header. |
| `CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER` | 3 | Canonical | Send the secret in the configured custom header. |
| `CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY` | 4 | Canonical | Add the secret as the configured URL query parameter when connecting; the stored endpoint remains the base URL. |
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: `1`, `2`, `3`, `4`
Must not match:
Type: `any`
Enum: `0`
**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.
Model reference: [SecretRef](/api/models/secret-ref#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})?$
**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.
**authQueryParam** `string`
Required for QUERY auth; the vendor's parameter name (e.g. "tavilyApiKey").
Empty is allowed — populated only for QUERY auth.
Pattern: ^([A-Za-z0-9._~-]{1,128})?$
#### 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`
MCP server record supplied to or returned by the operation.
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}".
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.
Model reference: [CustomMCPServer](/api/models/custom-mcp-server#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.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CUSTOM_MCP_SERVER_AUTH_TYPE_NONE` | 1 | Canonical | Send requests without attaching a secret for authentication. |
| `CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER` | 2 | Canonical | Send the secret as a Bearer token in the Authorization header. |
| `CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER` | 3 | Canonical | Send the secret in the configured custom header. |
| `CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY` | 4 | Canonical | Add the secret as the configured URL query parameter when connecting; the stored endpoint remains the base URL. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
Model reference: [SecretRef](/api/models/secret-ref#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.
**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.
**authQueryParam** `string`
Required for QUERY auth; the vendor's parameter name (e.g. "tavilyApiKey").
Empty is allowed — populated only for QUERY auth.
#### 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).
- Overview: `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`
---
# Account {#overview}
URL: https://docs.travila.ai/api/models/account
Connected account (external user's OAuth connection to an app)
## 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 | Pipedream application selected by the request or returned by the provider. |
| `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. |
## 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)
Document: `DOC-API-MODEL-account`.
---
# AppCategory {#overview}
URL: https://docs.travila.ai/api/models/app-category
App category
## 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 | Pipedream app slug identifying the catalog entry. |
| `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)
Document: `DOC-API-MODEL-app-category`.
---
# App {#overview}
URL: https://docs.travila.ai/api/models/app
App metadata
## 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 | Authentication mechanism reported for the connected account or app. |
| `description` | `string` | Optional | Human-readable description of the resource. |
| `imgSrc` | `string` | Optional | 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` | `integer (int32)` | Optional | Provider weight used to order featured apps. Minimum: -2147483648. Maximum: 2147483647. |
### Values of `authType` {#response-values-authtype}
Credential mechanism an integration app uses when connecting an account.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `AUTH_TYPE_KEYS` | 1 | Canonical | The app uses API-key credentials. |
| `AUTH_TYPE_OAUTH` | 2 | Canonical | The app uses an OAuth authorization flow. |
| `AUTH_TYPE_NONE` | 3 | Canonical | The app does not require authentication credentials. |
## 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)
Document: `DOC-API-MODEL-app`.
---
# CustomMCPServer {#overview}
URL: https://docs.travila.ai/api/models/custom-mcp-server
A project-scoped, HTTP-only MCP server definition, keyed
(tenant_id, project_id, server_id). Its wire ID is "custom:{server_id}".
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.
## 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)` (`1`, `2`, `3`, `4`) | Optional | Authentication mechanism configured for the MCP server. |
| `authSecretRef` | [SecretRef](/api/models/secret-ref#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})?$. |
| `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` | `string` | Optional | Required for QUERY auth; the vendor's parameter name (e.g. "tavilyApiKey"). Empty is allowed — populated only for QUERY auth. Pattern: ^([A-Za-z0-9._~-]{1,128})?$. |
### Values of `authType` {#request-values-authtype}
How credentials are attached to requests to a tenant-configured MCP server.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CUSTOM_MCP_SERVER_AUTH_TYPE_NONE` | 1 | Canonical | Send requests without attaching a secret for authentication. |
| `CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER` | 2 | Canonical | Send the secret as a Bearer token in the Authorization header. |
| `CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER` | 3 | Canonical | Send the secret in the configured custom header. |
| `CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY` | 4 | Canonical | Add the secret as the configured URL query parameter when connecting; the stored endpoint remains the base URL. |
## 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})?$` |
| `requestTimeout` | At most | `120s` |
| `authQueryParam` | Pattern | `^([A-Za-z0-9._~-]{1,128})?$` |
## 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 | Authentication mechanism configured for the MCP server. |
| `authSecretRef` | [SecretRef](/api/models/secret-ref#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. |
| `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` | `string` | Optional | Required for QUERY auth; the vendor's parameter name (e.g. "tavilyApiKey"). 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.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CUSTOM_MCP_SERVER_AUTH_TYPE_NONE` | 1 | Canonical | Send requests without attaching a secret for authentication. |
| `CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER` | 2 | Canonical | Send the secret as a Bearer token in the Authorization header. |
| `CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER` | 3 | Canonical | Send the secret in the configured custom header. |
| `CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY` | 4 | Canonical | Add the secret as the configured URL query parameter when connecting; the stored endpoint remains the base URL. |
## 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})?$` |
| `requestTimeout` | At most | `120s` |
| `authQueryParam` | Pattern | `^([A-Za-z0-9._~-]{1,128})?$` |
## Where used {#where-used}
| Reference | Relationship |
|---|---|
| [Register a custom MCP server](/api/mcp-servers/create-custom-mcp-server) | `POST /api/v1/mcp-servers/create` |
| [Update a custom MCP server](/api/mcp-servers/update-custom-mcp-server) | `POST /api/v1/mcp-servers/update` |
| [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` |
Download the [public reference contract](/reference/api-contract.json).
- [mcp-servers OpenAPI](/mcp-servers.yaml)
Document: `DOC-API-MODEL-custom-mcp-server`.
---
# MCPServerInfo {#overview}
URL: https://docs.travila.ai/api/models/mcp-server-info
Detailed server information
## 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 | Current connection status reported for the MCP server. |
| `availableTools` | Array of [ToolDefinition](/api/models/tool-definition#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 | 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` | 1 | Canonical | A connection to the MCP server is established. |
| `MCP_SERVER_CONNECTION_STATUS_DISCONNECTED` | 2 | Canonical | There is no active connection to the MCP server. |
| `MCP_SERVER_CONNECTION_STATUS_ERROR` | 3 | Canonical | A connection or discovery attempt encountered an error. |
| `MCP_SERVER_CONNECTION_STATUS_DISCOVERING` | 4 | 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.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `MCP_SERVER_KIND_INTERNAL` | 1 | Canonical | A server compiled into the deployment and dispatched in-process. |
| `MCP_SERVER_KIND_BUILT_IN` | 2 | Canonical | A platform-owned catalog server invoked with platform-held vendor credentials. |
| `MCP_SERVER_KIND_CUSTOM` | 3 | Canonical | A tenant-registered server invoked with the tenant's credentials. |
| `MCP_SERVER_KIND_EXTERNAL` | 4 | Canonical | A legacy externally configured server; this category does not designate a new tenant registration. |
| `MCP_SERVER_KIND_INTEGRATION` | 5 | Canonical | An account-connected 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)
Document: `DOC-API-MODEL-mcp-server-info`.
---
# MCPServerReference {#overview}
URL: https://docs.travila.ai/api/models/mcp-server-reference
MCP Server Reference
Lightweight reference to pre-configured MCP servers used by workflows
## Usage profiles {#fields}
| Usage | Fields and validation |
|---|---|
| In requests | [View fields](#request) |
| In responses | [View fields](#response) |
| In webhook payloads | [View fields](#webhook) |
## 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` | `integer (int32)` | Optional | Priority override for tool selection (higher = preferred). Minimum: -2147483648. Maximum: 2147483647. |
| `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. |
## 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` | `integer (int32)` | Optional | Priority override for tool selection (higher = preferred). Minimum: -2147483648. Maximum: 2147483647. |
| `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. |
## 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` |
## In webhook payloads {#webhook}
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
| `server_id` | `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` | `integer (int32)` | Optional | Priority override for tool selection (higher = preferred). Minimum: -2147483648. Maximum: 2147483647. |
| `allowlist_tool_patterns` | Array of `string` | Optional | Only include tools matching these patterns (e.g., "github_get_*", "search_*"). |
| `blocklist_tool_patterns` | Array of `string` | Optional | Exclude tools matching these patterns (e.g., "*_delete", "*_destroy"). |
| `server_overrides` | Map from string to `string` | Optional | Override server settings for this usage. |
## Request validation {#webhook-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 |
|---|---|---|
| `server_id` | 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` |
| [Update an agent profile](/api/agent-profiles/update-agent-profile) | `POST /api/v1/agent-profiles/update` |
| [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` |
| [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` |
| [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` |
| [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` |
| [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` |
| [llm.message_published](/api/events/llm-message-published) | Webhook JSON uses protobuf field names (snake_case). |
| [AgentProfile](/api/models/agent-profile#response) | Nested in model |
| [AgentProfile](/api/models/agent-profile#request) | Nested in model |
| [ConversationSettings](/api/models/conversation-settings#response) | Nested in model |
| [ConversationSettings](/api/models/conversation-settings#request) | Nested in model |
| [GenerationContext](/api/models/generation-context#response) | Nested in model |
| [GenerationContext](/api/models/generation-context#request) | Nested in model |
| [GenerationContext](/api/models/generation-context#webhook) | Nested in model |
Download the [public reference contract](/reference/api-contract.json).
- [agent-profiles OpenAPI](/agent-profiles.yaml)
- [conversations OpenAPI](/conversations.yaml)
Document: `DOC-API-MODEL-mcp-server-reference`.
---
# MCPServerStatus {#overview}
URL: https://docs.travila.ai/api/models/mcp-server-status
MCP Server Status
Status information about an MCP server (used in responses)
## 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. |
| `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 | Current connection status reported for the MCP server. |
| `toolsDiscovered` | `integer (int32)` | Optional | Number of tool definitions found during the last discovery. Minimum: -2147483648. Maximum: 2147483647. |
| `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 | Ownership of this server. Populated by ListAvailableServers for every source it merges. |
| `defaultEnabled` | `boolean` | Optional | Whether the built-in catalog recommends this server by default. This is a catalog recommendation, not whether the server is enabled for a particular profile or conversation. |
### 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` | 1 | Canonical | A connection to the MCP server is established. |
| `MCP_SERVER_CONNECTION_STATUS_DISCONNECTED` | 2 | Canonical | There is no active connection to the MCP server. |
| `MCP_SERVER_CONNECTION_STATUS_ERROR` | 3 | Canonical | A connection or discovery attempt encountered an error. |
| `MCP_SERVER_CONNECTION_STATUS_DISCOVERING` | 4 | 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.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `MCP_SERVER_KIND_INTERNAL` | 1 | Canonical | A server compiled into the deployment and dispatched in-process. |
| `MCP_SERVER_KIND_BUILT_IN` | 2 | Canonical | A platform-owned catalog server invoked with platform-held vendor credentials. |
| `MCP_SERVER_KIND_CUSTOM` | 3 | Canonical | A tenant-registered server invoked with the tenant's credentials. |
| `MCP_SERVER_KIND_EXTERNAL` | 4 | Canonical | A legacy externally configured server; this category does not designate a new tenant registration. |
| `MCP_SERVER_KIND_INTEGRATION` | 5 | Canonical | An account-connected 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)
Document: `DOC-API-MODEL-mcp-server-status`.
---
# PipedreamPageInfo {#overview}
URL: https://docs.travila.ai/api/models/pipedream-page-info
Pagination information returned in list responses
## 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` | `integer (int32)` | Optional | Items in current page. Minimum: -2147483648. Maximum: 2147483647. |
| `totalCount` | `integer (int32)` | Optional | Total items matching query. Minimum: -2147483648. Maximum: 2147483647. |
| `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)
Document: `DOC-API-MODEL-pipedream-page-info`.
---
# Resource {#overview}
URL: https://docs.travila.ai/api/models/resource
A resource exposed by an MCP server
## 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/content-part#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)
Document: `DOC-API-MODEL-resource`.
---
# MCP server selection {#overview}
URL: https://docs.travila.ai/api/tools/selection
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/mcp-server-reference#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/conversation-settings#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/agent-profile#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/conversation-settings#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/mcp-server-reference#request-field-allowlisttoolpatterns) and [`blocklistToolPatterns`](/api/models/mcp-server-reference#request-field-blocklisttoolpatterns) — glob patterns enforced at call time to control which of that server's tools the model may use.
---
# Event catalog {#event-catalog}
URL: https://docs.travila.ai/api/events
**Section:** `DOC-IN-webhooks-events#event-catalog`.
This reference defines outgoing webhook payloads, delivery headers and signature verification. Each event below has a dedicated schema and example page. Start with [Receive a completed order summary](/integrations/webhooks/endpoints) to build the customer workflow, or [Recover a missing backend update](/integrations/webhooks/deliveries) to investigate a delivery. Conversation streaming has a separate contract.
## Webhook events {#webhook-events}
**Section:** `DOC-IN-webhooks-events#webhook-events`.
Webhook events are delivered as HTTP POST requests to the endpoints and subscriptions you
manage via the [Webhook APIs](/api/webhooks).
### Delivery envelope {#delivery-envelope}
**Section:** `DOC-IN-webhooks-events#delivery-envelope`.
**The request body is the event payload itself** — there is no wrapper object. The body's
top-level keys are the payload fields listed under [Payload shapes](#payload-shapes)
(`event_context` plus the event's own fields), encoded as JSON with snake_case names — this
differs from the camelCase used by API responses.
The table and example below describe the documented timestamped-signature format. Confirm the actual header and signing configuration for your deployed endpoint before relying on it. The signed body contains the authoritative `event_context.event_name` and `event_context.event_id`; separate routing and deduplication headers are not covered by the documented body HMAC:
| Header | Description |
|--------|-------------|
| `X-Convoy-Event-Type` | The event type string, e.g. `llm.message_published` |
| `X-Convoy-Idempotency-Key` | `{event_id}:{endpoint_id}` — check against signed body identity and your configured endpoint before use |
| `X-Convoy-Signature` | `t={unix_seconds},v1={hex}` — see the verification procedure below |
An illustrative `llm.message_published` delivery in this format looks like this:
```http
POST /your-endpoint HTTP/1.1
Content-Type: application/json
X-Convoy-Event-Type: llm.message_published
X-Convoy-Idempotency-Key: d3b842c8-b19a-4205-a06f-c57cbf313582:01M0FJHPDVYYBA1V856RK6K91P
X-Convoy-Signature: t=1787229727,v1=050d3756a2953051bfb045490398894546c0d1a7c6fdf3c09d206fdeeeb92255
{
"event_context": { "event_name": "llm.message_published", "event_id": "d3b842c8-b19a-4205-a06f-c57cbf313582", "...": "..." },
"message": { "...": "..." }
}
```
After verifying the signature, route by signed `event_context.event_name` and
validate the expected schema and scope. Reject disagreement with
`X-Convoy-Event-Type`. Derive deduplication from signed `event_context.event_id`,
your configured endpoint and payload digest; reject a conflicting idempotency
header. A valid body signature does not authenticate arbitrary header replacements.
Verify the signature before processing the payload. The signing secret is the value returned
in the `secret` field when you call `list-endpoints` for the receiving endpoint.
In this format, `t` is the signing time in Unix seconds. `v1` is the **hex-encoded HMAC-SHA256** of the
string `{t},{raw_body}` — the timestamp, a comma, then the raw request body — computed with
the per-endpoint secret. Two details matter and are easy to get wrong: the signed input is
**not** the body alone, and the digest is **hex**, not base64.
Verify it before processing the payload. A missing or invalid signature cannot establish the sender's authenticity; reject the request and inspect the endpoint's configured format and secret through an authorized channel.
Use a verifier compatible with the signature format above, or implement all of these checks:
1. Bound header/body size and the number of signature fields. Parse safely; missing separators, invalid integers, repeated timestamp fields and malformed hex must reject without raising an unhandled error.
2. Require one signing timestamp and at least one supported version signature. Preserve multiple `v1` values during key rotation instead of overwriting them in a dictionary.
3. Enforce a bounded timestamp tolerance (five minutes is an example receiver setting), with an explicit clock-skew policy.
4. Compute HMAC-SHA256 over the original timestamp text, a comma and the raw body bytes. Compare equal-length decoded digests in constant time against the small configured set of current/overlap secrets. Never log those secrets or the signature.
5. After verification, enforce the expected scope and event schema. Derive type and event identity from signed `event_context.event_name` and `event_context.event_id`, bound to your configured endpoint. Reject conflicting type/idempotency headers: those separate headers are not covered by the body HMAC. Atomically persist the scoped event identity, payload digest and pending work before acknowledging. The timestamp tolerance limits old replays; it does not prevent duplicates within the window.
Pass the **raw request body bytes**, exactly as received. Re-serializing the parsed JSON
changes the bytes (key order, whitespace) and the signature will not match.
Five minutes is an example receiver tolerance, not a platform-imposed acceptance window. Choose and enforce a bounded policy appropriate to the receiver’s clock skew.
**Secret rotation:** the current public [update-endpoint operation](/api/webhooks/update-webhook-endpoint) changes the endpoint's name, URL and description. It does not accept a `secret` field, and there is no public secret-rotation operation. Do not use an endpoint-metadata update as evidence that a signing key changed. Qualify any separately supported rotation procedure for your deployment, including receiver overlap and signatures on new and retried deliveries, before relying on it.
### Event types {#event-types}
**Section:** `DOC-IN-webhooks-events#event-types`.
| Event | Owner | Direction | Emitted when |
|---|---|---|---|
| [`llm.message_published`](/api/events/llm-message-published) | Conversations | Travila → your endpoint (outgoing) | An assistant/tool message is produced or an assistant message snapshot is updated. |
| [`llm.generation_started`](/api/events/llm-generation-started) | Conversations | Travila → your endpoint (outgoing) | A generation run starts for a conversation. |
| [`llm.generation_completed`](/api/events/llm-generation-completed) | Conversations | Travila → your endpoint (outgoing) | A generation run reaches a terminal outcome. Inspect status and correlate run_id. |
| [`llm.tool_call_started`](/api/events/llm-tool-call-started) | Delegation and approvals | Travila → your endpoint (outgoing) | A tool call is dispatched for platform or client execution. |
| [`llm.tool_call_approval_required`](/api/events/llm-tool-call-approval-required) | Delegation and approvals | Travila → your endpoint (outgoing) | A routed tool call is parked for human approval with a decision deadline. |
| [`llm.tool_call_completed`](/api/events/llm-tool-call-completed) | Delegation and approvals | Travila → your endpoint (outgoing) | A tool call reaches a terminal outcome, including a rejected or timed-out approval. |
Subscribe only to what you act on. `llm.message_published` and `llm.generation_completed`
can both concern a normal assistant turn. Give them distinct lifecycle handlers and correlate their identities so they do not trigger the same business action twice.
### Payload shapes {#payload-shapes}
**Section:** `DOC-IN-webhooks-events#payload-shapes`.
Payload field names use snake_case.
#### `llm.message_published` {#llmmessage_published}
**Section:** `DOC-IN-webhooks-events#llmmessage_published`.
See [llm.message_published payload, example and producing operations](/api/events/llm-message-published).
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
| `event_context` | [EventContext](/api/models/event-context#webhook) | Optional | Event provenance and routing metadata associated with the emitted event. |
| `message` | [Message](/api/models/message#webhook) | Optional | The generated assistant/tool message |
Full payload: [LLMMessagePublishedEvent](/api/models/llm-message-published-event#webhook).
#### `llm.generation_started` {#llmgeneration_started}
**Section:** `DOC-IN-webhooks-events#llmgeneration_started`.
See [llm.generation_started payload, example and producing operations](/api/events/llm-generation-started).
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
| `event_context` | [EventContext](/api/models/event-context#webhook) | Optional | Event provenance and routing metadata associated with the emitted event. |
| `run_id` | `string` | Optional | Unique identifier for the workflow run |
| `config` | [GenerationConfig](/api/models/generation-config#webhook) | Optional | Optional snapshot of generation configuration used for this run |
| `starting_sequence` | `string (int64)` | Optional | Conversation sequence number at the moment the run started (if known) Pattern: ^-?\d+$. |
Full payload: [LLMGenerationStartedEvent](/api/models/llm-generation-started-event#webhook).
#### `llm.generation_completed` {#llmgeneration_completed}
**Section:** `DOC-IN-webhooks-events#llmgeneration_completed`.
See [llm.generation_completed payload, example and producing operations](/api/events/llm-generation-completed).
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
| `event_context` | [EventContext](/api/models/event-context#webhook) | Optional | Event provenance and routing metadata associated with the emitted event. |
| `run_id` | `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 | Terminal status of the run |
| `loop_count` | `integer (int32)` | Optional | Number of agent loops/steps executed Minimum: -2147483648. Maximum: 2147483647. |
| `duration_ms` | `string (int64)` | Optional | End-to-end run duration in milliseconds Pattern: ^-?\d+$. |
| `usage` | [Usage](/api/models/usage#webhook) | Optional | Optional usage accounting for the run |
| `error` | [RpcError](/api/models/rpc-error#webhook) | Optional | Structured error for FAILED/TIMED_OUT/CANCELED runs. |
| `usage_by_model` | Array of [UsageByModel](/api/models/usage-by-model#webhook) | 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. |
| `turn_key` | `string` | Optional | Identifies the conversation turn this run served: the message_id of the opening user message, resolved once at run start and stamped on every message the run emits as Message.source_user_message_id. Empty when the producer predates this field, or when the turn is unresolvable — never guess one, an empty key means "no turn attribution". |
##### Values of `status` {#llm-generation-completed-values-status}
Lifecycle state of a workflow execution, distinct from the reason a terminal execution ended.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `WORKFLOW_STATUS_RUNNING` | 1 | Canonical | The workflow has started and has not reached a terminal outcome. |
| `WORKFLOW_STATUS_COMPLETED` | 2 | Canonical | The workflow finished successfully. |
| `WORKFLOW_STATUS_FAILED` | 3 | Canonical | The workflow ended because execution failed; inspect its error or end reason. |
| `WORKFLOW_STATUS_TIMED_OUT` | 4 | Canonical | The workflow ended because its execution time limit elapsed. |
| `WORKFLOW_STATUS_CANCELED` | 5 | Canonical | The workflow was cancelled before normal completion. This enum retains its existing CANCELED wire spelling. |
Full payload: [LLMGenerationCompletedEvent](/api/models/llm-generation-completed-event#webhook).
#### `llm.tool_call_started` {#llmtool_call_started}
**Section:** `DOC-IN-webhooks-events#llmtool_call_started`.
See [llm.tool_call_started payload, example and producing operations](/api/events/llm-tool-call-started).
Fires when a tool call is dispatched — both for tools the platform runs itself and for
[client-side tools](/managed-agents/delegation-approvals/using-tools#client-side-tools), which are dispatched to you.
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
| `event_context` | [EventContext](/api/models/event-context#webhook) | Optional | Event provenance and routing metadata associated with the emitted event. |
| `tool_call` | [ToolCall](/api/models/tool-call#webhook) | 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. |
Full payload: [ToolCallStartedEvent](/api/models/tool-call-started-event#webhook).
`tool_call.status` is always `TOOL_EXECUTION_STATUS_EXECUTING` here: the event says what was
dispatched, not what came back.
For a client-side tool the run is parked on **you** from this moment, exactly as
`llm.tool_call_approval_required` parks it on an approver. The payload does not carry a flag
distinguishing the two kinds, so match on the tool names you declared in `clientTools` — those
are the only ones you are expected to run. It also does not carry the answer deadline; read
`clientToolDeadlineAt` from
[`list-pending-client-tools`](/api/conversations/list-pending-client-tools) when you need it.
#### `llm.tool_call_completed` {#llmtool_call_completed}
**Section:** `DOC-IN-webhooks-events#llmtool_call_completed`.
See [llm.tool_call_completed payload, example and producing operations](/api/events/llm-tool-call-completed).
Fires when a tool call reaches a terminal state — a result you submitted, a result the platform
produced, or a timeout.
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
| `event_context` | [EventContext](/api/models/event-context#webhook) | Optional | Event provenance and routing metadata associated with the emitted event. |
| `tool_call` | [ToolCall](/api/models/tool-call#webhook) | Optional | Final tool call: status is terminal (SUCCESS|FAILED|CANCELLED|TIMED_OUT), result_json populated. |
| `execution_time_ms` | `integer (int32)` | Optional | Wall-clock execution time in milliseconds (0 when unknown, e.g. dispatch error). Minimum: -2147483648. Maximum: 2147483647. |
Full payload: [ToolCallCompletedEvent](/api/models/tool-call-completed-event#webhook).
#### `llm.tool_call_approval_required` {#llmtool_call_approval_required}
**Section:** `DOC-IN-webhooks-events#llmtool_call_approval_required`.
See [llm.tool_call_approval_required payload, example and producing operations](/api/events/llm-tool-call-approval-required).
A routed tool call is waiting for human approval. This event uses the same native payload
shape as `llm.tool_call_started`; the signed event name and tool-call status distinguish them.
The call has `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` and a `requires_approval_at` decision deadline.
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
| `event_context` | [EventContext](/api/models/event-context#webhook) | Optional | Event provenance and routing metadata associated with the emitted event. |
| `tool_call` | [ToolCall](/api/models/tool-call#webhook) | 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. |
Full payload: [ToolCallStartedEvent](/api/models/tool-call-started-event#webhook).
Use [`list-pending-approvals`](/api/conversations/list-pending-approvals) to reconcile calls
awaiting a decision, and [`submit-tool-approvals`](/api/conversations/submit-tool-approvals)
to resolve them. A pending call waits for a decision or its deadline; other calls
may proceed under the MIXED policy. Treat a missing deadline as unknown and decide
promptly, rather than assuming the call can wait indefinitely.
---
## Conversation updates {#conversation-updates}
**Section:** `DOC-IN-webhooks-events#conversation-updates`.
This catalog describes outgoing webhooks; it does not define an incoming-webhook endpoint. [Scheduled callbacks](/api/scheduled-jobs/callbacks#callback-envelope) send the payload configured on the schedule and use a separate signed-token protocol. They do not share these event payload schemas.
Conversation updates have separate delivery and recovery rules from webhooks. See [streaming availability](/managed-agents/conversations/streaming), [event interpretation](/managed-agents/conversations/streaming/payloads) and [reconnection requirements](/managed-agents/conversations/streaming/subscribing). Never substitute a conversation activity sequence for a message sequence or treat an idle conversation as proof that a particular run completed.
Document ID: `DOC-IN-webhooks-events`. Section identities and revisions.
---
# Endpoint {#overview}
URL: https://docs.travila.ai/api/models/endpoint
Provider record describing a webhook delivery destination and its delivery settings.
## 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 associated with the resource or outbound request. |
| `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 | Current state of the webhook endpoint. |
| `secret` | `string` | Optional | Secret associated with the webhook endpoint or deployed trigger. |
| `httpTimeout` | `integer (int32)` | Optional | Timeout for an individual webhook HTTP delivery, in seconds. Minimum: -2147483648. Maximum: 2147483647. |
| `rateLimit` | `integer (int32)` | Optional | Maximum delivery rate configured for the webhook endpoint. Minimum: -2147483648. Maximum: 2147483647. |
| `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}
Lifecycle condition reported for a webhook delivery endpoint.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `ENDPOINT_STATUS_ACTIVE` | 1 | Canonical | The endpoint is marked active for webhook delivery. |
| `ENDPOINT_STATUS_INACTIVE` | 2 | Canonical | The endpoint is marked inactive by the delivery backend. |
| `ENDPOINT_STATUS_PAUSED` | 3 | Canonical | Delivery to the endpoint is paused. |
| `ENDPOINT_STATUS_PENDING` | 4 | 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)
Document: `DOC-API-MODEL-endpoint`.
---
# EventDelivery {#overview}
URL: https://docs.travila.ai/api/models/event-delivery
Delivery-attempt state and response information for a webhook event.
## 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 | Current delivery status reported for this webhook event attempt. |
| `attempts` | `integer (int32)` | Optional | Number of delivery attempts reported for the webhook event. Minimum: -2147483648. Maximum: 2147483647. |
| `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` | `integer (int32)` | Optional | HTTP response status reported for the delivery attempt. Minimum: -2147483648. Maximum: 2147483647. |
| `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}
Delivery-backend state of a webhook event sent to an endpoint.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `DELIVERY_STATUS_SCHEDULED` | 1 | Canonical | The delivery is scheduled and waiting for processing. |
| `DELIVERY_STATUS_PROCESSING` | 2 | Canonical | The delivery backend is processing a delivery attempt. |
| `DELIVERY_STATUS_COMPLETED` | 3 | Canonical | The webhook delivery completed successfully. |
| `DELIVERY_STATUS_RETRY` | 4 | Canonical | The delivery is awaiting another attempt after a retryable failure. |
| `DELIVERY_STATUS_FAILED` | 5 | Canonical | The delivery is reported as failed by the backend. |
| `DELIVERY_STATUS_DISCARDED` | 6 | Canonical | The delivery backend discarded the event instead of completing delivery. |
## 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)
Document: `DOC-API-MODEL-event-delivery`.
---
# LLMGenerationCompletedEvent {#overview}
URL: https://docs.travila.ai/api/models/llm-generation-completed-event
Event emitted when a generation run reaches a terminal state. The event context identifies the
associated conversation.
## Usage profiles {#fields}
| Usage | Fields and validation |
|---|---|
| In webhook payloads | [View fields](#webhook) |
## In webhook payloads {#webhook}
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
| `event_context` | [EventContext](/api/models/event-context#webhook) | Optional | Event provenance and routing metadata associated with the emitted event. |
| `run_id` | `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 | Terminal status of the run |
| `loop_count` | `integer (int32)` | Optional | Number of agent loops/steps executed Minimum: -2147483648. Maximum: 2147483647. |
| `duration_ms` | `string (int64)` | Optional | End-to-end run duration in milliseconds Pattern: ^-?\d+$. |
| `usage` | [Usage](/api/models/usage#webhook) | Optional | Optional usage accounting for the run |
| `error` | [RpcError](/api/models/rpc-error#webhook) | Optional | Structured error for FAILED/TIMED_OUT/CANCELED runs. |
| `usage_by_model` | Array of [UsageByModel](/api/models/usage-by-model#webhook) | 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. |
| `turn_key` | `string` | Optional | Identifies the conversation turn this run served: the message_id of the opening user message, resolved once at run start and stamped on every message the run emits as Message.source_user_message_id. Empty when the producer predates this field, or when the turn is unresolvable — never guess one, an empty key means "no turn attribution". |
### Values of `status` {#webhook-values-status}
Lifecycle state of a workflow execution, distinct from the reason a terminal execution ended.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `WORKFLOW_STATUS_RUNNING` | 1 | Canonical | The workflow has started and has not reached a terminal outcome. |
| `WORKFLOW_STATUS_COMPLETED` | 2 | Canonical | The workflow finished successfully. |
| `WORKFLOW_STATUS_FAILED` | 3 | Canonical | The workflow ended because execution failed; inspect its error or end reason. |
| `WORKFLOW_STATUS_TIMED_OUT` | 4 | Canonical | The workflow ended because its execution time limit elapsed. |
| `WORKFLOW_STATUS_CANCELED` | 5 | Canonical | The workflow was cancelled before normal completion. This enum retains its existing CANCELED wire spelling. |
## Where used {#where-used}
| Reference | Relationship |
|---|---|
| [llm.generation_completed](/api/events/llm-generation-completed) | Webhook JSON uses protobuf field names (snake_case). |
Download the [public reference contract](/reference/api-contract.json).
Document: `DOC-API-MODEL-llm-generation-completed-event`.
---
# LLMGenerationStartedEvent {#overview}
URL: https://docs.travila.ai/api/models/llm-generation-started-event
Event emitted when a generation run starts. The event context identifies the associated
conversation.
## Usage profiles {#fields}
| Usage | Fields and validation |
|---|---|
| In webhook payloads | [View fields](#webhook) |
## In webhook payloads {#webhook}
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
| `event_context` | [EventContext](/api/models/event-context#webhook) | Optional | Event provenance and routing metadata associated with the emitted event. |
| `run_id` | `string` | Optional | Unique identifier for the workflow run |
| `config` | [GenerationConfig](/api/models/generation-config#webhook) | Optional | Optional snapshot of generation configuration used for this run |
| `starting_sequence` | `string (int64)` | Optional | Conversation sequence number at the moment the run started (if known) Pattern: ^-?\d+$. |
## Where used {#where-used}
| Reference | Relationship |
|---|---|
| [llm.generation_started](/api/events/llm-generation-started) | Webhook JSON uses protobuf field names (snake_case). |
Download the [public reference contract](/reference/api-contract.json).
Document: `DOC-API-MODEL-llm-generation-started-event`.
---
# LLMMessagePublishedEvent {#overview}
URL: https://docs.travila.ai/api/models/llm-message-published-event
Domain event published when a new assistant/tool message is produced.
## Usage profiles {#fields}
| Usage | Fields and validation |
|---|---|
| In webhook payloads | [View fields](#webhook) |
## In webhook payloads {#webhook}
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
| `event_context` | [EventContext](/api/models/event-context#webhook) | Optional | Event provenance and routing metadata associated with the emitted event. |
| `message` | [Message](/api/models/message#webhook) | Optional | The generated assistant/tool message |
## Where used {#where-used}
| Reference | Relationship |
|---|---|
| [llm.message_published](/api/events/llm-message-published) | Webhook JSON uses protobuf field names (snake_case). |
Download the [public reference contract](/reference/api-contract.json).
Document: `DOC-API-MODEL-llm-message-published-event`.
---
# PaginationInfo {#overview}
URL: https://docs.travila.ai/api/models/pagination-info
Page position and aggregate counts accompanying a paginated provider listing.
## 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` | `integer (int32)` | Optional | Total number of entries reported by the listing. Minimum: -2147483648. Maximum: 2147483647. |
| `page` | `integer (int32)` | Optional | Page number used by this listing operation. Minimum: -2147483648. Maximum: 2147483647. |
| `perPage` | `integer (int32)` | Optional | Number of entries requested per page. Minimum: -2147483648. Maximum: 2147483647. |
| `totalPages` | `integer (int32)` | Optional | Total number of pages reported for the current query. Minimum: -2147483648. Maximum: 2147483647. |
## 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)
Document: `DOC-API-MODEL-pagination-info`.
---
# RetryConfig {#overview}
URL: https://docs.travila.ai/api/models/retry-config
Retry strategy, attempt limit, and interval for failed webhook deliveries.
## 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 | Webhook retry strategy selected in the provider configuration. |
| `retryCount` | `integer (int32)` | Optional | Maximum retry count configured for webhook delivery. Minimum: -2147483648. Maximum: 2147483647. |
| `intervalSeconds` | `integer (int32)` | Optional | Delay between webhook delivery retries, in seconds. Minimum: -2147483648. Maximum: 2147483647. |
### Values of `strategy` {#response-values-strategy}
Backoff strategy applied between webhook delivery attempts.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `RETRY_STRATEGY_LINEAR` | 1 | Canonical | Retry using the configured linear interval strategy. |
| `RETRY_STRATEGY_EXPONENTIAL` | 2 | 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` |
| [Subscription](/api/models/subscription#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json).
- [webhooks OpenAPI](/webhooks.yaml)
Document: `DOC-API-MODEL-retry-config`.
---
# SubscriptionFilter {#overview}
URL: https://docs.travila.ai/api/models/subscription-filter
Event-body and header conditions selecting webhook events for a subscription.
## 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` |
| [Subscription](/api/models/subscription#response) | Nested in model |
Download the [public reference contract](/reference/api-contract.json).
- [webhooks OpenAPI](/webhooks.yaml)
Document: `DOC-API-MODEL-subscription-filter`.
---
# Subscription {#overview}
URL: https://docs.travila.ai/api/models/subscription
Webhook event selection and retry settings associated with an endpoint.
## 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/subscription-filter#response) | Optional | Selection criteria applied to the listing. |
| `retryConfig` | [RetryConfig](/api/models/retry-config#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. |
## 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)
Document: `DOC-API-MODEL-subscription`.
---
# ToolCallCompletedEvent {#overview}
URL: https://docs.travila.ai/api/models/tool-call-completed-event
Event emitted when a tool call reaches COMPLETED, FAILED, CANCELLED or TIMED_OUT, including
calls that required human approval.
## Usage profiles {#fields}
| Usage | Fields and validation |
|---|---|
| In webhook payloads | [View fields](#webhook) |
## In webhook payloads {#webhook}
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
| `event_context` | [EventContext](/api/models/event-context#webhook) | Optional | Event provenance and routing metadata associated with the emitted event. |
| `tool_call` | [ToolCall](/api/models/tool-call#webhook) | Optional | Final tool call: status is terminal (SUCCESS|FAILED|CANCELLED|TIMED_OUT), result_json populated. |
| `execution_time_ms` | `integer (int32)` | Optional | Wall-clock execution time in milliseconds (0 when unknown, e.g. dispatch error). Minimum: -2147483648. Maximum: 2147483647. |
## Where used {#where-used}
| Reference | Relationship |
|---|---|
| [llm.tool_call_completed](/api/events/llm-tool-call-completed) | Webhook JSON uses protobuf field names (snake_case). |
Download the [public reference contract](/reference/api-contract.json).
Document: `DOC-API-MODEL-tool-call-completed-event`.
---
# ToolCallStartedEvent {#overview}
URL: https://docs.travila.ai/api/models/tool-call-started-event
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.
## Usage profiles {#fields}
| Usage | Fields and validation |
|---|---|
| In webhook payloads | [View fields](#webhook) |
## In webhook payloads {#webhook}
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
| `event_context` | [EventContext](/api/models/event-context#webhook) | Optional | Event provenance and routing metadata associated with the emitted event. |
| `tool_call` | [ToolCall](/api/models/tool-call#webhook) | 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. |
## Where used {#where-used}
| Reference | Relationship |
|---|---|
| [llm.tool_call_approval_required](/api/events/llm-tool-call-approval-required) | Webhook JSON uses protobuf field names (snake_case). |
| [llm.tool_call_started](/api/events/llm-tool-call-started) | Webhook JSON uses protobuf field names (snake_case). |
Download the [public reference contract](/reference/api-contract.json).
Document: `DOC-API-MODEL-tool-call-started-event`.
---
# llm.generation_completed {#overview}
URL: https://docs.travila.ai/api/events/llm-generation-completed
A generation run reaches a terminal outcome. Inspect status and correlate run_id.
**Owner:** [Conversations](/managed-agents/conversations). **Direction:** Travila → your endpoint (outgoing).
The receiver gets an HTTP POST webhook request whose body is the event payload itself. JSON uses protobuf field names (snake_case). See [delivery headers and signature verification](/api/events#delivery-envelope) before accepting it.
## Operations that can produce this event {#producer-operations}
These operations can start the generation workflow that emits this event. Receiving a successful API response does not establish that every event will be produced or delivered.
- [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`
## Payload fields {#fields}
| Field | Type | Presence | Meaning |
|---|---|---|---|
| `event_context` | [EventContext](/api/models/event-context#webhook) | Optional | Event provenance and routing metadata associated with the emitted event. |
| `run_id` | `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 | Terminal status of the run |
| `loop_count` | `integer (int32)` | Optional | Number of agent loops/steps executed Minimum: -2147483648. Maximum: 2147483647. |
| `duration_ms` | `string (int64)` | Optional | End-to-end run duration in milliseconds Pattern: ^-?\d+$. |
| `usage` | [Usage](/api/models/usage#webhook) | Optional | Optional usage accounting for the run |
| `error` | [RpcError](/api/models/rpc-error#webhook) | Optional | Structured error for FAILED/TIMED_OUT/CANCELED runs. |
| `usage_by_model` | Array of [UsageByModel](/api/models/usage-by-model#webhook) | 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. |
| `turn_key` | `string` | Optional | Identifies the conversation turn this run served: the message_id of the opening user message, resolved once at run start and stamped on every message the run emits as Message.source_user_message_id. Empty when the producer predates this field, or when the turn is unresolvable — never guess one, an empty key means "no turn attribution". |
### Values of `status` {#values-status}
Lifecycle state of a workflow execution, distinct from the reason a terminal execution ended.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `WORKFLOW_STATUS_RUNNING` | 1 | Canonical | The workflow has started and has not reached a terminal outcome. |
| `WORKFLOW_STATUS_COMPLETED` | 2 | Canonical | The workflow finished successfully. |
| `WORKFLOW_STATUS_FAILED` | 3 | Canonical | The workflow ended because execution failed; inspect its error or end reason. |
| `WORKFLOW_STATUS_TIMED_OUT` | 4 | Canonical | The workflow ended because its execution time limit elapsed. |
| `WORKFLOW_STATUS_CANCELED` | 5 | Canonical | The workflow was cancelled before normal completion. This enum retains its existing CANCELED wire spelling. |
Full payload model: [LLMGenerationCompletedEvent](/api/models/llm-generation-completed-event#webhook).
## Example {#example}
Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event.
```json
{
"event_context": {
"event_name": "llm.generation_completed",
"version": "1.0",
"event_id": "d3b842c8-b19a-4205-a06f-c57cbf313582",
"correlation_id": "9d4c2e1f-27b1-4304-ae54-af7fe876df31",
"emitted_at": "2026-09-16T12:00:00Z",
"caller_key": "tenant-demo:b81d5345-c1f9-4fb9-b558-a6327c75b842",
"tenant_id": "tenant-demo",
"project_id": "default"
},
"run_id": "9d4c2e1f-27b1-4304-ae54-af7fe876df31",
"status": "WORKFLOW_STATUS_COMPLETED",
"loop_count": 1,
"duration_ms": "1250",
"usage": {
"prompt_tokens": 412,
"completion_tokens": 88,
"total_tokens": 500
}
}
```
## Related payloads and delivery {#related}
- [Event context and identity](/api/models/event-context#webhook)
- [Webhook event catalog and signing](/api/events)
- [Receive and process events](/integrations/webhooks/endpoints)
- [Recover a failed delivery](/integrations/webhooks/deliveries)
Download the [public reference contract](/reference/api-contract.json) for this event schema and its named example.
Document: `DOC-API-EVENT-llm-generation-completed`.
---
# llm.generation_started {#overview}
URL: https://docs.travila.ai/api/events/llm-generation-started
A generation run starts for a conversation.
**Owner:** [Conversations](/managed-agents/conversations). **Direction:** Travila → your endpoint (outgoing).
The receiver gets an HTTP POST webhook request whose body is the event payload itself. JSON uses protobuf field names (snake_case). See [delivery headers and signature verification](/api/events#delivery-envelope) before accepting it.
## Operations that can produce this event {#producer-operations}
These operations can start the generation workflow that emits this event. Receiving a successful API response does not establish that every event will be produced or delivered.
- [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`
## Payload fields {#fields}
| Field | Type | Presence | Meaning |
|---|---|---|---|
| `event_context` | [EventContext](/api/models/event-context#webhook) | Optional | Event provenance and routing metadata associated with the emitted event. |
| `run_id` | `string` | Optional | Unique identifier for the workflow run |
| `config` | [GenerationConfig](/api/models/generation-config#webhook) | Optional | Optional snapshot of generation configuration used for this run |
| `starting_sequence` | `string (int64)` | Optional | Conversation sequence number at the moment the run started (if known) Pattern: ^-?\d+$. |
Full payload model: [LLMGenerationStartedEvent](/api/models/llm-generation-started-event#webhook).
## Example {#example}
Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event.
```json
{
"event_context": {
"event_name": "llm.generation_started",
"version": "1.0",
"event_id": "d3b842c8-b19a-4205-a06f-c57cbf313581",
"correlation_id": "9d4c2e1f-27b1-4304-ae54-af7fe876df31",
"emitted_at": "2026-09-16T12:00:00Z",
"caller_key": "tenant-demo:b81d5345-c1f9-4fb9-b558-a6327c75b842",
"tenant_id": "tenant-demo",
"project_id": "default"
},
"run_id": "9d4c2e1f-27b1-4304-ae54-af7fe876df31",
"starting_sequence": "1"
}
```
## Related payloads and delivery {#related}
- [Event context and identity](/api/models/event-context#webhook)
- [Webhook event catalog and signing](/api/events)
- [Receive and process events](/integrations/webhooks/endpoints)
- [Recover a failed delivery](/integrations/webhooks/deliveries)
Download the [public reference contract](/reference/api-contract.json) for this event schema and its named example.
Document: `DOC-API-EVENT-llm-generation-started`.
---
# llm.message_published {#overview}
URL: https://docs.travila.ai/api/events/llm-message-published
An assistant/tool message is produced or an assistant message snapshot is updated.
**Owner:** [Conversations](/managed-agents/conversations). **Direction:** Travila → your endpoint (outgoing).
The receiver gets an HTTP POST webhook request whose body is the event payload itself. JSON uses protobuf field names (snake_case). See [delivery headers and signature verification](/api/events#delivery-envelope) before accepting it.
## Operations that can produce this event {#producer-operations}
These operations can start the generation workflow that emits this event. Receiving a successful API response does not establish that every event will be produced or delivered.
- [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`
## Payload fields {#fields}
| Field | Type | Presence | Meaning |
|---|---|---|---|
| `event_context` | [EventContext](/api/models/event-context#webhook) | Optional | Event provenance and routing metadata associated with the emitted event. |
| `message` | [Message](/api/models/message#webhook) | Optional | The generated assistant/tool message |
Full payload model: [LLMMessagePublishedEvent](/api/models/llm-message-published-event#webhook).
## Example {#example}
Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event.
```json
{
"event_context": {
"event_name": "llm.message_published",
"version": "1.0",
"event_id": "d3b842c8-b19a-4205-a06f-c57cbf313580",
"correlation_id": "9d4c2e1f-27b1-4304-ae54-af7fe876df31",
"emitted_at": "2026-09-16T12:00:00Z",
"caller_key": "tenant-demo:b81d5345-c1f9-4fb9-b558-a6327c75b842",
"tenant_id": "tenant-demo",
"project_id": "default"
},
"message": {
"role": "ROLE_ASSISTANT",
"content": [
{
"type": "CONTENT_PART_TYPE_TEXT",
"content": "Here is your daily briefing."
}
],
"message_id": "924ad207-f757-4b1f-bf41-8344ce32dd01",
"sequence": "2",
"generated_by": "9d4c2e1f-27b1-4304-ae54-af7fe876df31"
}
}
```
## Related payloads and delivery {#related}
- [Event context and identity](/api/models/event-context#webhook)
- [Webhook event catalog and signing](/api/events)
- [Receive and process events](/integrations/webhooks/endpoints)
- [Recover a failed delivery](/integrations/webhooks/deliveries)
Download the [public reference contract](/reference/api-contract.json) for this event schema and its named example.
Document: `DOC-API-EVENT-llm-message-published`.
---
# llm.tool_call_approval_required {#overview}
URL: https://docs.travila.ai/api/events/llm-tool-call-approval-required
A routed tool call is parked for human approval with a decision deadline.
**Owner:** [Delegation and approvals](/api/tool-execution/policies). **Direction:** Travila → your endpoint (outgoing).
The receiver gets an HTTP POST webhook request whose body is the event payload itself. JSON uses protobuf field names (snake_case). See [delivery headers and signature verification](/api/events#delivery-envelope) before accepting it.
## Operations that can produce this event {#producer-operations}
These operations can start the generation workflow that emits this event. Receiving a successful API response does not establish that every event will be produced or delivered.
- [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`
## Payload fields {#fields}
| Field | Type | Presence | Meaning |
|---|---|---|---|
| `event_context` | [EventContext](/api/models/event-context#webhook) | Optional | Event provenance and routing metadata associated with the emitted event. |
| `tool_call` | [ToolCall](/api/models/tool-call#webhook) | 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. |
Full payload model: [ToolCallStartedEvent](/api/models/tool-call-started-event#webhook).
## Example {#example}
Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event.
```json
{
"event_context": {
"event_name": "llm.tool_call_approval_required",
"version": "1.0",
"event_id": "d3b842c8-b19a-4205-a06f-c57cbf313584",
"correlation_id": "9d4c2e1f-27b1-4304-ae54-af7fe876df31",
"emitted_at": "2026-09-16T12:00:00Z",
"caller_key": "tenant-demo:b81d5345-c1f9-4fb9-b558-a6327c75b842",
"tenant_id": "tenant-demo",
"project_id": "default"
},
"tool_call": {
"id": "call_123",
"name": "send_briefing",
"server_id": "briefing-tools",
"arguments_json": {
"conversation_id": "b81d5345-c1f9-4fb9-b558-a6327c75b842"
},
"status": "TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION",
"requires_approval_at": "2026-09-16T12:05:00Z"
}
}
```
The tool call has not been dispatched. Its status is `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION`, and `requires_approval_at` is the decision deadline. Reconcile with [pending approvals](/api/conversations/list-pending-approvals), then use [submit tool approvals](/api/conversations/submit-tool-approvals).
## Related payloads and delivery {#related}
- [Event context and identity](/api/models/event-context#webhook)
- [Webhook event catalog and signing](/api/events)
- [Receive and process events](/integrations/webhooks/endpoints)
- [Recover a failed delivery](/integrations/webhooks/deliveries)
Download the [public reference contract](/reference/api-contract.json) for this event schema and its named example.
Document: `DOC-API-EVENT-llm-tool-call-approval-required`.
---
# llm.tool_call_completed {#overview}
URL: https://docs.travila.ai/api/events/llm-tool-call-completed
A tool call reaches a terminal outcome, including a rejected or timed-out approval.
**Owner:** [Delegation and approvals](/api/tool-execution/policies). **Direction:** Travila → your endpoint (outgoing).
The receiver gets an HTTP POST webhook request whose body is the event payload itself. JSON uses protobuf field names (snake_case). See [delivery headers and signature verification](/api/events#delivery-envelope) before accepting it.
## Operations that can produce this event {#producer-operations}
These operations can start the generation workflow that emits this event. Receiving a successful API response does not establish that every event will be produced or delivered.
- [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`
## Payload fields {#fields}
| Field | Type | Presence | Meaning |
|---|---|---|---|
| `event_context` | [EventContext](/api/models/event-context#webhook) | Optional | Event provenance and routing metadata associated with the emitted event. |
| `tool_call` | [ToolCall](/api/models/tool-call#webhook) | Optional | Final tool call: status is terminal (SUCCESS|FAILED|CANCELLED|TIMED_OUT), result_json populated. |
| `execution_time_ms` | `integer (int32)` | Optional | Wall-clock execution time in milliseconds (0 when unknown, e.g. dispatch error). Minimum: -2147483648. Maximum: 2147483647. |
Full payload model: [ToolCallCompletedEvent](/api/models/tool-call-completed-event#webhook).
## Example {#example}
Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event.
```json
{
"event_context": {
"event_name": "llm.tool_call_completed",
"version": "1.0",
"event_id": "d3b842c8-b19a-4205-a06f-c57cbf313585",
"correlation_id": "9d4c2e1f-27b1-4304-ae54-af7fe876df31",
"emitted_at": "2026-09-16T12:00:00Z",
"caller_key": "tenant-demo:b81d5345-c1f9-4fb9-b558-a6327c75b842",
"tenant_id": "tenant-demo",
"project_id": "default"
},
"execution_time_ms": 240,
"tool_call": {
"id": "call_123",
"name": "send_briefing",
"server_id": "briefing-tools",
"arguments_json": {
"conversation_id": "b81d5345-c1f9-4fb9-b558-a6327c75b842"
},
"status": "TOOL_EXECUTION_STATUS_COMPLETED",
"result_json": {
"accepted": true
}
}
}
```
## Related payloads and delivery {#related}
- [Event context and identity](/api/models/event-context#webhook)
- [Webhook event catalog and signing](/api/events)
- [Receive and process events](/integrations/webhooks/endpoints)
- [Recover a failed delivery](/integrations/webhooks/deliveries)
Download the [public reference contract](/reference/api-contract.json) for this event schema and its named example.
Document: `DOC-API-EVENT-llm-tool-call-completed`.
---
# llm.tool_call_started {#overview}
URL: https://docs.travila.ai/api/events/llm-tool-call-started
A tool call is dispatched for platform or client execution.
**Owner:** [Delegation and approvals](/api/tool-execution/policies). **Direction:** Travila → your endpoint (outgoing).
The receiver gets an HTTP POST webhook request whose body is the event payload itself. JSON uses protobuf field names (snake_case). See [delivery headers and signature verification](/api/events#delivery-envelope) before accepting it.
## Operations that can produce this event {#producer-operations}
These operations can start the generation workflow that emits this event. Receiving a successful API response does not establish that every event will be produced or delivered.
- [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`
## Payload fields {#fields}
| Field | Type | Presence | Meaning |
|---|---|---|---|
| `event_context` | [EventContext](/api/models/event-context#webhook) | Optional | Event provenance and routing metadata associated with the emitted event. |
| `tool_call` | [ToolCall](/api/models/tool-call#webhook) | 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. |
Full payload model: [ToolCallStartedEvent](/api/models/tool-call-started-event#webhook).
## Example {#example}
Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event.
```json
{
"event_context": {
"event_name": "llm.tool_call_started",
"version": "1.0",
"event_id": "d3b842c8-b19a-4205-a06f-c57cbf313583",
"correlation_id": "9d4c2e1f-27b1-4304-ae54-af7fe876df31",
"emitted_at": "2026-09-16T12:00:00Z",
"caller_key": "tenant-demo:b81d5345-c1f9-4fb9-b558-a6327c75b842",
"tenant_id": "tenant-demo",
"project_id": "default"
},
"tool_call": {
"id": "call_123",
"name": "send_briefing",
"server_id": "briefing-tools",
"arguments_json": {
"conversation_id": "b81d5345-c1f9-4fb9-b558-a6327c75b842"
},
"status": "TOOL_EXECUTION_STATUS_EXECUTING"
}
}
```
This snapshot reports an executing call. Match client-side calls to the tool names you registered; this payload does not supply a client-tool deadline. Read the current pending-client-tool state before execution.
## Related payloads and delivery {#related}
- [Event context and identity](/api/models/event-context#webhook)
- [Webhook event catalog and signing](/api/events)
- [Receive and process events](/integrations/webhooks/endpoints)
- [Recover a failed delivery](/integrations/webhooks/deliveries)
Download the [public reference contract](/reference/api-contract.json) for this event schema and its named example.
Document: `DOC-API-EVENT-llm-tool-call-started`.
---
# 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.
## 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.
**name** `string` **required**
Display name of the tenant’s webhook delivery destination.
Minimum length: 1
**url** `string(uri)` **required**
URL associated with the resource or outbound request.
**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/endpoint#response).
**id** `string`
Identifier of the endpoint record.
**name** `string`
Display name of the webhook delivery destination.
**url** `string`
URL associated with the resource or outbound request.
**description** `string`
Human-readable description of the resource.
**status** `any`
Current state of the webhook endpoint.
Lifecycle condition reported for a webhook delivery endpoint.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `ENDPOINT_STATUS_ACTIVE` | 1 | Canonical | The endpoint is marked active for webhook delivery. |
| `ENDPOINT_STATUS_INACTIVE` | 2 | Canonical | The endpoint is marked inactive by the delivery backend. |
| `ENDPOINT_STATUS_PAUSED` | 3 | Canonical | Delivery to the endpoint is paused. |
| `ENDPOINT_STATUS_PENDING` | 4 | 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)`
Must not match:
Type: `any`
Enum: `0`
**secret** `string`
Secret associated with the webhook endpoint or deployed trigger.
**httpTimeout** `integer(int32)`
Timeout for an individual webhook HTTP delivery, in seconds.
Minimum: -2147483648
Maximum: 2147483647
**rateLimit** `integer(int32)`
Maximum delivery rate configured for the webhook endpoint.
Minimum: -2147483648
Maximum: 2147483647
**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/subscription#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`
Selection criteria applied to the listing.
All of:
Variant 1:
Event-body and header conditions selecting webhook events for a subscription.
Model reference: [SubscriptionFilter](/api/models/subscription-filter#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/retry-config#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` | 1 | Canonical | Retry using the configured linear interval strategy. |
| `RETRY_STRATEGY_EXPONENTIAL` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**retryCount** `integer(int32)`
Maximum retry count configured for webhook delivery.
Minimum: -2147483648
Maximum: 2147483647
**intervalSeconds** `integer(int32)`
Delay between webhook delivery retries, in seconds.
Minimum: -2147483648
Maximum: 2147483647
**createdAt** `string(date-time)`
Time when this record was created.
**externalId** `string`
Client-supplied external subscription identifier. Empty when none was supplied.
#### 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"
}
}
```
#### 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).
- Overview: `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.
## 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/subscription#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`
Selection criteria applied to the listing.
All of:
Variant 1:
Event-body and header conditions selecting webhook events for a subscription.
Model reference: [SubscriptionFilter](/api/models/subscription-filter#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/retry-config#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` | 1 | Canonical | Retry using the configured linear interval strategy. |
| `RETRY_STRATEGY_EXPONENTIAL` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**retryCount** `integer(int32)`
Maximum retry count configured for webhook delivery.
Minimum: -2147483648
Maximum: 2147483647
**intervalSeconds** `integer(int32)`
Delay between webhook delivery retries, in seconds.
Minimum: -2147483648
Maximum: 2147483647
**createdAt** `string(date-time)`
Time when this record was created.
**externalId** `string`
Client-supplied external subscription identifier. Empty when none was supplied.
#### 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"
}
}
```
Document ID: `DOC-IN-webhooks-api-createWebhookSubscription`. [Section identities and revisions](/documentation-manifest.json).
- Overview: `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.
## 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).
- Overview: `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.
## 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).
- Overview: `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.
## 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.
Delivery-backend state of a webhook event sent to an endpoint.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `DELIVERY_STATUS_SCHEDULED` | 1 | Canonical | The delivery is scheduled and waiting for processing. |
| `DELIVERY_STATUS_PROCESSING` | 2 | Canonical | The delivery backend is processing a delivery attempt. |
| `DELIVERY_STATUS_COMPLETED` | 3 | Canonical | The webhook delivery completed successfully. |
| `DELIVERY_STATUS_RETRY` | 4 | Canonical | The delivery is awaiting another attempt after a retryable failure. |
| `DELIVERY_STATUS_FAILED` | 5 | Canonical | The delivery is reported as failed by the backend. |
| `DELIVERY_STATUS_DISCARDED` | 6 | Canonical | The delivery backend discarded the event instead of completing delivery. |
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)`
Must not match:
Type: `any`
Enum: `0`
**createdAfter** `string(date-time)`
Optional: filter by creation time.
**createdBefore** `string(date-time)`
Optional: filter by creation time.
**page** `integer(int32)`
Page number used by this listing operation.
Minimum: -2147483648
Maximum: 2147483647
**perPage** `integer(int32)`
Number of entries requested per page.
Minimum: -2147483648
Maximum: 2147483647
#### 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[EventDelivery]`
Webhook delivery records matching the listing query.
Delivery-attempt state and response information for a webhook event.
Model reference: [EventDelivery](/api/models/event-delivery#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.
Delivery-backend state of a webhook event sent to an endpoint.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `DELIVERY_STATUS_SCHEDULED` | 1 | Canonical | The delivery is scheduled and waiting for processing. |
| `DELIVERY_STATUS_PROCESSING` | 2 | Canonical | The delivery backend is processing a delivery attempt. |
| `DELIVERY_STATUS_COMPLETED` | 3 | Canonical | The webhook delivery completed successfully. |
| `DELIVERY_STATUS_RETRY` | 4 | Canonical | The delivery is awaiting another attempt after a retryable failure. |
| `DELIVERY_STATUS_FAILED` | 5 | Canonical | The delivery is reported as failed by the backend. |
| `DELIVERY_STATUS_DISCARDED` | 6 | Canonical | The delivery backend discarded the event instead of completing delivery. |
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)`
Must not match:
Type: `any`
Enum: `0`
**attempts** `integer(int32)`
Number of delivery attempts reported for the webhook event.
Minimum: -2147483648
Maximum: 2147483647
**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** `integer(int32)`
HTTP response status reported for the delivery attempt.
Minimum: -2147483648
Maximum: 2147483647
**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/pagination-info#response).
**total** `integer(int32)`
Total number of entries reported by the listing.
Minimum: -2147483648
Maximum: 2147483647
**page** `integer(int32)`
Page number used by this listing operation.
Minimum: -2147483648
Maximum: 2147483647
**perPage** `integer(int32)`
Number of entries requested per page.
Minimum: -2147483648
Maximum: 2147483647
**totalPages** `integer(int32)`
Total number of pages reported for the current query.
Minimum: -2147483648
Maximum: 2147483647
#### 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).
- Overview: `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.
## 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** `integer(int32)`
Page number used by this listing operation.
Minimum: -2147483648
Maximum: 2147483647
**perPage** `integer(int32)`
Number of entries requested per page.
Minimum: -2147483648
Maximum: 2147483647
#### 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[Endpoint]`
Webhook endpoints returned by the listing.
Provider record describing a webhook delivery destination and its delivery settings.
Model reference: [Endpoint](/api/models/endpoint#response).
**id** `string`
Identifier of the endpoint record.
**name** `string`
Display name of the webhook delivery destination.
**url** `string`
URL associated with the resource or outbound request.
**description** `string`
Human-readable description of the resource.
**status** `any`
Current state of the webhook endpoint.
Lifecycle condition reported for a webhook delivery endpoint.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `ENDPOINT_STATUS_ACTIVE` | 1 | Canonical | The endpoint is marked active for webhook delivery. |
| `ENDPOINT_STATUS_INACTIVE` | 2 | Canonical | The endpoint is marked inactive by the delivery backend. |
| `ENDPOINT_STATUS_PAUSED` | 3 | Canonical | Delivery to the endpoint is paused. |
| `ENDPOINT_STATUS_PENDING` | 4 | 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)`
Must not match:
Type: `any`
Enum: `0`
**secret** `string`
Secret associated with the webhook endpoint or deployed trigger.
**httpTimeout** `integer(int32)`
Timeout for an individual webhook HTTP delivery, in seconds.
Minimum: -2147483648
Maximum: 2147483647
**rateLimit** `integer(int32)`
Maximum delivery rate configured for the webhook endpoint.
Minimum: -2147483648
Maximum: 2147483647
**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/pagination-info#response).
**total** `integer(int32)`
Total number of entries reported by the listing.
Minimum: -2147483648
Maximum: 2147483647
**page** `integer(int32)`
Page number used by this listing operation.
Minimum: -2147483648
Maximum: 2147483647
**perPage** `integer(int32)`
Number of entries requested per page.
Minimum: -2147483648
Maximum: 2147483647
**totalPages** `integer(int32)`
Total number of pages reported for the current query.
Minimum: -2147483648
Maximum: 2147483647
#### 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).
- Overview: `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.
## 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** `integer(int32)`
Page number used by this listing operation.
Minimum: -2147483648
Maximum: 2147483647
**perPage** `integer(int32)`
Number of entries requested per page.
Minimum: -2147483648
Maximum: 2147483647
#### 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[Subscription]`
Webhook subscriptions returned by the listing.
Webhook event selection and retry settings associated with an endpoint.
Model reference: [Subscription](/api/models/subscription#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`
Selection criteria applied to the listing.
All of:
Variant 1:
Event-body and header conditions selecting webhook events for a subscription.
Model reference: [SubscriptionFilter](/api/models/subscription-filter#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/retry-config#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` | 1 | Canonical | Retry using the configured linear interval strategy. |
| `RETRY_STRATEGY_EXPONENTIAL` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**retryCount** `integer(int32)`
Maximum retry count configured for webhook delivery.
Minimum: -2147483648
Maximum: 2147483647
**intervalSeconds** `integer(int32)`
Delay between webhook delivery retries, in seconds.
Minimum: -2147483648
Maximum: 2147483647
**createdAt** `string(date-time)`
Time when this record was created.
**externalId** `string`
Client-supplied external subscription identifier. Empty when none was supplied.
**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/pagination-info#response).
**total** `integer(int32)`
Total number of entries reported by the listing.
Minimum: -2147483648
Maximum: 2147483647
**page** `integer(int32)`
Page number used by this listing operation.
Minimum: -2147483648
Maximum: 2147483647
**perPage** `integer(int32)`
Number of entries requested per page.
Minimum: -2147483648
Maximum: 2147483647
**totalPages** `integer(int32)`
Total number of pages reported for the current query.
Minimum: -2147483648
Maximum: 2147483647
#### 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"
}
],
"pagination": {
"total": 1,
"page": 1,
"perPage": 1,
"totalPages": 1
}
}
```
Document ID: `DOC-IN-webhooks-api-listWebhookSubscriptions`. [Section identities and revisions](/documentation-manifest.json).
- Overview: `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.
## 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/event-delivery#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.
Delivery-backend state of a webhook event sent to an endpoint.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `DELIVERY_STATUS_SCHEDULED` | 1 | Canonical | The delivery is scheduled and waiting for processing. |
| `DELIVERY_STATUS_PROCESSING` | 2 | Canonical | The delivery backend is processing a delivery attempt. |
| `DELIVERY_STATUS_COMPLETED` | 3 | Canonical | The webhook delivery completed successfully. |
| `DELIVERY_STATUS_RETRY` | 4 | Canonical | The delivery is awaiting another attempt after a retryable failure. |
| `DELIVERY_STATUS_FAILED` | 5 | Canonical | The delivery is reported as failed by the backend. |
| `DELIVERY_STATUS_DISCARDED` | 6 | Canonical | The delivery backend discarded the event instead of completing delivery. |
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)`
Must not match:
Type: `any`
Enum: `0`
**attempts** `integer(int32)`
Number of delivery attempts reported for the webhook event.
Minimum: -2147483648
Maximum: 2147483647
**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** `integer(int32)`
HTTP response status reported for the delivery attempt.
Minimum: -2147483648
Maximum: 2147483647
**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).
- Overview: `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.
## 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 associated with the resource or outbound request.
**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/endpoint#response).
**id** `string`
Identifier of the endpoint record.
**name** `string`
Display name of the webhook delivery destination.
**url** `string`
URL associated with the resource or outbound request.
**description** `string`
Human-readable description of the resource.
**status** `any`
Current state of the webhook endpoint.
Lifecycle condition reported for a webhook delivery endpoint.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `ENDPOINT_STATUS_ACTIVE` | 1 | Canonical | The endpoint is marked active for webhook delivery. |
| `ENDPOINT_STATUS_INACTIVE` | 2 | Canonical | The endpoint is marked inactive by the delivery backend. |
| `ENDPOINT_STATUS_PAUSED` | 3 | Canonical | Delivery to the endpoint is paused. |
| `ENDPOINT_STATUS_PENDING` | 4 | 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)`
Must not match:
Type: `any`
Enum: `0`
**secret** `string`
Secret associated with the webhook endpoint or deployed trigger.
**httpTimeout** `integer(int32)`
Timeout for an individual webhook HTTP delivery, in seconds.
Minimum: -2147483648
Maximum: 2147483647
**rateLimit** `integer(int32)`
Maximum delivery rate configured for the webhook endpoint.
Minimum: -2147483648
Maximum: 2147483647
**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).
- Overview: `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: `1.0.0`
Register HTTPS endpoints, subscribe them to events and inspect or retry deliveries.
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](/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
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.
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](/integrations/webhooks)
### 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](/api).
## Authentication {#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.
Security scheme type: `apiKey`
Parameter location: `header`
Parameter name: `X-API-Key`
### 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`.
Security scheme type: `http`
HTTP authorization scheme: `bearer`
Bearer format: `JWT`
## Operations
- [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`
- [Delete a webhook endpoint](/api/webhooks/delete-webhook-endpoint) — `POST /api/v1/webhooks/delete-endpoint`
- [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`
- [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`
- [Retry a failed webhook delivery](/api/webhooks/retry-webhook-delivery) — `POST /api/v1/webhooks/retry-delivery`
- [Update a webhook endpoint](/api/webhooks/update-webhook-endpoint) — `POST /api/v1/webhooks/update-endpoint`
Document ID: `DOC-IN-webhooks-api-overview`. [Section identities and revisions](/documentation-manifest.json).
- Overview: `DOC-IN-webhooks-api-overview#overview`
- JSON conventions: `DOC-IN-webhooks-api-overview#json-conventions`
- Authentication: `DOC-IN-webhooks-api-overview#authentication`
- Endpoints and subscriptions: `DOC-IN-webhooks-api-overview#endpoints-and-subscriptions`
- Addressing Subscriptions: `DOC-IN-webhooks-api-overview#addressing-subscriptions`
---
# Context and compaction {#overview}
URL: https://docs.travila.ai/api/conversations/context-and-compaction
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/usage#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/context-management-settings#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/tool-call#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.
---
# 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.
## 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 (JWT) 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
Model reference: [Message](/api/models/message#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` | 1 | Canonical | Instructions or context provided as a system message. |
| `ROLE_USER` | 2 | Canonical | Input supplied by the user or customer application. |
| `ROLE_ASSISTANT` | 3 | Canonical | Content produced by the assistant, including its tool-call requests. |
| `ROLE_TOOL` | 4 | 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: `1`, `2`, `3`, `4`
Must not match:
Type: `any`
Enum: `0`
**content** `array[ContentPartInput]`
Content parts composing the chat message.
Content parts composing a message (flattened structure for JSON compatibility)
Model reference: [ContentPart](/api/models/content-part#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` | 1 | Canonical | Plain text carried by the content part. |
| `CONTENT_PART_TYPE_IMAGE_URL` | 2 | Canonical | An image supplied through a remote URL. |
| `CONTENT_PART_TYPE_IMAGE_BASE64` | 3 | Canonical | An image supplied as base64-encoded bytes. |
| `CONTENT_PART_TYPE_FILE_ID` | 4 | Canonical | A provider file identifier or internal storage identifier resolved before generation. |
| `CONTENT_PART_TYPE_FILE_PATH` | 5 | Canonical | A reference to a local file path. |
| `CONTENT_PART_TYPE_FILE_URL` | 6 | Canonical | A file supplied through a public or signed URL. |
| `CONTENT_PART_TYPE_FILE_DATA_URL` | 7 | Canonical | A file embedded in a data URL, including its media type and encoded data. |
| `CONTENT_PART_TYPE_AUDIO_BASE64` | 8 | Canonical | Base64-encoded audio; the part metadata identifies its audio format. |
| `CONTENT_PART_TYPE_REASONING` | 9 | Canonical | A reasoning segment returned by a model provider, when available. |
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: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`
Must not match:
Type: `any`
Enum: `0`
**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/content-part#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/content-part#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/structured-message#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[ToolCallInput]`
Assistant-to-tool invocations.
A single structured tool call emitted by the model
[`clientToolDeadlineAt`](/api/models/tool-call#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/tool-call#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 one tool call, including approval waiting and terminal outcomes.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `TOOL_EXECUTION_STATUS_PENDING` | 1 | Canonical | The tool call is waiting to begin execution. |
| `TOOL_EXECUTION_STATUS_EXECUTING` | 2 | Canonical | The tool call is currently executing. |
| `TOOL_EXECUTION_STATUS_COMPLETED` | 3 | Canonical | The tool call completed successfully. Responses use this canonical spelling for numeric value 3. |
| `TOOL_EXECUTION_STATUS_SUCCESS` | 3 | Alias of `TOOL_EXECUTION_STATUS_COMPLETED` | Legacy alias of TOOL_EXECUTION_STATUS_COMPLETED with the same numeric value; use COMPLETED for new writes. |
| `TOOL_EXECUTION_STATUS_FAILED` | 4 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. |
| `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 5 | Canonical | The tool call is waiting for approval before it can execute. |
| `TOOL_EXECUTION_STATUS_CANCELLED` | 6 | Canonical | The tool call was cancelled before normal completion. |
| `TOOL_EXECUTION_STATUS_TIMED_OUT` | 7 | 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_SUCCESS`, `TOOL_EXECUTION_STATUS_FAILED`, `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION`, `TOOL_EXECUTION_STATUS_CANCELLED`, `TOOL_EXECUTION_STATUS_TIMED_OUT`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**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 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", the underlying error. Set only once `status` is
terminal, and empty on a clean COMPLETED.
**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. Mirrors requires_approval_at.
**name** `string`
Name identifying the sender of the chat message.
**timestamp** `string(date-time)`
Timestamp associated with the conversation message or event.
**messageId** `string`
Unique message identifier.
**annotations** `array[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/annotation#request).
**urlCitation** `any`
Submessage fields (optional); populate the one matching kind
All of:
Variant 1:
=== Annotations ===
Web source and character range cited in generated message content.
Model reference: [UrlCitation](/api/models/url-citation#request).
**url** `string`
URL associated with the resource or outbound request.
**title** `string`
Title of the web page cited by this annotation.
**content** `string`
Excerpt or snippet of the cited web page.
**startIndex** `integer(int32)`
Character index in message content.
Minimum: -2147483648
Maximum: 2147483647
**endIndex** `integer(int32)`
Character index in message content.
Minimum: -2147483648
Maximum: 2147483647
**pdf** `any`
PDF annotation or parser configuration selected by the enclosing message.
All of:
Variant 1:
Provider annotation identifying a parsed PDF and reusable parsing output.
Model reference: [PdfAnnotation](/api/models/pdf-annotation#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[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 (flattened structure for JSON compatibility)
Model reference: [ContentPart](/api/models/content-part#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` | 1 | Canonical | Plain text carried by the content part. |
| `CONTENT_PART_TYPE_IMAGE_URL` | 2 | Canonical | An image supplied through a remote URL. |
| `CONTENT_PART_TYPE_IMAGE_BASE64` | 3 | Canonical | An image supplied as base64-encoded bytes. |
| `CONTENT_PART_TYPE_FILE_ID` | 4 | Canonical | A provider file identifier or internal storage identifier resolved before generation. |
| `CONTENT_PART_TYPE_FILE_PATH` | 5 | Canonical | A reference to a local file path. |
| `CONTENT_PART_TYPE_FILE_URL` | 6 | Canonical | A file supplied through a public or signed URL. |
| `CONTENT_PART_TYPE_FILE_DATA_URL` | 7 | Canonical | A file embedded in a data URL, including its media type and encoded data. |
| `CONTENT_PART_TYPE_AUDIO_BASE64` | 8 | Canonical | Base64-encoded audio; the part metadata identifies its audio format. |
| `CONTENT_PART_TYPE_REASONING` | 9 | Canonical | A reasoning segment returned by a model provider, when available. |
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: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`
Must not match:
Type: `any`
Enum: `0`
**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/content-part#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/content-part#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/structured-message#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.
**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` | 1 | Canonical | A citation to a source identified by its URL. |
| `ANNOTATION_KIND_PDF` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/usage#request).
**promptTokens** `integer(int32)`
Prompt-token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**completionTokens** `integer(int32)`
Completion-token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**totalTokens** `integer(int32)`
Total token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**costEstimate** `any`
Estimated cost in USD.
Exactly one of:
Variant 1:
Type: `number(float)`
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; one category must not be derived by subtracting the
others.
Model reference: [CompletionTokensDetails](/api/models/completion-tokens-details#request).
**reasoningTokens** `integer(int32)`
Tokens used for reasoning/thinking.
Minimum: -2147483648
Maximum: 2147483647
**imageTokens** `integer(int32)`
Completion tokens emitted as image output.
Minimum: -2147483648
Maximum: 2147483647
**audioTokens** `integer(int32)`
Completion tokens emitted as audio output.
Minimum: -2147483648
Maximum: 2147483647
**promptTokensDetails** `any`
Breakdown of prompt tokens (cache).
All of:
Variant 1:
Breakdown of prompt token usage by category (input-side cache accounting)
Model reference: [PromptTokensDetails](/api/models/prompt-tokens-details#request).
**cachedTokens** `integer(int32)`
Prompt tokens served from cache (cache READ).
Minimum: -2147483648
Maximum: 2147483647
**cacheWriteTokens** `integer(int32)`
Prompt tokens written to cache this call (cache WRITE).
Minimum: -2147483648
Maximum: 2147483647
**audioTokens** `integer(int32)`
Prompt tokens from audio input (multimodal).
Minimum: -2147483648
Maximum: 2147483647
**videoTokens** `integer(int32)`
Prompt tokens from video input (multimodal).
Minimum: -2147483648
Maximum: 2147483647
**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/cost-details#request).
**upstreamInferenceCost** `any`
Total upstream provider cost (USD) on BYOK routes.
Exactly one of:
Variant 1:
Type: `number(float)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**upstreamInferencePromptCost** `any`
Upstream cost attributed to prompt tokens (USD).
Exactly one of:
Variant 1:
Type: `number(float)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**upstreamInferenceCompletionCost** `any`
Upstream cost attributed to completion tokens (USD).
Exactly one of:
Variant 1:
Type: `number(float)`
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/generation-context#request).
**memories** `array[MemoryReferenceInput]`
Memory records captured in the generation context.
A memory record retrieved and included in generation context.
Model reference: [MemoryReference](/api/models/memory-reference#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(float)`
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[RelationReferenceInput]`
Graph relationships captured in the generation context.
A graph relationship retrieved and included in generation context.
Model reference: [RelationReference](/api/models/relation-reference#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/memory-search-params#request).
**query** `string`
Text submitted to memory retrieval for this generation.
**topK** `integer(int32)`
Maximum memory matches requested during generation-context retrieval.
Minimum: -2147483648
Maximum: 2147483647
**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** `integer(int32)`
Number of memory records returned by the search.
Minimum: -2147483648
Maximum: 2147483647
**relationsReturned** `integer(int32)`
Number of graph relationships returned by the search.
Minimum: -2147483648
Maximum: 2147483647
**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/turn-info#request).
**currentTurn** `integer(int32)`
Current turn position within the generation run.
Minimum: -2147483648
Maximum: 2147483647
**maxTurns** `integer(int32)`
Maximum turns configured for the generation run.
Minimum: -2147483648
Maximum: 2147483647
**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 prompt for a generation turn.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `PROMPT_SOURCE_CLIENT_OVERRIDE` | 1 | Canonical | The caller supplied the prompt through the send request's generation-configuration override. |
| `PROMPT_SOURCE_PROFILE_TEMPLATE` | 2 | Canonical | The prompt was rendered from the active agent profile template. |
| `PROMPT_SOURCE_DEFAULT_CONFIG` | 3 | Canonical | The prompt came from the conversation or project default generation configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**baseConfig** `any`
Generation configuration resolved before per-call overrides and timeout adjustments, with
system_prompt omitted. The active profile supplies the base when selected; otherwise the
conversation default does. May be absent on older turns or when neither supplies a
configuration.
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/generation-config#request).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#request).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: 0
Maximum: 3
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#request).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinitionInput]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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**
Which server provides this tool (for MCP tools).
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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinitionInput]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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**
Which server provides this tool (for MCP tools).
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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#request).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRuleInput]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#request).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#request).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#request).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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})*$
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#request).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#request).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#request).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#request).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#request).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#request).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
**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/generation-config#request).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#request).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: 0
Maximum: 3
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#request).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinitionInput]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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**
Which server provides this tool (for MCP tools).
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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinitionInput]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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**
Which server provides this tool (for MCP tools).
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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#request).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRuleInput]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#request).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#request).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#request).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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})*$
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#request).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#request).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#request).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#request).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#request).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#request).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
**profileVersion** `integer(int32)`
Immutable version of the active agent profile used to render this turn’s prompt. Absent on
older turns and turns without a profile template.
Minimum: -2147483648
Maximum: 2147483647
**fragmentsVersion** `integer(int32)`
Version of the prompt-fragment set used to render the profile prompt.
Minimum: -2147483648
Maximum: 2147483647
**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 [User Context] block as rendered into this turn's prompt: the user's
name, locale, and location conditions (weather/AQI/UV/sun times). This is
the literal text the model received, not a reconstruction.
Empty when the user has no stored location, when enrichment degraded, or
on turns predating capture.
**resolvedMcpServers** `array[MCPServerReferenceInput]`
The MCP server list that governed this turn — the tier actually resolved
(conversation settings -> active profile -> per-turn override_mcp_servers),
which is simultaneously the tool-discovery source and the CallTool
allow/block basis.
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/mcp-server-reference#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** `integer(int32)`
Priority override for tool selection (higher = preferred).
Minimum: -2147483648
Maximum: 2147483647
**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.
**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/client-context#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[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.
Model reference: [MessageFeedback](/api/models/message-feedback#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` | 1 | Canonical | Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice. |
| `FEEDBACK_KIND_SCALE` | 2 | Canonical | Feedback expressed as an integer rating from 1 through 10. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `FEEDBACK_KIND_THUMB`, `FEEDBACK_KIND_SCALE`
Variant 2:
Type: `integer(int32)`
Enum: `1`, `2`
Must not match:
Type: `any`
Enum: `0`
**thumbUp** `boolean`
Positive when true and negative when false; used for THUMB feedback.
**rating** `integer(int32)`
Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent.
Minimum: 0
Maximum: 10
**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.
**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).
- Overview: `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.
## 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 (JWT) 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** `integer(int32)`
Estimated tokens in the source messages being summarized, not the compaction trigger estimate.
Minimum: -2147483648
Maximum: 2147483647
**tokensAfter** `integer(int32)`
Tokens in the generated summary, using provider-reported usage when available.
Minimum: -2147483648
Maximum: 2147483647
**tokensSaved** `integer(int32)`
Source count minus summary count. The counts can use different methods; this is not an invoice saving.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Compaction was started and its result is still pending. |
| `COMPACTION_STATUS_COMPLETED` | 2 | Canonical | Compaction completed and produced its result. |
| `COMPACTION_STATUS_FAILED` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
#### 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).
- Overview: `DOC-MA-conversations-api-compactConversation#overview`
- Request: `DOC-MA-conversations-api-compactConversation#request`
- Responses: `DOC-MA-conversations-api-compactConversation#responses`
---
# 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.
## 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 (JWT) via `Authorization: Bearer `
## Request Body
*Required*
Content type: `application/json`
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.
**socayoConfig** `any`
Socayo-specific agent configuration
All of:
Variant 1:
Socayo-specific agent configuration (bundled)
Model reference: [SocayoAgentConfig](/api/models/socayo-agent-config#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` | 1 | Canonical | Use the Pipecat Cloud hosting backend. |
| `AGENT_PROVIDER_CEREBRIUM` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**tts** `any`
Bundled sub-configs
Speech-synthesis configuration supplied to the Socayo agent.
All of:
Variant 1:
Cartesia Sonic-3 TTS configuration
Model reference: [TTSConfig](/api/models/tts-config#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** `integer(int32)`
Optional sample rate override (Hz)
Minimum: -2147483648
Maximum: 2147483647
**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/hey-gen-config#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.
**videoEncoding** `string`
Video codec requested for the HeyGen avatar stream.
**voice** `any`
Voice configuration used by the HeyGen avatar.
All of:
Variant 1:
HeyGen voice settings
Model reference: [HeyGenVoiceSettings](/api/models/hey-gen-voice-settings#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.
**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/hey-gen-eleven-labs-settings#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** `integer(int32)`
Integer style code.
Minimum: -2147483648
Maximum: 2147483647
**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.
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/transport-config#request).
**audioInSampleRate** `integer(int32)`
Sample rate of incoming audio, in hertz.
Minimum: -2147483648
Maximum: 2147483647
**audioOutSampleRate** `integer(int32)`
Sample rate of outgoing audio, in hertz.
Minimum: -2147483648
Maximum: 2147483647
**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/daily-room-properties#request).
**nbf** `string(int64)`
Timestamps (unix seconds)
Pattern: ^-?\d+$
**exp** `string(int64)`
Expiration time of the Daily room, as Unix seconds.
Pattern: ^-?\d+$
**maxParticipants** `integer(int32)`
Limits
Maximum number of participants allowed in the Daily room.
Minimum: -2147483648
Maximum: 2147483647
**enablePeopleUi** `boolean`
UI toggles
Whether the Daily room exposes the 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`
Access and permissions
**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`
Features
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`
Media defaults
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` | 1 | Canonical | Request the provider's cloud recording mode. |
| `RECORDING_MODE_LOCAL` | 2 | Canonical | Request the provider's local recording mode. |
| `RECORDING_MODE_RAW_TRACKS` | 3 | Canonical | Request separate raw media tracks for recording. |
| `RECORDING_MODE_DISABLED` | 4 | Canonical | Explicitly disable room recording. |
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)`
Must not match:
Type: `any`
Enum: `0`
**ejectAtRoomExp** `boolean`
Whether participants are removed when the Daily room expires.
**ejectAfterElapsed** `integer(int32)`
Elapsed session duration after which to eject participants, in seconds.
Minimum: -2147483648
Maximum: 2147483647
**enableMeshSfu** `boolean`
Topology and bandwidth
**sfuSwitchover** `any`
Daily topology setting controlling the switch to SFU transport.
Exactly one of:
Variant 1:
Type: `number(float)`
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`
Localization and hooks
**meetingJoinHook** `string`
Webhook URL invoked by the Daily meeting-join hook.
**geo** `string`
Regions
Region selected for the Daily room’s media infrastructure.
**rtmpGeo** `string`
Region selected for Daily RTMP streaming.
**disableRtmpGeoFallback** `boolean`
Whether automatic RTMP region fallback is disabled.
**recordingsBucket** `any`
Storage destination configured for Daily recordings.
All of:
Variant 1:
Storage configs
Object-storage destination and access settings for Daily recordings.
Model reference: [RecordingBucketConfig](/api/models/recording-bucket-config#request).
**bucketName** `string`
Object-storage bucket used for Daily recordings or transcriptions.
**bucketRegion** `string`
Region containing the Daily recording or transcription 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/transcription-bucket-config#request).
**bucketName** `string`
Object-storage bucket used for Daily recordings or transcriptions.
**bucketRegion** `string`
Region containing the Daily recording or transcription 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/daily-meeting-token-properties#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/start-session-user-data#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/daily-session#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/start-session-user-data#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/daily-room-properties#response).
**nbf** `string(int64)`
Timestamps (unix seconds)
Pattern: ^-?\d+$
**exp** `string(int64)`
Expiration time of the Daily room, as Unix seconds.
Pattern: ^-?\d+$
**maxParticipants** `integer(int32)`
Limits
Maximum number of participants allowed in the Daily room.
Minimum: -2147483648
Maximum: 2147483647
**enablePeopleUi** `boolean`
UI toggles
Whether the Daily room exposes the 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`
Access and permissions
**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`
Features
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`
Media defaults
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` | 1 | Canonical | Request the provider's cloud recording mode. |
| `RECORDING_MODE_LOCAL` | 2 | Canonical | Request the provider's local recording mode. |
| `RECORDING_MODE_RAW_TRACKS` | 3 | Canonical | Request separate raw media tracks for recording. |
| `RECORDING_MODE_DISABLED` | 4 | Canonical | Explicitly disable room recording. |
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)`
Must not match:
Type: `any`
Enum: `0`
**ejectAtRoomExp** `boolean`
Whether participants are removed when the Daily room expires.
**ejectAfterElapsed** `integer(int32)`
Elapsed session duration after which to eject participants, in seconds.
Minimum: -2147483648
Maximum: 2147483647
**enableMeshSfu** `boolean`
Topology and bandwidth
**sfuSwitchover** `any`
Daily topology setting controlling the switch to SFU transport.
Exactly one of:
Variant 1:
Type: `number(float)`
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`
Localization and hooks
**meetingJoinHook** `string`
Webhook URL invoked by the Daily meeting-join hook.
**geo** `string`
Regions
Region selected for the Daily room’s media infrastructure.
**rtmpGeo** `string`
Region selected for Daily RTMP streaming.
**disableRtmpGeoFallback** `boolean`
Whether automatic RTMP region fallback is disabled.
**recordingsBucket** `any`
Storage destination configured for Daily recordings.
All of:
Variant 1:
Storage configs
Object-storage destination and access settings for Daily recordings.
Model reference: [RecordingBucketConfig](/api/models/recording-bucket-config#response).
**bucketName** `string`
Object-storage bucket used for Daily recordings or transcriptions.
**bucketRegion** `string`
Region containing the Daily recording or transcription 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/transcription-bucket-config#response).
**bucketName** `string`
Object-storage bucket used for Daily recordings or transcriptions.
**bucketRegion** `string`
Region containing the Daily recording or transcription 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/daily-meeting-token-properties#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).
- Overview: `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.
## 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 (JWT) via `Authorization: Bearer `
## Request Body
*Required*
Content type: `application/json`
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** `integer(int32)`
Immutable version of the active profile to use. Zero selects its latest version.
Minimum: -2147483648
Maximum: 2147483647
**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/generation-config#request).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#request).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: 0
Maximum: 3
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#request).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinitionInput]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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**
Which server provides this tool (for MCP tools).
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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinitionInput]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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**
Which server provides this tool (for MCP tools).
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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#request).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRuleInput]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#request).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#request).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#request).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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})*$
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#request).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#request).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#request).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#request).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#request).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#request).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
**conversationSettings** `any`
Initial conversation settings, including prompt and integration configuration.
All of:
Variant 1:
Conversation-level settings controlling behavior across sends
[`maxLoops`](/api/models/conversation-settings#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/generation-config#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/conversation-settings#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` | 1 | Canonical | Reject the new send with an error while a run is active; do not append its user message. |
| `INTERRUPT_POLICY_CANCEL_ONGOING` | 2 | Canonical | Cancel the ongoing run and start a new run for the incoming message. |
| `INTERRUPT_POLICY_QUEUE` | 3 | Canonical | Queue the incoming message to run after the current run completes. |
| `INTERRUPT_POLICY_IGNORE` | 4 | Canonical | Accept the send without persisting its message or starting a new run; let the ongoing run continue. |
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)`
Must not match:
Type: `any`
Enum: `0`
**maxLoops** `integer(int32)`
Default limit on agentic generation loops for the conversation.
Minimum: -2147483648
Maximum: 2147483647
**maxParallelTools** `integer(int32)`
Maximum number of tool executions allowed concurrently by this configuration.
Minimum: -2147483648
Maximum: 2147483647
**mcpServers** `array[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/mcp-server-reference#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** `integer(int32)`
Priority override for tool selection (higher = preferred).
Minimum: -2147483648
Maximum: 2147483647
**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.
**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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#request).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRuleInput]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#request).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#request).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#request).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**promptVariables** `map[string, any]`
Typed values used when rendering profile prompt templates. They 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/context-management-settings#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` | 1 | Canonical | Use completed compaction summaries and remaining history; fall back to windowing when no completed summary is available. |
| `CONTEXT_STRATEGY_WINDOWING` | 2 | Canonical | Keep a bounded window of recent conversation messages according to the windowing configuration. |
| `CONTEXT_STRATEGY_NONE` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**compactionConfig** `any`
Configuration applied when summarizing the conversation context.
All of:
Variant 1:
Configuration for compaction strategy
Model reference: [CompactionConfig](/api/models/compaction-config#request).
**mode** `any`
Context compaction mode selected by the operation.
Whether context compaction blocks the triggering operation or proceeds asynchronously.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `COMPACTION_MODE_SYNC` | 1 | Canonical | Wait for compaction to finish before continuing the dependent operation. |
| `COMPACTION_MODE_ASYNC` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**threshold** `any`
Token-count or context-window-percentage threshold that triggers compaction.
All of:
Variant 1:
Threshold configuration for triggering compaction
Model reference: [ThresholdConfig](/api/models/threshold-config#request).
All of:
Variant 1:
Type: `any`
Must not match:
Type: `any`
**tokenCount** `integer(int32)`
Absolute token limit.
Minimum: -2147483648
Maximum: 2147483647
**percentage** `integer(int32)`
% of model's context window.
Minimum: -2147483648
Maximum: 2147483647
**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/generation-config#request).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#request).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: 0
Maximum: 3
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#request).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinitionInput]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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**
Which server provides this tool (for MCP tools).
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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinitionInput]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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**
Which server provides this tool (for MCP tools).
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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#request).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRuleInput]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#request).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#request).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#request).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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})*$
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#request).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#request).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#request).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#request).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#request).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#request).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
**preserveRecent** `integer(int32)`
Messages to keep uncompacted.
Minimum: -2147483648
Maximum: 2147483647
**windowingConfig** `any`
Rules selecting the message window retained in model context.
All of:
Variant 1:
Configuration for windowing strategy
Model reference: [WindowingConfig](/api/models/windowing-config#request).
**maxMessages** `integer(int32)`
Maximum number of conversation messages to retain in the context window.
Minimum: -2147483648
Maximum: 2147483647
**selectiveExclusionConfig** `any`
Rules selecting content to omit from the model context.
All of:
Variant 1:
Configuration for selective exclusion
Model reference: [SelectiveExclusionConfig](/api/models/selective-exclusion-config#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 thread registry record for multi-thread management
Model reference: [ConversationThread](/api/models/conversation-thread#response).
**threadId** `string`
Identifier of the conversation thread.
**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).
- Overview: `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).
## 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 (JWT) 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).
- Overview: `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.
## 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 (JWT) 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
Model reference: [Message](/api/models/message#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` | 1 | Canonical | Instructions or context provided as a system message. |
| `ROLE_USER` | 2 | Canonical | Input supplied by the user or customer application. |
| `ROLE_ASSISTANT` | 3 | Canonical | Content produced by the assistant, including its tool-call requests. |
| `ROLE_TOOL` | 4 | 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)`
Must not match:
Type: `any`
Enum: `0`
**content** `array[ContentPart]`
Content parts composing the chat message.
Content parts composing a message (flattened structure for JSON compatibility)
Model reference: [ContentPart](/api/models/content-part#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` | 1 | Canonical | Plain text carried by the content part. |
| `CONTENT_PART_TYPE_IMAGE_URL` | 2 | Canonical | An image supplied through a remote URL. |
| `CONTENT_PART_TYPE_IMAGE_BASE64` | 3 | Canonical | An image supplied as base64-encoded bytes. |
| `CONTENT_PART_TYPE_FILE_ID` | 4 | Canonical | A provider file identifier or internal storage identifier resolved before generation. |
| `CONTENT_PART_TYPE_FILE_PATH` | 5 | Canonical | A reference to a local file path. |
| `CONTENT_PART_TYPE_FILE_URL` | 6 | Canonical | A file supplied through a public or signed URL. |
| `CONTENT_PART_TYPE_FILE_DATA_URL` | 7 | Canonical | A file embedded in a data URL, including its media type and encoded data. |
| `CONTENT_PART_TYPE_AUDIO_BASE64` | 8 | Canonical | Base64-encoded audio; the part metadata identifies its audio format. |
| `CONTENT_PART_TYPE_REASONING` | 9 | Canonical | A reasoning segment returned by a model provider, when available. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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/content-part#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/content-part#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/structured-message#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[ToolCall]`
Assistant-to-tool invocations.
A single structured tool call emitted by the model
[`clientToolDeadlineAt`](/api/models/tool-call#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/tool-call#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 one tool call, including approval waiting and terminal outcomes.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `TOOL_EXECUTION_STATUS_PENDING` | 1 | Canonical | The tool call is waiting to begin execution. |
| `TOOL_EXECUTION_STATUS_EXECUTING` | 2 | Canonical | The tool call is currently executing. |
| `TOOL_EXECUTION_STATUS_COMPLETED` | 3 | Canonical | The tool call completed successfully. Responses use this canonical spelling for numeric value 3. |
| `TOOL_EXECUTION_STATUS_SUCCESS` | 3 | Alias of `TOOL_EXECUTION_STATUS_COMPLETED`; Name not accepted for this field; number accepted | Legacy alias of TOOL_EXECUTION_STATUS_COMPLETED with the same numeric value; use COMPLETED for new writes. |
| `TOOL_EXECUTION_STATUS_FAILED` | 4 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. |
| `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 5 | Canonical | The tool call is waiting for approval before it can execute. |
| `TOOL_EXECUTION_STATUS_CANCELLED` | 6 | Canonical | The tool call was cancelled before normal completion. |
| `TOOL_EXECUTION_STATUS_TIMED_OUT` | 7 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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 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", the underlying error. Set only once `status` is
terminal, and empty on a clean COMPLETED.
**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. Mirrors requires_approval_at.
**name** `string`
Name identifying the sender of the chat message.
**timestamp** `string(date-time)`
Timestamp associated with the conversation message or event.
**messageId** `string`
Unique message identifier.
**annotations** `array[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/annotation#response).
**urlCitation** `any`
Submessage fields (optional); populate the one matching kind
All of:
Variant 1:
=== Annotations ===
Web source and character range cited in generated message content.
Model reference: [UrlCitation](/api/models/url-citation#response).
**url** `string`
URL associated with the resource or outbound request.
**title** `string`
Title of the web page cited by this annotation.
**content** `string`
Excerpt or snippet of the cited web page.
**startIndex** `integer(int32)`
Character index in message content.
Minimum: -2147483648
Maximum: 2147483647
**endIndex** `integer(int32)`
Character index in message content.
Minimum: -2147483648
Maximum: 2147483647
**pdf** `any`
PDF annotation or parser configuration selected by the enclosing message.
All of:
Variant 1:
Provider annotation identifying a parsed PDF and reusable parsing output.
Model reference: [PdfAnnotation](/api/models/pdf-annotation#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[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 (flattened structure for JSON compatibility)
Model reference: [ContentPart](/api/models/content-part#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` | 1 | Canonical | Plain text carried by the content part. |
| `CONTENT_PART_TYPE_IMAGE_URL` | 2 | Canonical | An image supplied through a remote URL. |
| `CONTENT_PART_TYPE_IMAGE_BASE64` | 3 | Canonical | An image supplied as base64-encoded bytes. |
| `CONTENT_PART_TYPE_FILE_ID` | 4 | Canonical | A provider file identifier or internal storage identifier resolved before generation. |
| `CONTENT_PART_TYPE_FILE_PATH` | 5 | Canonical | A reference to a local file path. |
| `CONTENT_PART_TYPE_FILE_URL` | 6 | Canonical | A file supplied through a public or signed URL. |
| `CONTENT_PART_TYPE_FILE_DATA_URL` | 7 | Canonical | A file embedded in a data URL, including its media type and encoded data. |
| `CONTENT_PART_TYPE_AUDIO_BASE64` | 8 | Canonical | Base64-encoded audio; the part metadata identifies its audio format. |
| `CONTENT_PART_TYPE_REASONING` | 9 | Canonical | A reasoning segment returned by a model provider, when available. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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/content-part#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/content-part#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/structured-message#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.
**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` | 1 | Canonical | A citation to a source identified by its URL. |
| `ANNOTATION_KIND_PDF` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/usage#response).
**promptTokens** `integer(int32)`
Prompt-token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**completionTokens** `integer(int32)`
Completion-token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**totalTokens** `integer(int32)`
Total token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**costEstimate** `any`
Estimated cost in USD.
Exactly one of:
Variant 1:
Type: `number(float)`
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; one category must not be derived by subtracting the
others.
Model reference: [CompletionTokensDetails](/api/models/completion-tokens-details#response).
**reasoningTokens** `integer(int32)`
Tokens used for reasoning/thinking.
Minimum: -2147483648
Maximum: 2147483647
**imageTokens** `integer(int32)`
Completion tokens emitted as image output.
Minimum: -2147483648
Maximum: 2147483647
**audioTokens** `integer(int32)`
Completion tokens emitted as audio output.
Minimum: -2147483648
Maximum: 2147483647
**promptTokensDetails** `any`
Breakdown of prompt tokens (cache).
All of:
Variant 1:
Breakdown of prompt token usage by category (input-side cache accounting)
Model reference: [PromptTokensDetails](/api/models/prompt-tokens-details#response).
**cachedTokens** `integer(int32)`
Prompt tokens served from cache (cache READ).
Minimum: -2147483648
Maximum: 2147483647
**cacheWriteTokens** `integer(int32)`
Prompt tokens written to cache this call (cache WRITE).
Minimum: -2147483648
Maximum: 2147483647
**audioTokens** `integer(int32)`
Prompt tokens from audio input (multimodal).
Minimum: -2147483648
Maximum: 2147483647
**videoTokens** `integer(int32)`
Prompt tokens from video input (multimodal).
Minimum: -2147483648
Maximum: 2147483647
**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/cost-details#response).
**upstreamInferenceCost** `any`
Total upstream provider cost (USD) on BYOK routes.
Exactly one of:
Variant 1:
Type: `number(float)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**upstreamInferencePromptCost** `any`
Upstream cost attributed to prompt tokens (USD).
Exactly one of:
Variant 1:
Type: `number(float)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**upstreamInferenceCompletionCost** `any`
Upstream cost attributed to completion tokens (USD).
Exactly one of:
Variant 1:
Type: `number(float)`
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/generation-context#response).
**memories** `array[MemoryReference]`
Memory records captured in the generation context.
A memory record retrieved and included in generation context.
Model reference: [MemoryReference](/api/models/memory-reference#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(float)`
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[RelationReference]`
Graph relationships captured in the generation context.
A graph relationship retrieved and included in generation context.
Model reference: [RelationReference](/api/models/relation-reference#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/memory-search-params#response).
**query** `string`
Text submitted to memory retrieval for this generation.
**topK** `integer(int32)`
Maximum memory matches requested during generation-context retrieval.
Minimum: -2147483648
Maximum: 2147483647
**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** `integer(int32)`
Number of memory records returned by the search.
Minimum: -2147483648
Maximum: 2147483647
**relationsReturned** `integer(int32)`
Number of graph relationships returned by the search.
Minimum: -2147483648
Maximum: 2147483647
**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/turn-info#response).
**currentTurn** `integer(int32)`
Current turn position within the generation run.
Minimum: -2147483648
Maximum: 2147483647
**maxTurns** `integer(int32)`
Maximum turns configured for the generation run.
Minimum: -2147483648
Maximum: 2147483647
**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 prompt for a generation turn.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `PROMPT_SOURCE_CLIENT_OVERRIDE` | 1 | Canonical | The caller supplied the prompt through the send request's generation-configuration override. |
| `PROMPT_SOURCE_PROFILE_TEMPLATE` | 2 | Canonical | The prompt was rendered from the active agent profile template. |
| `PROMPT_SOURCE_DEFAULT_CONFIG` | 3 | Canonical | The prompt came from the conversation or project default generation configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**baseConfig** `any`
Generation configuration resolved before per-call overrides and timeout adjustments, with
system_prompt omitted. The active profile supplies the base when selected; otherwise the
conversation default does. May be absent on older turns or when neither supplies a
configuration.
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/generation-config#response).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#response).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: -2147483648
Maximum: 2147483647
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#response).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinition]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinition]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#response).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRule]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#response).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#response).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#response).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**languagePreference** `string`
Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware)
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#response).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#response).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#response).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#response).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#response).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#response).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
**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/generation-config#response).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#response).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: -2147483648
Maximum: 2147483647
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#response).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinition]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinition]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#response).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRule]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#response).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#response).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#response).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**languagePreference** `string`
Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware)
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#response).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#response).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#response).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#response).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#response).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#response).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
**profileVersion** `integer(int32)`
Immutable version of the active agent profile used to render this turn’s prompt. Absent on
older turns and turns without a profile template.
Minimum: -2147483648
Maximum: 2147483647
**fragmentsVersion** `integer(int32)`
Version of the prompt-fragment set used to render the profile prompt.
Minimum: -2147483648
Maximum: 2147483647
**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 [User Context] block as rendered into this turn's prompt: the user's
name, locale, and location conditions (weather/AQI/UV/sun times). This is
the literal text the model received, not a reconstruction.
Empty when the user has no stored location, when enrichment degraded, or
on turns predating capture.
**resolvedMcpServers** `array[MCPServerReference]`
The MCP server list that governed this turn — the tier actually resolved
(conversation settings -> active profile -> per-turn override_mcp_servers),
which is simultaneously the tool-discovery source and the CallTool
allow/block basis.
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/mcp-server-reference#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** `integer(int32)`
Priority override for tool selection (higher = preferred).
Minimum: -2147483648
Maximum: 2147483647
**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.
**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/client-context#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[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.
Model reference: [MessageFeedback](/api/models/message-feedback#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` | 1 | Canonical | Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice. |
| `FEEDBACK_KIND_SCALE` | 2 | Canonical | Feedback expressed as an integer rating from 1 through 10. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `FEEDBACK_KIND_THUMB`, `FEEDBACK_KIND_SCALE`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**thumbUp** `boolean`
Positive when true and negative when false; used for THUMB feedback.
**rating** `integer(int32)`
Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent.
Minimum: -2147483648
Maximum: 2147483647
**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.
**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).
- Overview: `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.
## 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 (JWT) 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[Message]`
Messages recorded in the conversation history.
Chat message
Model reference: [Message](/api/models/message#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` | 1 | Canonical | Instructions or context provided as a system message. |
| `ROLE_USER` | 2 | Canonical | Input supplied by the user or customer application. |
| `ROLE_ASSISTANT` | 3 | Canonical | Content produced by the assistant, including its tool-call requests. |
| `ROLE_TOOL` | 4 | 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)`
Must not match:
Type: `any`
Enum: `0`
**content** `array[ContentPart]`
Content parts composing the chat message.
Content parts composing a message (flattened structure for JSON compatibility)
Model reference: [ContentPart](/api/models/content-part#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` | 1 | Canonical | Plain text carried by the content part. |
| `CONTENT_PART_TYPE_IMAGE_URL` | 2 | Canonical | An image supplied through a remote URL. |
| `CONTENT_PART_TYPE_IMAGE_BASE64` | 3 | Canonical | An image supplied as base64-encoded bytes. |
| `CONTENT_PART_TYPE_FILE_ID` | 4 | Canonical | A provider file identifier or internal storage identifier resolved before generation. |
| `CONTENT_PART_TYPE_FILE_PATH` | 5 | Canonical | A reference to a local file path. |
| `CONTENT_PART_TYPE_FILE_URL` | 6 | Canonical | A file supplied through a public or signed URL. |
| `CONTENT_PART_TYPE_FILE_DATA_URL` | 7 | Canonical | A file embedded in a data URL, including its media type and encoded data. |
| `CONTENT_PART_TYPE_AUDIO_BASE64` | 8 | Canonical | Base64-encoded audio; the part metadata identifies its audio format. |
| `CONTENT_PART_TYPE_REASONING` | 9 | Canonical | A reasoning segment returned by a model provider, when available. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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/content-part#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/content-part#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/structured-message#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[ToolCall]`
Assistant-to-tool invocations.
A single structured tool call emitted by the model
[`clientToolDeadlineAt`](/api/models/tool-call#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/tool-call#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 one tool call, including approval waiting and terminal outcomes.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `TOOL_EXECUTION_STATUS_PENDING` | 1 | Canonical | The tool call is waiting to begin execution. |
| `TOOL_EXECUTION_STATUS_EXECUTING` | 2 | Canonical | The tool call is currently executing. |
| `TOOL_EXECUTION_STATUS_COMPLETED` | 3 | Canonical | The tool call completed successfully. Responses use this canonical spelling for numeric value 3. |
| `TOOL_EXECUTION_STATUS_SUCCESS` | 3 | Alias of `TOOL_EXECUTION_STATUS_COMPLETED`; Name not accepted for this field; number accepted | Legacy alias of TOOL_EXECUTION_STATUS_COMPLETED with the same numeric value; use COMPLETED for new writes. |
| `TOOL_EXECUTION_STATUS_FAILED` | 4 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. |
| `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 5 | Canonical | The tool call is waiting for approval before it can execute. |
| `TOOL_EXECUTION_STATUS_CANCELLED` | 6 | Canonical | The tool call was cancelled before normal completion. |
| `TOOL_EXECUTION_STATUS_TIMED_OUT` | 7 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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 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", the underlying error. Set only once `status` is
terminal, and empty on a clean COMPLETED.
**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. Mirrors requires_approval_at.
**name** `string`
Name identifying the sender of the chat message.
**timestamp** `string(date-time)`
Timestamp associated with the conversation message or event.
**messageId** `string`
Unique message identifier.
**annotations** `array[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/annotation#response).
**urlCitation** `any`
Submessage fields (optional); populate the one matching kind
All of:
Variant 1:
=== Annotations ===
Web source and character range cited in generated message content.
Model reference: [UrlCitation](/api/models/url-citation#response).
**url** `string`
URL associated with the resource or outbound request.
**title** `string`
Title of the web page cited by this annotation.
**content** `string`
Excerpt or snippet of the cited web page.
**startIndex** `integer(int32)`
Character index in message content.
Minimum: -2147483648
Maximum: 2147483647
**endIndex** `integer(int32)`
Character index in message content.
Minimum: -2147483648
Maximum: 2147483647
**pdf** `any`
PDF annotation or parser configuration selected by the enclosing message.
All of:
Variant 1:
Provider annotation identifying a parsed PDF and reusable parsing output.
Model reference: [PdfAnnotation](/api/models/pdf-annotation#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[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 (flattened structure for JSON compatibility)
Model reference: [ContentPart](/api/models/content-part#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` | 1 | Canonical | Plain text carried by the content part. |
| `CONTENT_PART_TYPE_IMAGE_URL` | 2 | Canonical | An image supplied through a remote URL. |
| `CONTENT_PART_TYPE_IMAGE_BASE64` | 3 | Canonical | An image supplied as base64-encoded bytes. |
| `CONTENT_PART_TYPE_FILE_ID` | 4 | Canonical | A provider file identifier or internal storage identifier resolved before generation. |
| `CONTENT_PART_TYPE_FILE_PATH` | 5 | Canonical | A reference to a local file path. |
| `CONTENT_PART_TYPE_FILE_URL` | 6 | Canonical | A file supplied through a public or signed URL. |
| `CONTENT_PART_TYPE_FILE_DATA_URL` | 7 | Canonical | A file embedded in a data URL, including its media type and encoded data. |
| `CONTENT_PART_TYPE_AUDIO_BASE64` | 8 | Canonical | Base64-encoded audio; the part metadata identifies its audio format. |
| `CONTENT_PART_TYPE_REASONING` | 9 | Canonical | A reasoning segment returned by a model provider, when available. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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/content-part#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/content-part#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/structured-message#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.
**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` | 1 | Canonical | A citation to a source identified by its URL. |
| `ANNOTATION_KIND_PDF` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/usage#response).
**promptTokens** `integer(int32)`
Prompt-token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**completionTokens** `integer(int32)`
Completion-token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**totalTokens** `integer(int32)`
Total token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**costEstimate** `any`
Estimated cost in USD.
Exactly one of:
Variant 1:
Type: `number(float)`
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; one category must not be derived by subtracting the
others.
Model reference: [CompletionTokensDetails](/api/models/completion-tokens-details#response).
**reasoningTokens** `integer(int32)`
Tokens used for reasoning/thinking.
Minimum: -2147483648
Maximum: 2147483647
**imageTokens** `integer(int32)`
Completion tokens emitted as image output.
Minimum: -2147483648
Maximum: 2147483647
**audioTokens** `integer(int32)`
Completion tokens emitted as audio output.
Minimum: -2147483648
Maximum: 2147483647
**promptTokensDetails** `any`
Breakdown of prompt tokens (cache).
All of:
Variant 1:
Breakdown of prompt token usage by category (input-side cache accounting)
Model reference: [PromptTokensDetails](/api/models/prompt-tokens-details#response).
**cachedTokens** `integer(int32)`
Prompt tokens served from cache (cache READ).
Minimum: -2147483648
Maximum: 2147483647
**cacheWriteTokens** `integer(int32)`
Prompt tokens written to cache this call (cache WRITE).
Minimum: -2147483648
Maximum: 2147483647
**audioTokens** `integer(int32)`
Prompt tokens from audio input (multimodal).
Minimum: -2147483648
Maximum: 2147483647
**videoTokens** `integer(int32)`
Prompt tokens from video input (multimodal).
Minimum: -2147483648
Maximum: 2147483647
**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/cost-details#response).
**upstreamInferenceCost** `any`
Total upstream provider cost (USD) on BYOK routes.
Exactly one of:
Variant 1:
Type: `number(float)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**upstreamInferencePromptCost** `any`
Upstream cost attributed to prompt tokens (USD).
Exactly one of:
Variant 1:
Type: `number(float)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**upstreamInferenceCompletionCost** `any`
Upstream cost attributed to completion tokens (USD).
Exactly one of:
Variant 1:
Type: `number(float)`
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/generation-context#response).
**memories** `array[MemoryReference]`
Memory records captured in the generation context.
A memory record retrieved and included in generation context.
Model reference: [MemoryReference](/api/models/memory-reference#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(float)`
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[RelationReference]`
Graph relationships captured in the generation context.
A graph relationship retrieved and included in generation context.
Model reference: [RelationReference](/api/models/relation-reference#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/memory-search-params#response).
**query** `string`
Text submitted to memory retrieval for this generation.
**topK** `integer(int32)`
Maximum memory matches requested during generation-context retrieval.
Minimum: -2147483648
Maximum: 2147483647
**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** `integer(int32)`
Number of memory records returned by the search.
Minimum: -2147483648
Maximum: 2147483647
**relationsReturned** `integer(int32)`
Number of graph relationships returned by the search.
Minimum: -2147483648
Maximum: 2147483647
**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/turn-info#response).
**currentTurn** `integer(int32)`
Current turn position within the generation run.
Minimum: -2147483648
Maximum: 2147483647
**maxTurns** `integer(int32)`
Maximum turns configured for the generation run.
Minimum: -2147483648
Maximum: 2147483647
**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 prompt for a generation turn.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `PROMPT_SOURCE_CLIENT_OVERRIDE` | 1 | Canonical | The caller supplied the prompt through the send request's generation-configuration override. |
| `PROMPT_SOURCE_PROFILE_TEMPLATE` | 2 | Canonical | The prompt was rendered from the active agent profile template. |
| `PROMPT_SOURCE_DEFAULT_CONFIG` | 3 | Canonical | The prompt came from the conversation or project default generation configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**baseConfig** `any`
Generation configuration resolved before per-call overrides and timeout adjustments, with
system_prompt omitted. The active profile supplies the base when selected; otherwise the
conversation default does. May be absent on older turns or when neither supplies a
configuration.
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/generation-config#response).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#response).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: -2147483648
Maximum: 2147483647
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#response).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinition]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinition]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#response).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRule]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#response).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#response).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#response).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**languagePreference** `string`
Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware)
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#response).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#response).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#response).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#response).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#response).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#response).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
**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/generation-config#response).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#response).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: -2147483648
Maximum: 2147483647
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#response).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinition]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinition]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#response).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRule]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#response).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#response).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#response).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**languagePreference** `string`
Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware)
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#response).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#response).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#response).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#response).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#response).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#response).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
**profileVersion** `integer(int32)`
Immutable version of the active agent profile used to render this turn’s prompt. Absent on
older turns and turns without a profile template.
Minimum: -2147483648
Maximum: 2147483647
**fragmentsVersion** `integer(int32)`
Version of the prompt-fragment set used to render the profile prompt.
Minimum: -2147483648
Maximum: 2147483647
**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 [User Context] block as rendered into this turn's prompt: the user's
name, locale, and location conditions (weather/AQI/UV/sun times). This is
the literal text the model received, not a reconstruction.
Empty when the user has no stored location, when enrichment degraded, or
on turns predating capture.
**resolvedMcpServers** `array[MCPServerReference]`
The MCP server list that governed this turn — the tier actually resolved
(conversation settings -> active profile -> per-turn override_mcp_servers),
which is simultaneously the tool-discovery source and the CallTool
allow/block basis.
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/mcp-server-reference#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** `integer(int32)`
Priority override for tool selection (higher = preferred).
Minimum: -2147483648
Maximum: 2147483647
**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.
**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/client-context#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[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.
Model reference: [MessageFeedback](/api/models/message-feedback#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` | 1 | Canonical | Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice. |
| `FEEDBACK_KIND_SCALE` | 2 | Canonical | Feedback expressed as an integer rating from 1 through 10. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `FEEDBACK_KIND_THUMB`, `FEEDBACK_KIND_SCALE`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**thumbUp** `boolean`
Positive when true and negative when false; used for THUMB feedback.
**rating** `integer(int32)`
Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent.
Minimum: -2147483648
Maximum: 2147483647
**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.
**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/generation-config#response).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#response).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: -2147483648
Maximum: 2147483647
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#response).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinition]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinition]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#response).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRule]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#response).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#response).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#response).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**languagePreference** `string`
Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware)
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#response).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#response).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#response).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#response).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#response).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#response).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
**settings** `any`
Conversation settings returned or supplied for this operation.
All of:
Variant 1:
Conversation-level settings controlling behavior across sends
[`maxLoops`](/api/models/conversation-settings#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/generation-config#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/conversation-settings#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` | 1 | Canonical | Reject the new send with an error while a run is active; do not append its user message. |
| `INTERRUPT_POLICY_CANCEL_ONGOING` | 2 | Canonical | Cancel the ongoing run and start a new run for the incoming message. |
| `INTERRUPT_POLICY_QUEUE` | 3 | Canonical | Queue the incoming message to run after the current run completes. |
| `INTERRUPT_POLICY_IGNORE` | 4 | Canonical | Accept the send without persisting its message or starting a new run; let the ongoing run continue. |
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)`
Must not match:
Type: `any`
Enum: `0`
**maxLoops** `integer(int32)`
Default limit on agentic generation loops for the conversation.
Minimum: -2147483648
Maximum: 2147483647
**maxParallelTools** `integer(int32)`
Maximum number of tool executions allowed concurrently by this configuration.
Minimum: -2147483648
Maximum: 2147483647
**mcpServers** `array[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/mcp-server-reference#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** `integer(int32)`
Priority override for tool selection (higher = preferred).
Minimum: -2147483648
Maximum: 2147483647
**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.
**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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#response).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRule]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#response).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#response).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#response).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**promptVariables** `map[string, any]`
Typed values used when rendering profile prompt templates. They 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/context-management-settings#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` | 1 | Canonical | Use completed compaction summaries and remaining history; fall back to windowing when no completed summary is available. |
| `CONTEXT_STRATEGY_WINDOWING` | 2 | Canonical | Keep a bounded window of recent conversation messages according to the windowing configuration. |
| `CONTEXT_STRATEGY_NONE` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**compactionConfig** `any`
Configuration applied when summarizing the conversation context.
All of:
Variant 1:
Configuration for compaction strategy
Model reference: [CompactionConfig](/api/models/compaction-config#response).
**mode** `any`
Context compaction mode selected by the operation.
Whether context compaction blocks the triggering operation or proceeds asynchronously.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `COMPACTION_MODE_SYNC` | 1 | Canonical | Wait for compaction to finish before continuing the dependent operation. |
| `COMPACTION_MODE_ASYNC` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**threshold** `any`
Token-count or context-window-percentage threshold that triggers compaction.
All of:
Variant 1:
Threshold configuration for triggering compaction
Model reference: [ThresholdConfig](/api/models/threshold-config#response).
All of:
Variant 1:
Type: `any`
Must not match:
Type: `any`
**tokenCount** `integer(int32)`
Absolute token limit.
Minimum: -2147483648
Maximum: 2147483647
**percentage** `integer(int32)`
% of model's context window.
Minimum: -2147483648
Maximum: 2147483647
**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/generation-config#response).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#response).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: -2147483648
Maximum: 2147483647
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#response).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinition]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinition]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#response).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRule]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#response).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#response).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#response).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**languagePreference** `string`
Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware)
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#response).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#response).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#response).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#response).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#response).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#response).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
**preserveRecent** `integer(int32)`
Messages to keep uncompacted.
Minimum: -2147483648
Maximum: 2147483647
**windowingConfig** `any`
Rules selecting the message window retained in model context.
All of:
Variant 1:
Configuration for windowing strategy
Model reference: [WindowingConfig](/api/models/windowing-config#response).
**maxMessages** `integer(int32)`
Maximum number of conversation messages to retain in the context window.
Minimum: -2147483648
Maximum: 2147483647
**selectiveExclusionConfig** `any`
Rules selecting content to omit from the model context.
All of:
Variant 1:
Configuration for selective exclusion
Model reference: [SelectiveExclusionConfig](/api/models/selective-exclusion-config#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[Compaction]`
Recorded context compaction operations for the conversation.
Compaction metadata
Model reference: [Compaction](/api/models/compaction#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** `integer(int32)`
Estimated token count of the context before compaction.
Minimum: -2147483648
Maximum: 2147483647
**summaryTokenCount** `integer(int32)`
Estimated token count of the generated summary.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Compaction was started and its result is still pending. |
| `COMPACTION_STATUS_COMPLETED` | 2 | Canonical | Compaction completed and produced its result. |
| `COMPACTION_STATUS_FAILED` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**triggerReason** `any`
Reason for triggering this compaction (auto threshold vs manual)
Reason a conversation context-compaction attempt was started.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `COMPACTION_TRIGGER_REASON_THRESHOLD_EXCEEDED` | 1 | Canonical | Context usage crossed the configured compaction threshold. |
| `COMPACTION_TRIGGER_REASON_MANUAL` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**compactionInProgress** `boolean`
Whether a context compaction is currently in progress.
**totalUsage** `any`
Cumulative token usage and cost for the conversation. Absent when no usage has accrued.
All of:
Variant 1:
Usage accounting
Model reference: [Usage](/api/models/usage#response).
**promptTokens** `integer(int32)`
Prompt-token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**completionTokens** `integer(int32)`
Completion-token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**totalTokens** `integer(int32)`
Total token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**costEstimate** `any`
Estimated cost in USD.
Exactly one of:
Variant 1:
Type: `number(float)`
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; one category must not be derived by subtracting the
others.
Model reference: [CompletionTokensDetails](/api/models/completion-tokens-details#response).
**reasoningTokens** `integer(int32)`
Tokens used for reasoning/thinking.
Minimum: -2147483648
Maximum: 2147483647
**imageTokens** `integer(int32)`
Completion tokens emitted as image output.
Minimum: -2147483648
Maximum: 2147483647
**audioTokens** `integer(int32)`
Completion tokens emitted as audio output.
Minimum: -2147483648
Maximum: 2147483647
**promptTokensDetails** `any`
Breakdown of prompt tokens (cache).
All of:
Variant 1:
Breakdown of prompt token usage by category (input-side cache accounting)
Model reference: [PromptTokensDetails](/api/models/prompt-tokens-details#response).
**cachedTokens** `integer(int32)`
Prompt tokens served from cache (cache READ).
Minimum: -2147483648
Maximum: 2147483647
**cacheWriteTokens** `integer(int32)`
Prompt tokens written to cache this call (cache WRITE).
Minimum: -2147483648
Maximum: 2147483647
**audioTokens** `integer(int32)`
Prompt tokens from audio input (multimodal).
Minimum: -2147483648
Maximum: 2147483647
**videoTokens** `integer(int32)`
Prompt tokens from video input (multimodal).
Minimum: -2147483648
Maximum: 2147483647
**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/cost-details#response).
**upstreamInferenceCost** `any`
Total upstream provider cost (USD) on BYOK routes.
Exactly one of:
Variant 1:
Type: `number(float)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**upstreamInferencePromptCost** `any`
Upstream cost attributed to prompt tokens (USD).
Exactly one of:
Variant 1:
Type: `number(float)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**upstreamInferenceCompletionCost** `any`
Upstream cost attributed to completion tokens (USD).
Exactly one of:
Variant 1:
Type: `number(float)`
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 completed generation run. Unset until a run has ended.
Execution state of an agent generation run, separate from the reason a terminal run ended.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `AGENT_STATUS_ACTIVE` | 1 | Canonical | The run is active and has not yet reached a more specific execution phase or terminal outcome. |
| `AGENT_STATUS_GENERATING` | 2 | Canonical | The run is generating a model response. |
| `AGENT_STATUS_EXECUTING_TOOLS` | 3 | Canonical | The run is executing server-side tools. |
| `AGENT_STATUS_COMPLETED` | 4 | Canonical | The run finished successfully. |
| `AGENT_STATUS_FAILED` | 5 | Canonical | The run ended with a failure; inspect its error or end reason. |
| `AGENT_STATUS_QUEUED` | 6 | Canonical | The incoming message is queued behind an ongoing run under the queue interruption policy. |
| `AGENT_STATUS_AWAITING_CLIENT_TOOLS` | 7 | Canonical | The run is waiting for the caller to execute client-side tools and submit their results. |
| `AGENT_STATUS_CANCELLED` | 8 | Canonical | The run ended because a client or its invocation cancelled it. |
| `AGENT_STATUS_TIMED_OUT` | 9 | Canonical | The run ended because a run-level time limit 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)`
Must not match:
Type: `any`
Enum: `0`
#### 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).
- Overview: `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.
## 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 (JWT) 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/memory/models/memory#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(float)`
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).
- Overview: `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.
## 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 (JWT) 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/tool-call#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/tool-call#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 one tool call, including approval waiting and terminal outcomes.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `TOOL_EXECUTION_STATUS_PENDING` | 1 | Canonical | The tool call is waiting to begin execution. |
| `TOOL_EXECUTION_STATUS_EXECUTING` | 2 | Canonical | The tool call is currently executing. |
| `TOOL_EXECUTION_STATUS_COMPLETED` | 3 | Canonical | The tool call completed successfully. Responses use this canonical spelling for numeric value 3. |
| `TOOL_EXECUTION_STATUS_SUCCESS` | 3 | Alias of `TOOL_EXECUTION_STATUS_COMPLETED`; Name not accepted for this field; number accepted | Legacy alias of TOOL_EXECUTION_STATUS_COMPLETED with the same numeric value; use COMPLETED for new writes. |
| `TOOL_EXECUTION_STATUS_FAILED` | 4 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. |
| `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 5 | Canonical | The tool call is waiting for approval before it can execute. |
| `TOOL_EXECUTION_STATUS_CANCELLED` | 6 | Canonical | The tool call was cancelled before normal completion. |
| `TOOL_EXECUTION_STATUS_TIMED_OUT` | 7 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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 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", the underlying error. Set only once `status` is
terminal, and empty on a clean COMPLETED.
**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. Mirrors requires_approval_at.
#### 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).
- Overview: `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.
## 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 (JWT) 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** `integer(int32)` **required**
Maximum number of memories to return. Supply explicitly; omission is rejected.
Minimum: 1
Maximum: 100
#### 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]`
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/memory/models/memory#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(float)`
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).
- Overview: `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.
## 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 (JWT) 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[ToolCall]`
Tool calls waiting for a caller approval decision.
A single structured tool call emitted by the model
[`clientToolDeadlineAt`](/api/models/tool-call#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/tool-call#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 one tool call, including approval waiting and terminal outcomes.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `TOOL_EXECUTION_STATUS_PENDING` | 1 | Canonical | The tool call is waiting to begin execution. |
| `TOOL_EXECUTION_STATUS_EXECUTING` | 2 | Canonical | The tool call is currently executing. |
| `TOOL_EXECUTION_STATUS_COMPLETED` | 3 | Canonical | The tool call completed successfully. Responses use this canonical spelling for numeric value 3. |
| `TOOL_EXECUTION_STATUS_SUCCESS` | 3 | Alias of `TOOL_EXECUTION_STATUS_COMPLETED`; Name not accepted for this field; number accepted | Legacy alias of TOOL_EXECUTION_STATUS_COMPLETED with the same numeric value; use COMPLETED for new writes. |
| `TOOL_EXECUTION_STATUS_FAILED` | 4 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. |
| `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 5 | Canonical | The tool call is waiting for approval before it can execute. |
| `TOOL_EXECUTION_STATUS_CANCELLED` | 6 | Canonical | The tool call was cancelled before normal completion. |
| `TOOL_EXECUTION_STATUS_TIMED_OUT` | 7 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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 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", the underlying error. Set only once `status` is
terminal, and empty on a clean COMPLETED.
**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. Mirrors requires_approval_at.
#### 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).
- Overview: `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.
## 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 (JWT) 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[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/tool-call#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/tool-call#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 one tool call, including approval waiting and terminal outcomes.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `TOOL_EXECUTION_STATUS_PENDING` | 1 | Canonical | The tool call is waiting to begin execution. |
| `TOOL_EXECUTION_STATUS_EXECUTING` | 2 | Canonical | The tool call is currently executing. |
| `TOOL_EXECUTION_STATUS_COMPLETED` | 3 | Canonical | The tool call completed successfully. Responses use this canonical spelling for numeric value 3. |
| `TOOL_EXECUTION_STATUS_SUCCESS` | 3 | Alias of `TOOL_EXECUTION_STATUS_COMPLETED`; Name not accepted for this field; number accepted | Legacy alias of TOOL_EXECUTION_STATUS_COMPLETED with the same numeric value; use COMPLETED for new writes. |
| `TOOL_EXECUTION_STATUS_FAILED` | 4 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. |
| `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 5 | Canonical | The tool call is waiting for approval before it can execute. |
| `TOOL_EXECUTION_STATUS_CANCELLED` | 6 | Canonical | The tool call was cancelled before normal completion. |
| `TOOL_EXECUTION_STATUS_TIMED_OUT` | 7 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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 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", the underlying error. Set only once `status` is
terminal, and empty on a clean COMPLETED.
**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. Mirrors requires_approval_at.
#### 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).
- Overview: `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.
## 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 (JWT) via `Authorization: Bearer `
## Request Body
*Required*
Content type: `application/json`
Input for listing conversation threads visible to the caller.
**limit** `integer(int32)`
Max rows per page. 0 -> service default (50). Values >200 are clamped
to 200 downstream. Negative values are rejected by proto validation.
Minimum: 0
Maximum: 2147483647
**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[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/thread-summary#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.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CONVERSATION_STATUS_ACTIVE` | 1 | Canonical | The conversation is in its active lifecycle state. |
| `CONVERSATION_STATUS_ARCHIVED` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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).
- Overview: `DOC-MA-conversations-api-listThreads#overview`
- Request: `DOC-MA-conversations-api-listThreads#request`
- Responses: `DOC-MA-conversations-api-listThreads#responses`
---
# LLM APIs
URL: https://docs.travila.ai/api/conversations
Version: `1.0.0`
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](/managed-agents/voice-media). Native endpoints do not use the OpenAI wire protocol.
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](/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](/managed-agents/conversations), [Agent tools](/integrations/tools-connections), [Memory](/managed-agents/memory-knowledge), [Streaming availability](/managed-agents/conversations/streaming)
### 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](/api).
## Authentication {#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.
Security scheme type: `apiKey`
Parameter location: `header`
Parameter name: `X-API-Key`
### 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`.
Security scheme type: `apiKey`
Parameter location: `header`
Parameter name: `X-On-Behalf-Of`
### 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`.
Security scheme type: `http`
HTTP authorization scheme: `bearer`
Bearer format: `JWT`
## Operations
- [Append a message without generating](/api/conversations/append-message) — `POST /api/v1/llm/append-message`
- [Compact a conversation](/api/conversations/compact-conversation) — `POST /api/v1/llm/compact-conversation`
- [Create a voice session (in progress)](/api/conversations/create-daily-session) — `POST /api/v1/llm/create-daily-session`
- [Create a new conversation thread](/api/conversations/create-thread) — `POST /api/v1/llm/create-thread`
- [Delete a memory](/api/conversations/delete-memory) — `POST /api/v1/llm/delete-memory`
- [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 specific memory](/api/conversations/get-memory) — `POST /api/v1/llm/get-memory`
- [Get a single tool call by ID](/api/conversations/get-tool-call) — `POST /api/v1/llm/get-tool-call`
- [List user memories](/api/conversations/list-memories) — `POST /api/v1/llm/list-memories`
- [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`
- [List conversation threads](/api/conversations/list-threads) — `POST /api/v1/llm/list-threads`
- [Execute an MCP tool](/api/conversations/mcp-call-tool) — `POST /api/v1/llm/mcp-call-tool`
- [Get an MCP prompt template](/api/conversations/mcp-get-prompt) — `POST /api/v1/llm/mcp-get-prompt`
- [Get detailed MCP server info](/api/conversations/mcp-get-server-info) — `POST /api/v1/llm/mcp-get-server-info`
- [List available MCP servers](/api/conversations/mcp-list-available-servers) — `POST /api/v1/llm/mcp-list-available-servers`
- [List MCP prompt templates](/api/conversations/mcp-list-prompts) — `POST /api/v1/llm/mcp-list-prompts`
- [List MCP resources](/api/conversations/mcp-list-resources) — `POST /api/v1/llm/mcp-list-resources`
- [List available MCP tools](/api/conversations/mcp-list-tools) — `POST /api/v1/llm/mcp-list-tools`
- [Read an MCP resource](/api/conversations/mcp-read-resource) — `POST /api/v1/llm/mcp-read-resource`
- [Mint a speech-to-text token (in progress)](/api/conversations/mint-stt-token) — `POST /api/v1/llm/stt-token`
- [Rate an assistant message](/api/conversations/rate-message) — `POST /api/v1/llm/rate-message`
- [Semantic search over memories](/api/conversations/search-memories) — `POST /api/v1/llm/search-memories`
- [Send a message and wait for the result](/api/conversations/send-message-sync) — `POST /api/v1/llm/send-message-sync`
- [Send a message to a conversation](/api/conversations/send-message) — `POST /api/v1/llm/send-message`
- [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`
- [Approve or reject pending tool calls](/api/conversations/submit-tool-approvals) — `POST /api/v1/llm/submit-tool-approvals`
- [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 a memory](/api/conversations/update-memory) — `POST /api/v1/llm/update-memory`
- [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`
Document ID: `DOC-MA-conversations-api-overview`. [Section identities and revisions](/documentation-manifest.json).
- Overview: `DOC-MA-conversations-api-overview#overview`
- JSON conventions: `DOC-MA-conversations-api-overview#json-conventions`
- Authentication: `DOC-MA-conversations-api-overview#authentication`
---
# 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.
## 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 (JWT) 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/tool-call#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/tool-call#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 one tool call, including approval waiting and terminal outcomes.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `TOOL_EXECUTION_STATUS_PENDING` | 1 | Canonical | The tool call is waiting to begin execution. |
| `TOOL_EXECUTION_STATUS_EXECUTING` | 2 | Canonical | The tool call is currently executing. |
| `TOOL_EXECUTION_STATUS_COMPLETED` | 3 | Canonical | The tool call completed successfully. Responses use this canonical spelling for numeric value 3. |
| `TOOL_EXECUTION_STATUS_SUCCESS` | 3 | Alias of `TOOL_EXECUTION_STATUS_COMPLETED` | Legacy alias of TOOL_EXECUTION_STATUS_COMPLETED with the same numeric value; use COMPLETED for new writes. |
| `TOOL_EXECUTION_STATUS_FAILED` | 4 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. |
| `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 5 | Canonical | The tool call is waiting for approval before it can execute. |
| `TOOL_EXECUTION_STATUS_CANCELLED` | 6 | Canonical | The tool call was cancelled before normal completion. |
| `TOOL_EXECUTION_STATUS_TIMED_OUT` | 7 | 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_SUCCESS`, `TOOL_EXECUTION_STATUS_FAILED`, `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION`, `TOOL_EXECUTION_STATUS_CANCELLED`, `TOOL_EXECUTION_STATUS_TIMED_OUT`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**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 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", the underlying error. Set only once `status` is
terminal, and empty on a clean COMPLETED.
**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. Mirrors requires_approval_at.
**requestId** `string`
Correlation identifier for the MCP tool execution request.
**sessionId** `string`
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.
All of:
Variant 1:
A single structured tool call emitted by the model
[`clientToolDeadlineAt`](/api/models/tool-call#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/tool-call#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 one tool call, including approval waiting and terminal outcomes.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `TOOL_EXECUTION_STATUS_PENDING` | 1 | Canonical | The tool call is waiting to begin execution. |
| `TOOL_EXECUTION_STATUS_EXECUTING` | 2 | Canonical | The tool call is currently executing. |
| `TOOL_EXECUTION_STATUS_COMPLETED` | 3 | Canonical | The tool call completed successfully. Responses use this canonical spelling for numeric value 3. |
| `TOOL_EXECUTION_STATUS_SUCCESS` | 3 | Alias of `TOOL_EXECUTION_STATUS_COMPLETED`; Name not accepted for this field; number accepted | Legacy alias of TOOL_EXECUTION_STATUS_COMPLETED with the same numeric value; use COMPLETED for new writes. |
| `TOOL_EXECUTION_STATUS_FAILED` | 4 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. |
| `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 5 | Canonical | The tool call is waiting for approval before it can execute. |
| `TOOL_EXECUTION_STATUS_CANCELLED` | 6 | Canonical | The tool call was cancelled before normal completion. |
| `TOOL_EXECUTION_STATUS_TIMED_OUT` | 7 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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 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", the underlying error. Set only once `status` is
terminal, and empty on a clean COMPLETED.
**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. Mirrors requires_approval_at.
**executionTimeMs** `integer(int32)`
Reported duration of MCP tool execution, in milliseconds.
Minimum: -2147483648
Maximum: 2147483647
#### 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).
- Overview: `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.
## 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 (JWT) 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/prompt-definition#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[PromptParameter]`
Parameter definitions accepted by the prompt template.
A parameter used by a prompt template
Model reference: [PromptParameter](/api/models/prompt-parameter#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).
- Overview: `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.
## 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 (JWT) 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/mcp-server-info#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` | 1 | Canonical | A connection to the MCP server is established. |
| `MCP_SERVER_CONNECTION_STATUS_DISCONNECTED` | 2 | Canonical | There is no active connection to the MCP server. |
| `MCP_SERVER_CONNECTION_STATUS_ERROR` | 3 | Canonical | A connection or discovery attempt encountered an error. |
| `MCP_SERVER_CONNECTION_STATUS_DISCOVERING` | 4 | 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)`
Must not match:
Type: `any`
Enum: `0`
**availableTools** `array[ToolDefinition]`
Tool definitions currently reported by the MCP server.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `MCP_SERVER_KIND_INTERNAL` | 1 | Canonical | A server compiled into the deployment and dispatched in-process. |
| `MCP_SERVER_KIND_BUILT_IN` | 2 | Canonical | A platform-owned catalog server invoked with platform-held vendor credentials. |
| `MCP_SERVER_KIND_CUSTOM` | 3 | Canonical | A tenant-registered server invoked with the tenant's credentials. |
| `MCP_SERVER_KIND_EXTERNAL` | 4 | Canonical | A legacy externally configured server; this category does not designate a new tenant registration. |
| `MCP_SERVER_KIND_INTEGRATION` | 5 | Canonical | An account-connected 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)`
Must not match:
Type: `any`
Enum: `0`
#### 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).
- Overview: `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. [`defaultEnabled`](/api/models/mcp-server-status#response-field-defaultenabled) is a recommendation, not a setting that attaches tools to your conversation.
## 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 (JWT) via `Authorization: Bearer `
## Request Body
*Required*
Content type: `application/json`
Server management
**includeDisconnected** `boolean`
Whether the server listing should include disconnected MCP servers.
**kinds** `array[any]`
Restrict the listing to these ownership classes. Empty = every kind, so an
existing caller that omits it sees no behavior change. Lets a console
request a narrow view without standing up a new endpoint.
Ownership and connection category of an MCP server available to the platform.
Ownership and connection category of an MCP server available to the platform.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `MCP_SERVER_KIND_INTERNAL` | 1 | Canonical | A server compiled into the deployment and dispatched in-process. |
| `MCP_SERVER_KIND_BUILT_IN` | 2 | Canonical | A platform-owned catalog server invoked with platform-held vendor credentials. |
| `MCP_SERVER_KIND_CUSTOM` | 3 | Canonical | A tenant-registered server invoked with the tenant's credentials. |
| `MCP_SERVER_KIND_EXTERNAL` | 4 | Canonical | A legacy externally configured server; this category does not designate a new tenant registration. |
| `MCP_SERVER_KIND_INTEGRATION` | 5 | Canonical | An account-connected 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)`
Must not match:
Type: `any`
Enum: `0`
#### 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[MCPServerStatus]`
Connection status of each MCP server included in the listing.
MCP Server Status
Status information about an MCP server (used in responses)
Model reference: [MCPServerStatus](/api/models/mcp-server-status#response).
**serverId** `string`
Identifier of the MCP server associated with the operation or tool.
**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` | 1 | Canonical | A connection to the MCP server is established. |
| `MCP_SERVER_CONNECTION_STATUS_DISCONNECTED` | 2 | Canonical | There is no active connection to the MCP server. |
| `MCP_SERVER_CONNECTION_STATUS_ERROR` | 3 | Canonical | A connection or discovery attempt encountered an error. |
| `MCP_SERVER_CONNECTION_STATUS_DISCOVERING` | 4 | 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)`
Must not match:
Type: `any`
Enum: `0`
**toolsDiscovered** `integer(int32)`
Number of tool definitions found during the last discovery.
Minimum: -2147483648
Maximum: 2147483647
**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.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `MCP_SERVER_KIND_INTERNAL` | 1 | Canonical | A server compiled into the deployment and dispatched in-process. |
| `MCP_SERVER_KIND_BUILT_IN` | 2 | Canonical | A platform-owned catalog server invoked with platform-held vendor credentials. |
| `MCP_SERVER_KIND_CUSTOM` | 3 | Canonical | A tenant-registered server invoked with the tenant's credentials. |
| `MCP_SERVER_KIND_EXTERNAL` | 4 | Canonical | A legacy externally configured server; this category does not designate a new tenant registration. |
| `MCP_SERVER_KIND_INTEGRATION` | 5 | Canonical | An account-connected 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)`
Must not match:
Type: `any`
Enum: `0`
**defaultEnabled** `boolean`
Whether the built-in catalog recommends this server by default. This is a catalog
recommendation, not whether the server is enabled for a particular profile or conversation.
#### 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",
"defaultEnabled": true
}
]
}
```
Document ID: `DOC-MA-conversations-api-mcpListAvailableServers`. [Section identities and revisions](/documentation-manifest.json).
- Overview: `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.
## 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 (JWT) via `Authorization: Bearer `
## Request Body
*Required*
Content type: `application/json`
Prompts
**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[PromptDefinition]`
Prompt templates returned by MCP discovery.
A prompt definition exposed by an MCP server
Model reference: [PromptDefinition](/api/models/prompt-definition#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[PromptParameter]`
Parameter definitions accepted by the prompt template.
A parameter used by a prompt template
Model reference: [PromptParameter](/api/models/prompt-parameter#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** `integer(int32)`
Number of entries reported by the MCP operation.
Minimum: -2147483648
Maximum: 2147483647
#### 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).
- Overview: `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.
## 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 (JWT) via `Authorization: Bearer `
## Request Body
*Required*
Content type: `application/json`
Resources
**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[Resource]`
Resource descriptions returned by MCP discovery.
A resource exposed by an MCP server
Model reference: [Resource](/api/models/resource#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[ContentPart]`
Optional embedded content.
Content parts composing a message (flattened structure for JSON compatibility)
Model reference: [ContentPart](/api/models/content-part#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` | 1 | Canonical | Plain text carried by the content part. |
| `CONTENT_PART_TYPE_IMAGE_URL` | 2 | Canonical | An image supplied through a remote URL. |
| `CONTENT_PART_TYPE_IMAGE_BASE64` | 3 | Canonical | An image supplied as base64-encoded bytes. |
| `CONTENT_PART_TYPE_FILE_ID` | 4 | Canonical | A provider file identifier or internal storage identifier resolved before generation. |
| `CONTENT_PART_TYPE_FILE_PATH` | 5 | Canonical | A reference to a local file path. |
| `CONTENT_PART_TYPE_FILE_URL` | 6 | Canonical | A file supplied through a public or signed URL. |
| `CONTENT_PART_TYPE_FILE_DATA_URL` | 7 | Canonical | A file embedded in a data URL, including its media type and encoded data. |
| `CONTENT_PART_TYPE_AUDIO_BASE64` | 8 | Canonical | Base64-encoded audio; the part metadata identifies its audio format. |
| `CONTENT_PART_TYPE_REASONING` | 9 | Canonical | A reasoning segment returned by a model provider, when available. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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/content-part#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/content-part#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/structured-message#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** `integer(int32)`
Number of entries reported by the MCP operation.
Minimum: -2147483648
Maximum: 2147483647
#### 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).
- Overview: `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.
## 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 (JWT) via `Authorization: Bearer `
## Request Body
*Required*
Content type: `application/json`
Tool operations
**servers** `array[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/mcp-server-reference#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** `integer(int32)`
Priority override for tool selection (higher = preferred).
Minimum: -2147483648
Maximum: 2147483647
**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.
**sessionId** `string`
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[ToolDefinition]`
Tool definitions returned by MCP discovery.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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** `integer(int32)`
Number of entries reported by the MCP operation.
Minimum: -2147483648
Maximum: 2147483647
#### 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).
- Overview: `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.
## 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 (JWT) 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/resource#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[ContentPart]`
Optional embedded content.
Content parts composing a message (flattened structure for JSON compatibility)
Model reference: [ContentPart](/api/models/content-part#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` | 1 | Canonical | Plain text carried by the content part. |
| `CONTENT_PART_TYPE_IMAGE_URL` | 2 | Canonical | An image supplied through a remote URL. |
| `CONTENT_PART_TYPE_IMAGE_BASE64` | 3 | Canonical | An image supplied as base64-encoded bytes. |
| `CONTENT_PART_TYPE_FILE_ID` | 4 | Canonical | A provider file identifier or internal storage identifier resolved before generation. |
| `CONTENT_PART_TYPE_FILE_PATH` | 5 | Canonical | A reference to a local file path. |
| `CONTENT_PART_TYPE_FILE_URL` | 6 | Canonical | A file supplied through a public or signed URL. |
| `CONTENT_PART_TYPE_FILE_DATA_URL` | 7 | Canonical | A file embedded in a data URL, including its media type and encoded data. |
| `CONTENT_PART_TYPE_AUDIO_BASE64` | 8 | Canonical | Base64-encoded audio; the part metadata identifies its audio format. |
| `CONTENT_PART_TYPE_REASONING` | 9 | Canonical | A reasoning segment returned by a model provider, when available. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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/content-part#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/content-part#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/structured-message#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).
- Overview: `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.
## 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 (JWT) 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** `integer(int32)`
Lifetime of the issued access token, in seconds.
Minimum: -2147483648
Maximum: 2147483647
#### 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).
- Overview: `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.
## 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 (JWT) 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` | 1 | Canonical | Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice. |
| `FEEDBACK_KIND_SCALE` | 2 | Canonical | Feedback expressed as an integer rating from 1 through 10. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `FEEDBACK_KIND_THUMB`, `FEEDBACK_KIND_SCALE`
Variant 2:
Type: `integer(int32)`
Enum: `1`, `2`
Must not match:
Type: `any`
Enum: `0`
**thumbUp** `boolean`
Positive when true and negative when false; used for THUMB feedback.
**rating** `integer(int32)`
Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent.
Minimum: 0
Maximum: 10
**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
Model reference: [Message](/api/models/message#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` | 1 | Canonical | Instructions or context provided as a system message. |
| `ROLE_USER` | 2 | Canonical | Input supplied by the user or customer application. |
| `ROLE_ASSISTANT` | 3 | Canonical | Content produced by the assistant, including its tool-call requests. |
| `ROLE_TOOL` | 4 | 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)`
Must not match:
Type: `any`
Enum: `0`
**content** `array[ContentPart]`
Content parts composing the chat message.
Content parts composing a message (flattened structure for JSON compatibility)
Model reference: [ContentPart](/api/models/content-part#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` | 1 | Canonical | Plain text carried by the content part. |
| `CONTENT_PART_TYPE_IMAGE_URL` | 2 | Canonical | An image supplied through a remote URL. |
| `CONTENT_PART_TYPE_IMAGE_BASE64` | 3 | Canonical | An image supplied as base64-encoded bytes. |
| `CONTENT_PART_TYPE_FILE_ID` | 4 | Canonical | A provider file identifier or internal storage identifier resolved before generation. |
| `CONTENT_PART_TYPE_FILE_PATH` | 5 | Canonical | A reference to a local file path. |
| `CONTENT_PART_TYPE_FILE_URL` | 6 | Canonical | A file supplied through a public or signed URL. |
| `CONTENT_PART_TYPE_FILE_DATA_URL` | 7 | Canonical | A file embedded in a data URL, including its media type and encoded data. |
| `CONTENT_PART_TYPE_AUDIO_BASE64` | 8 | Canonical | Base64-encoded audio; the part metadata identifies its audio format. |
| `CONTENT_PART_TYPE_REASONING` | 9 | Canonical | A reasoning segment returned by a model provider, when available. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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/content-part#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/content-part#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/structured-message#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[ToolCall]`
Assistant-to-tool invocations.
A single structured tool call emitted by the model
[`clientToolDeadlineAt`](/api/models/tool-call#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/tool-call#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 one tool call, including approval waiting and terminal outcomes.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `TOOL_EXECUTION_STATUS_PENDING` | 1 | Canonical | The tool call is waiting to begin execution. |
| `TOOL_EXECUTION_STATUS_EXECUTING` | 2 | Canonical | The tool call is currently executing. |
| `TOOL_EXECUTION_STATUS_COMPLETED` | 3 | Canonical | The tool call completed successfully. Responses use this canonical spelling for numeric value 3. |
| `TOOL_EXECUTION_STATUS_SUCCESS` | 3 | Alias of `TOOL_EXECUTION_STATUS_COMPLETED`; Name not accepted for this field; number accepted | Legacy alias of TOOL_EXECUTION_STATUS_COMPLETED with the same numeric value; use COMPLETED for new writes. |
| `TOOL_EXECUTION_STATUS_FAILED` | 4 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. |
| `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 5 | Canonical | The tool call is waiting for approval before it can execute. |
| `TOOL_EXECUTION_STATUS_CANCELLED` | 6 | Canonical | The tool call was cancelled before normal completion. |
| `TOOL_EXECUTION_STATUS_TIMED_OUT` | 7 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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 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", the underlying error. Set only once `status` is
terminal, and empty on a clean COMPLETED.
**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. Mirrors requires_approval_at.
**name** `string`
Name identifying the sender of the chat message.
**timestamp** `string(date-time)`
Timestamp associated with the conversation message or event.
**messageId** `string`
Unique message identifier.
**annotations** `array[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/annotation#response).
**urlCitation** `any`
Submessage fields (optional); populate the one matching kind
All of:
Variant 1:
=== Annotations ===
Web source and character range cited in generated message content.
Model reference: [UrlCitation](/api/models/url-citation#response).
**url** `string`
URL associated with the resource or outbound request.
**title** `string`
Title of the web page cited by this annotation.
**content** `string`
Excerpt or snippet of the cited web page.
**startIndex** `integer(int32)`
Character index in message content.
Minimum: -2147483648
Maximum: 2147483647
**endIndex** `integer(int32)`
Character index in message content.
Minimum: -2147483648
Maximum: 2147483647
**pdf** `any`
PDF annotation or parser configuration selected by the enclosing message.
All of:
Variant 1:
Provider annotation identifying a parsed PDF and reusable parsing output.
Model reference: [PdfAnnotation](/api/models/pdf-annotation#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[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 (flattened structure for JSON compatibility)
Model reference: [ContentPart](/api/models/content-part#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` | 1 | Canonical | Plain text carried by the content part. |
| `CONTENT_PART_TYPE_IMAGE_URL` | 2 | Canonical | An image supplied through a remote URL. |
| `CONTENT_PART_TYPE_IMAGE_BASE64` | 3 | Canonical | An image supplied as base64-encoded bytes. |
| `CONTENT_PART_TYPE_FILE_ID` | 4 | Canonical | A provider file identifier or internal storage identifier resolved before generation. |
| `CONTENT_PART_TYPE_FILE_PATH` | 5 | Canonical | A reference to a local file path. |
| `CONTENT_PART_TYPE_FILE_URL` | 6 | Canonical | A file supplied through a public or signed URL. |
| `CONTENT_PART_TYPE_FILE_DATA_URL` | 7 | Canonical | A file embedded in a data URL, including its media type and encoded data. |
| `CONTENT_PART_TYPE_AUDIO_BASE64` | 8 | Canonical | Base64-encoded audio; the part metadata identifies its audio format. |
| `CONTENT_PART_TYPE_REASONING` | 9 | Canonical | A reasoning segment returned by a model provider, when available. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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/content-part#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/content-part#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/structured-message#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.
**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` | 1 | Canonical | A citation to a source identified by its URL. |
| `ANNOTATION_KIND_PDF` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/usage#response).
**promptTokens** `integer(int32)`
Prompt-token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**completionTokens** `integer(int32)`
Completion-token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**totalTokens** `integer(int32)`
Total token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**costEstimate** `any`
Estimated cost in USD.
Exactly one of:
Variant 1:
Type: `number(float)`
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; one category must not be derived by subtracting the
others.
Model reference: [CompletionTokensDetails](/api/models/completion-tokens-details#response).
**reasoningTokens** `integer(int32)`
Tokens used for reasoning/thinking.
Minimum: -2147483648
Maximum: 2147483647
**imageTokens** `integer(int32)`
Completion tokens emitted as image output.
Minimum: -2147483648
Maximum: 2147483647
**audioTokens** `integer(int32)`
Completion tokens emitted as audio output.
Minimum: -2147483648
Maximum: 2147483647
**promptTokensDetails** `any`
Breakdown of prompt tokens (cache).
All of:
Variant 1:
Breakdown of prompt token usage by category (input-side cache accounting)
Model reference: [PromptTokensDetails](/api/models/prompt-tokens-details#response).
**cachedTokens** `integer(int32)`
Prompt tokens served from cache (cache READ).
Minimum: -2147483648
Maximum: 2147483647
**cacheWriteTokens** `integer(int32)`
Prompt tokens written to cache this call (cache WRITE).
Minimum: -2147483648
Maximum: 2147483647
**audioTokens** `integer(int32)`
Prompt tokens from audio input (multimodal).
Minimum: -2147483648
Maximum: 2147483647
**videoTokens** `integer(int32)`
Prompt tokens from video input (multimodal).
Minimum: -2147483648
Maximum: 2147483647
**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/cost-details#response).
**upstreamInferenceCost** `any`
Total upstream provider cost (USD) on BYOK routes.
Exactly one of:
Variant 1:
Type: `number(float)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**upstreamInferencePromptCost** `any`
Upstream cost attributed to prompt tokens (USD).
Exactly one of:
Variant 1:
Type: `number(float)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**upstreamInferenceCompletionCost** `any`
Upstream cost attributed to completion tokens (USD).
Exactly one of:
Variant 1:
Type: `number(float)`
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/generation-context#response).
**memories** `array[MemoryReference]`
Memory records captured in the generation context.
A memory record retrieved and included in generation context.
Model reference: [MemoryReference](/api/models/memory-reference#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(float)`
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[RelationReference]`
Graph relationships captured in the generation context.
A graph relationship retrieved and included in generation context.
Model reference: [RelationReference](/api/models/relation-reference#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/memory-search-params#response).
**query** `string`
Text submitted to memory retrieval for this generation.
**topK** `integer(int32)`
Maximum memory matches requested during generation-context retrieval.
Minimum: -2147483648
Maximum: 2147483647
**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** `integer(int32)`
Number of memory records returned by the search.
Minimum: -2147483648
Maximum: 2147483647
**relationsReturned** `integer(int32)`
Number of graph relationships returned by the search.
Minimum: -2147483648
Maximum: 2147483647
**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/turn-info#response).
**currentTurn** `integer(int32)`
Current turn position within the generation run.
Minimum: -2147483648
Maximum: 2147483647
**maxTurns** `integer(int32)`
Maximum turns configured for the generation run.
Minimum: -2147483648
Maximum: 2147483647
**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 prompt for a generation turn.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `PROMPT_SOURCE_CLIENT_OVERRIDE` | 1 | Canonical | The caller supplied the prompt through the send request's generation-configuration override. |
| `PROMPT_SOURCE_PROFILE_TEMPLATE` | 2 | Canonical | The prompt was rendered from the active agent profile template. |
| `PROMPT_SOURCE_DEFAULT_CONFIG` | 3 | Canonical | The prompt came from the conversation or project default generation configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**baseConfig** `any`
Generation configuration resolved before per-call overrides and timeout adjustments, with
system_prompt omitted. The active profile supplies the base when selected; otherwise the
conversation default does. May be absent on older turns or when neither supplies a
configuration.
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/generation-config#response).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#response).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: -2147483648
Maximum: 2147483647
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#response).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinition]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinition]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#response).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRule]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#response).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#response).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#response).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**languagePreference** `string`
Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware)
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#response).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#response).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#response).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#response).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#response).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#response).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
**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/generation-config#response).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#response).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: -2147483648
Maximum: 2147483647
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#response).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinition]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinition]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#response).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRule]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#response).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#response).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#response).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**languagePreference** `string`
Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware)
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#response).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#response).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#response).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#response).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#response).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#response).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
**profileVersion** `integer(int32)`
Immutable version of the active agent profile used to render this turn’s prompt. Absent on
older turns and turns without a profile template.
Minimum: -2147483648
Maximum: 2147483647
**fragmentsVersion** `integer(int32)`
Version of the prompt-fragment set used to render the profile prompt.
Minimum: -2147483648
Maximum: 2147483647
**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 [User Context] block as rendered into this turn's prompt: the user's
name, locale, and location conditions (weather/AQI/UV/sun times). This is
the literal text the model received, not a reconstruction.
Empty when the user has no stored location, when enrichment degraded, or
on turns predating capture.
**resolvedMcpServers** `array[MCPServerReference]`
The MCP server list that governed this turn — the tier actually resolved
(conversation settings -> active profile -> per-turn override_mcp_servers),
which is simultaneously the tool-discovery source and the CallTool
allow/block basis.
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/mcp-server-reference#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** `integer(int32)`
Priority override for tool selection (higher = preferred).
Minimum: -2147483648
Maximum: 2147483647
**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.
**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/client-context#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[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.
Model reference: [MessageFeedback](/api/models/message-feedback#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` | 1 | Canonical | Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice. |
| `FEEDBACK_KIND_SCALE` | 2 | Canonical | Feedback expressed as an integer rating from 1 through 10. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `FEEDBACK_KIND_THUMB`, `FEEDBACK_KIND_SCALE`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**thumbUp** `boolean`
Positive when true and negative when false; used for THUMB feedback.
**rating** `integer(int32)`
Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent.
Minimum: -2147483648
Maximum: 2147483647
**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.
**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).
- Overview: `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).
## 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 (JWT) via `Authorization: Bearer `
- HTTP Bearer (JWT) via `Authorization: Bearer `
## Request Body
*Required*
Content type: `application/json`
Input for a semantic search of memories in the authenticated user’s tenant scope.
**query** `string` **required**
Non-empty natural-language search query.
Minimum length: 1
**topK** `integer(int32)` **required**
Maximum results requested. Supply explicitly; omission is rejected before search.
Minimum: 1
Maximum: 100
**threshold** `number(float)`
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]`
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/memory/models/memory#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(float)`
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[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/memory/models/relation#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).
- Overview: `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.
## 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 (JWT) 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
Model reference: [Message](/api/models/message#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` | 1 | Canonical | Instructions or context provided as a system message. |
| `ROLE_USER` | 2 | Canonical | Input supplied by the user or customer application. |
| `ROLE_ASSISTANT` | 3 | Canonical | Content produced by the assistant, including its tool-call requests. |
| `ROLE_TOOL` | 4 | 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: `1`, `2`, `3`, `4`
Must not match:
Type: `any`
Enum: `0`
**content** `array[ContentPartInput]`
Content parts composing the chat message.
Content parts composing a message (flattened structure for JSON compatibility)
Model reference: [ContentPart](/api/models/content-part#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` | 1 | Canonical | Plain text carried by the content part. |
| `CONTENT_PART_TYPE_IMAGE_URL` | 2 | Canonical | An image supplied through a remote URL. |
| `CONTENT_PART_TYPE_IMAGE_BASE64` | 3 | Canonical | An image supplied as base64-encoded bytes. |
| `CONTENT_PART_TYPE_FILE_ID` | 4 | Canonical | A provider file identifier or internal storage identifier resolved before generation. |
| `CONTENT_PART_TYPE_FILE_PATH` | 5 | Canonical | A reference to a local file path. |
| `CONTENT_PART_TYPE_FILE_URL` | 6 | Canonical | A file supplied through a public or signed URL. |
| `CONTENT_PART_TYPE_FILE_DATA_URL` | 7 | Canonical | A file embedded in a data URL, including its media type and encoded data. |
| `CONTENT_PART_TYPE_AUDIO_BASE64` | 8 | Canonical | Base64-encoded audio; the part metadata identifies its audio format. |
| `CONTENT_PART_TYPE_REASONING` | 9 | Canonical | A reasoning segment returned by a model provider, when available. |
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: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`
Must not match:
Type: `any`
Enum: `0`
**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/content-part#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/content-part#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/structured-message#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[ToolCallInput]`
Assistant-to-tool invocations.
A single structured tool call emitted by the model
[`clientToolDeadlineAt`](/api/models/tool-call#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/tool-call#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 one tool call, including approval waiting and terminal outcomes.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `TOOL_EXECUTION_STATUS_PENDING` | 1 | Canonical | The tool call is waiting to begin execution. |
| `TOOL_EXECUTION_STATUS_EXECUTING` | 2 | Canonical | The tool call is currently executing. |
| `TOOL_EXECUTION_STATUS_COMPLETED` | 3 | Canonical | The tool call completed successfully. Responses use this canonical spelling for numeric value 3. |
| `TOOL_EXECUTION_STATUS_SUCCESS` | 3 | Alias of `TOOL_EXECUTION_STATUS_COMPLETED` | Legacy alias of TOOL_EXECUTION_STATUS_COMPLETED with the same numeric value; use COMPLETED for new writes. |
| `TOOL_EXECUTION_STATUS_FAILED` | 4 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. |
| `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 5 | Canonical | The tool call is waiting for approval before it can execute. |
| `TOOL_EXECUTION_STATUS_CANCELLED` | 6 | Canonical | The tool call was cancelled before normal completion. |
| `TOOL_EXECUTION_STATUS_TIMED_OUT` | 7 | 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_SUCCESS`, `TOOL_EXECUTION_STATUS_FAILED`, `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION`, `TOOL_EXECUTION_STATUS_CANCELLED`, `TOOL_EXECUTION_STATUS_TIMED_OUT`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**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 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", the underlying error. Set only once `status` is
terminal, and empty on a clean COMPLETED.
**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. Mirrors requires_approval_at.
**name** `string`
Name identifying the sender of the chat message.
**timestamp** `string(date-time)`
Timestamp associated with the conversation message or event.
**messageId** `string`
Unique message identifier.
**annotations** `array[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/annotation#request).
**urlCitation** `any`
Submessage fields (optional); populate the one matching kind
All of:
Variant 1:
=== Annotations ===
Web source and character range cited in generated message content.
Model reference: [UrlCitation](/api/models/url-citation#request).
**url** `string`
URL associated with the resource or outbound request.
**title** `string`
Title of the web page cited by this annotation.
**content** `string`
Excerpt or snippet of the cited web page.
**startIndex** `integer(int32)`
Character index in message content.
Minimum: -2147483648
Maximum: 2147483647
**endIndex** `integer(int32)`
Character index in message content.
Minimum: -2147483648
Maximum: 2147483647
**pdf** `any`
PDF annotation or parser configuration selected by the enclosing message.
All of:
Variant 1:
Provider annotation identifying a parsed PDF and reusable parsing output.
Model reference: [PdfAnnotation](/api/models/pdf-annotation#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[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 (flattened structure for JSON compatibility)
Model reference: [ContentPart](/api/models/content-part#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` | 1 | Canonical | Plain text carried by the content part. |
| `CONTENT_PART_TYPE_IMAGE_URL` | 2 | Canonical | An image supplied through a remote URL. |
| `CONTENT_PART_TYPE_IMAGE_BASE64` | 3 | Canonical | An image supplied as base64-encoded bytes. |
| `CONTENT_PART_TYPE_FILE_ID` | 4 | Canonical | A provider file identifier or internal storage identifier resolved before generation. |
| `CONTENT_PART_TYPE_FILE_PATH` | 5 | Canonical | A reference to a local file path. |
| `CONTENT_PART_TYPE_FILE_URL` | 6 | Canonical | A file supplied through a public or signed URL. |
| `CONTENT_PART_TYPE_FILE_DATA_URL` | 7 | Canonical | A file embedded in a data URL, including its media type and encoded data. |
| `CONTENT_PART_TYPE_AUDIO_BASE64` | 8 | Canonical | Base64-encoded audio; the part metadata identifies its audio format. |
| `CONTENT_PART_TYPE_REASONING` | 9 | Canonical | A reasoning segment returned by a model provider, when available. |
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: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`
Must not match:
Type: `any`
Enum: `0`
**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/content-part#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/content-part#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/structured-message#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.
**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` | 1 | Canonical | A citation to a source identified by its URL. |
| `ANNOTATION_KIND_PDF` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/usage#request).
**promptTokens** `integer(int32)`
Prompt-token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**completionTokens** `integer(int32)`
Completion-token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**totalTokens** `integer(int32)`
Total token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**costEstimate** `any`
Estimated cost in USD.
Exactly one of:
Variant 1:
Type: `number(float)`
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; one category must not be derived by subtracting the
others.
Model reference: [CompletionTokensDetails](/api/models/completion-tokens-details#request).
**reasoningTokens** `integer(int32)`
Tokens used for reasoning/thinking.
Minimum: -2147483648
Maximum: 2147483647
**imageTokens** `integer(int32)`
Completion tokens emitted as image output.
Minimum: -2147483648
Maximum: 2147483647
**audioTokens** `integer(int32)`
Completion tokens emitted as audio output.
Minimum: -2147483648
Maximum: 2147483647
**promptTokensDetails** `any`
Breakdown of prompt tokens (cache).
All of:
Variant 1:
Breakdown of prompt token usage by category (input-side cache accounting)
Model reference: [PromptTokensDetails](/api/models/prompt-tokens-details#request).
**cachedTokens** `integer(int32)`
Prompt tokens served from cache (cache READ).
Minimum: -2147483648
Maximum: 2147483647
**cacheWriteTokens** `integer(int32)`
Prompt tokens written to cache this call (cache WRITE).
Minimum: -2147483648
Maximum: 2147483647
**audioTokens** `integer(int32)`
Prompt tokens from audio input (multimodal).
Minimum: -2147483648
Maximum: 2147483647
**videoTokens** `integer(int32)`
Prompt tokens from video input (multimodal).
Minimum: -2147483648
Maximum: 2147483647
**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/cost-details#request).
**upstreamInferenceCost** `any`
Total upstream provider cost (USD) on BYOK routes.
Exactly one of:
Variant 1:
Type: `number(float)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**upstreamInferencePromptCost** `any`
Upstream cost attributed to prompt tokens (USD).
Exactly one of:
Variant 1:
Type: `number(float)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**upstreamInferenceCompletionCost** `any`
Upstream cost attributed to completion tokens (USD).
Exactly one of:
Variant 1:
Type: `number(float)`
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/generation-context#request).
**memories** `array[MemoryReferenceInput]`
Memory records captured in the generation context.
A memory record retrieved and included in generation context.
Model reference: [MemoryReference](/api/models/memory-reference#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(float)`
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[RelationReferenceInput]`
Graph relationships captured in the generation context.
A graph relationship retrieved and included in generation context.
Model reference: [RelationReference](/api/models/relation-reference#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/memory-search-params#request).
**query** `string`
Text submitted to memory retrieval for this generation.
**topK** `integer(int32)`
Maximum memory matches requested during generation-context retrieval.
Minimum: -2147483648
Maximum: 2147483647
**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** `integer(int32)`
Number of memory records returned by the search.
Minimum: -2147483648
Maximum: 2147483647
**relationsReturned** `integer(int32)`
Number of graph relationships returned by the search.
Minimum: -2147483648
Maximum: 2147483647
**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/turn-info#request).
**currentTurn** `integer(int32)`
Current turn position within the generation run.
Minimum: -2147483648
Maximum: 2147483647
**maxTurns** `integer(int32)`
Maximum turns configured for the generation run.
Minimum: -2147483648
Maximum: 2147483647
**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 prompt for a generation turn.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `PROMPT_SOURCE_CLIENT_OVERRIDE` | 1 | Canonical | The caller supplied the prompt through the send request's generation-configuration override. |
| `PROMPT_SOURCE_PROFILE_TEMPLATE` | 2 | Canonical | The prompt was rendered from the active agent profile template. |
| `PROMPT_SOURCE_DEFAULT_CONFIG` | 3 | Canonical | The prompt came from the conversation or project default generation configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**baseConfig** `any`
Generation configuration resolved before per-call overrides and timeout adjustments, with
system_prompt omitted. The active profile supplies the base when selected; otherwise the
conversation default does. May be absent on older turns or when neither supplies a
configuration.
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/generation-config#request).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#request).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: 0
Maximum: 3
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#request).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinitionInput]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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**
Which server provides this tool (for MCP tools).
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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinitionInput]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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**
Which server provides this tool (for MCP tools).
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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#request).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRuleInput]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#request).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#request).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#request).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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})*$
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#request).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#request).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#request).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#request).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#request).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#request).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
**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/generation-config#request).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#request).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: 0
Maximum: 3
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#request).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinitionInput]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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**
Which server provides this tool (for MCP tools).
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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinitionInput]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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**
Which server provides this tool (for MCP tools).
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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#request).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRuleInput]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#request).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#request).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#request).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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})*$
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#request).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#request).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#request).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#request).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#request).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#request).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
**profileVersion** `integer(int32)`
Immutable version of the active agent profile used to render this turn’s prompt. Absent on
older turns and turns without a profile template.
Minimum: -2147483648
Maximum: 2147483647
**fragmentsVersion** `integer(int32)`
Version of the prompt-fragment set used to render the profile prompt.
Minimum: -2147483648
Maximum: 2147483647
**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 [User Context] block as rendered into this turn's prompt: the user's
name, locale, and location conditions (weather/AQI/UV/sun times). This is
the literal text the model received, not a reconstruction.
Empty when the user has no stored location, when enrichment degraded, or
on turns predating capture.
**resolvedMcpServers** `array[MCPServerReferenceInput]`
The MCP server list that governed this turn — the tier actually resolved
(conversation settings -> active profile -> per-turn override_mcp_servers),
which is simultaneously the tool-discovery source and the CallTool
allow/block basis.
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/mcp-server-reference#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** `integer(int32)`
Priority override for tool selection (higher = preferred).
Minimum: -2147483648
Maximum: 2147483647
**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.
**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/client-context#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[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.
Model reference: [MessageFeedback](/api/models/message-feedback#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` | 1 | Canonical | Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice. |
| `FEEDBACK_KIND_SCALE` | 2 | Canonical | Feedback expressed as an integer rating from 1 through 10. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `FEEDBACK_KIND_THUMB`, `FEEDBACK_KIND_SCALE`
Variant 2:
Type: `integer(int32)`
Enum: `1`, `2`
Must not match:
Type: `any`
Enum: `0`
**thumbUp** `boolean`
Positive when true and negative when false; used for THUMB feedback.
**rating** `integer(int32)`
Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent.
Minimum: 0
Maximum: 10
**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.
**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/map values inherit, so clear_tools is used
to clear inherited 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/generation-config#request).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#request).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: 0
Maximum: 3
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#request).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinitionInput]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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**
Which server provides this tool (for MCP tools).
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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinitionInput]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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**
Which server provides this tool (for MCP tools).
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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#request).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRuleInput]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#request).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#request).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#request).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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})*$
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#request).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#request).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#request).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#request).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#request).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#request).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
**setActiveProfileId** `string`
Set the active agent profile for this and subsequent conversation turns.
**setActiveProfileVersion** `integer(int32)`
Version of the active agent profile forwarded with this turn.
Minimum: -2147483648
Maximum: 2147483647
**overrideMcpServers** `array[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/mcp-server-reference#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** `integer(int32)`
Priority override for tool selection (higher = preferred).
Minimum: -2147483648
Maximum: 2147483647
**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.
**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.
Model reference: [ExperimentContext](/api/models/experiment-context#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-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[Message]`
Conversation messages returned by the generation segment.
Chat message
Model reference: [Message](/api/models/message#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` | 1 | Canonical | Instructions or context provided as a system message. |
| `ROLE_USER` | 2 | Canonical | Input supplied by the user or customer application. |
| `ROLE_ASSISTANT` | 3 | Canonical | Content produced by the assistant, including its tool-call requests. |
| `ROLE_TOOL` | 4 | 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)`
Must not match:
Type: `any`
Enum: `0`
**content** `array[ContentPart]`
Content parts composing the chat message.
Content parts composing a message (flattened structure for JSON compatibility)
Model reference: [ContentPart](/api/models/content-part#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` | 1 | Canonical | Plain text carried by the content part. |
| `CONTENT_PART_TYPE_IMAGE_URL` | 2 | Canonical | An image supplied through a remote URL. |
| `CONTENT_PART_TYPE_IMAGE_BASE64` | 3 | Canonical | An image supplied as base64-encoded bytes. |
| `CONTENT_PART_TYPE_FILE_ID` | 4 | Canonical | A provider file identifier or internal storage identifier resolved before generation. |
| `CONTENT_PART_TYPE_FILE_PATH` | 5 | Canonical | A reference to a local file path. |
| `CONTENT_PART_TYPE_FILE_URL` | 6 | Canonical | A file supplied through a public or signed URL. |
| `CONTENT_PART_TYPE_FILE_DATA_URL` | 7 | Canonical | A file embedded in a data URL, including its media type and encoded data. |
| `CONTENT_PART_TYPE_AUDIO_BASE64` | 8 | Canonical | Base64-encoded audio; the part metadata identifies its audio format. |
| `CONTENT_PART_TYPE_REASONING` | 9 | Canonical | A reasoning segment returned by a model provider, when available. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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/content-part#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/content-part#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/structured-message#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[ToolCall]`
Assistant-to-tool invocations.
A single structured tool call emitted by the model
[`clientToolDeadlineAt`](/api/models/tool-call#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/tool-call#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 one tool call, including approval waiting and terminal outcomes.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `TOOL_EXECUTION_STATUS_PENDING` | 1 | Canonical | The tool call is waiting to begin execution. |
| `TOOL_EXECUTION_STATUS_EXECUTING` | 2 | Canonical | The tool call is currently executing. |
| `TOOL_EXECUTION_STATUS_COMPLETED` | 3 | Canonical | The tool call completed successfully. Responses use this canonical spelling for numeric value 3. |
| `TOOL_EXECUTION_STATUS_SUCCESS` | 3 | Alias of `TOOL_EXECUTION_STATUS_COMPLETED`; Name not accepted for this field; number accepted | Legacy alias of TOOL_EXECUTION_STATUS_COMPLETED with the same numeric value; use COMPLETED for new writes. |
| `TOOL_EXECUTION_STATUS_FAILED` | 4 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. |
| `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 5 | Canonical | The tool call is waiting for approval before it can execute. |
| `TOOL_EXECUTION_STATUS_CANCELLED` | 6 | Canonical | The tool call was cancelled before normal completion. |
| `TOOL_EXECUTION_STATUS_TIMED_OUT` | 7 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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 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", the underlying error. Set only once `status` is
terminal, and empty on a clean COMPLETED.
**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. Mirrors requires_approval_at.
**name** `string`
Name identifying the sender of the chat message.
**timestamp** `string(date-time)`
Timestamp associated with the conversation message or event.
**messageId** `string`
Unique message identifier.
**annotations** `array[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/annotation#response).
**urlCitation** `any`
Submessage fields (optional); populate the one matching kind
All of:
Variant 1:
=== Annotations ===
Web source and character range cited in generated message content.
Model reference: [UrlCitation](/api/models/url-citation#response).
**url** `string`
URL associated with the resource or outbound request.
**title** `string`
Title of the web page cited by this annotation.
**content** `string`
Excerpt or snippet of the cited web page.
**startIndex** `integer(int32)`
Character index in message content.
Minimum: -2147483648
Maximum: 2147483647
**endIndex** `integer(int32)`
Character index in message content.
Minimum: -2147483648
Maximum: 2147483647
**pdf** `any`
PDF annotation or parser configuration selected by the enclosing message.
All of:
Variant 1:
Provider annotation identifying a parsed PDF and reusable parsing output.
Model reference: [PdfAnnotation](/api/models/pdf-annotation#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[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 (flattened structure for JSON compatibility)
Model reference: [ContentPart](/api/models/content-part#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` | 1 | Canonical | Plain text carried by the content part. |
| `CONTENT_PART_TYPE_IMAGE_URL` | 2 | Canonical | An image supplied through a remote URL. |
| `CONTENT_PART_TYPE_IMAGE_BASE64` | 3 | Canonical | An image supplied as base64-encoded bytes. |
| `CONTENT_PART_TYPE_FILE_ID` | 4 | Canonical | A provider file identifier or internal storage identifier resolved before generation. |
| `CONTENT_PART_TYPE_FILE_PATH` | 5 | Canonical | A reference to a local file path. |
| `CONTENT_PART_TYPE_FILE_URL` | 6 | Canonical | A file supplied through a public or signed URL. |
| `CONTENT_PART_TYPE_FILE_DATA_URL` | 7 | Canonical | A file embedded in a data URL, including its media type and encoded data. |
| `CONTENT_PART_TYPE_AUDIO_BASE64` | 8 | Canonical | Base64-encoded audio; the part metadata identifies its audio format. |
| `CONTENT_PART_TYPE_REASONING` | 9 | Canonical | A reasoning segment returned by a model provider, when available. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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/content-part#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/content-part#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/structured-message#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.
**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` | 1 | Canonical | A citation to a source identified by its URL. |
| `ANNOTATION_KIND_PDF` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/usage#response).
**promptTokens** `integer(int32)`
Prompt-token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**completionTokens** `integer(int32)`
Completion-token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**totalTokens** `integer(int32)`
Total token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**costEstimate** `any`
Estimated cost in USD.
Exactly one of:
Variant 1:
Type: `number(float)`
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; one category must not be derived by subtracting the
others.
Model reference: [CompletionTokensDetails](/api/models/completion-tokens-details#response).
**reasoningTokens** `integer(int32)`
Tokens used for reasoning/thinking.
Minimum: -2147483648
Maximum: 2147483647
**imageTokens** `integer(int32)`
Completion tokens emitted as image output.
Minimum: -2147483648
Maximum: 2147483647
**audioTokens** `integer(int32)`
Completion tokens emitted as audio output.
Minimum: -2147483648
Maximum: 2147483647
**promptTokensDetails** `any`
Breakdown of prompt tokens (cache).
All of:
Variant 1:
Breakdown of prompt token usage by category (input-side cache accounting)
Model reference: [PromptTokensDetails](/api/models/prompt-tokens-details#response).
**cachedTokens** `integer(int32)`
Prompt tokens served from cache (cache READ).
Minimum: -2147483648
Maximum: 2147483647
**cacheWriteTokens** `integer(int32)`
Prompt tokens written to cache this call (cache WRITE).
Minimum: -2147483648
Maximum: 2147483647
**audioTokens** `integer(int32)`
Prompt tokens from audio input (multimodal).
Minimum: -2147483648
Maximum: 2147483647
**videoTokens** `integer(int32)`
Prompt tokens from video input (multimodal).
Minimum: -2147483648
Maximum: 2147483647
**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/cost-details#response).
**upstreamInferenceCost** `any`
Total upstream provider cost (USD) on BYOK routes.
Exactly one of:
Variant 1:
Type: `number(float)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**upstreamInferencePromptCost** `any`
Upstream cost attributed to prompt tokens (USD).
Exactly one of:
Variant 1:
Type: `number(float)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**upstreamInferenceCompletionCost** `any`
Upstream cost attributed to completion tokens (USD).
Exactly one of:
Variant 1:
Type: `number(float)`
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/generation-context#response).
**memories** `array[MemoryReference]`
Memory records captured in the generation context.
A memory record retrieved and included in generation context.
Model reference: [MemoryReference](/api/models/memory-reference#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(float)`
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[RelationReference]`
Graph relationships captured in the generation context.
A graph relationship retrieved and included in generation context.
Model reference: [RelationReference](/api/models/relation-reference#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/memory-search-params#response).
**query** `string`
Text submitted to memory retrieval for this generation.
**topK** `integer(int32)`
Maximum memory matches requested during generation-context retrieval.
Minimum: -2147483648
Maximum: 2147483647
**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** `integer(int32)`
Number of memory records returned by the search.
Minimum: -2147483648
Maximum: 2147483647
**relationsReturned** `integer(int32)`
Number of graph relationships returned by the search.
Minimum: -2147483648
Maximum: 2147483647
**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/turn-info#response).
**currentTurn** `integer(int32)`
Current turn position within the generation run.
Minimum: -2147483648
Maximum: 2147483647
**maxTurns** `integer(int32)`
Maximum turns configured for the generation run.
Minimum: -2147483648
Maximum: 2147483647
**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 prompt for a generation turn.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `PROMPT_SOURCE_CLIENT_OVERRIDE` | 1 | Canonical | The caller supplied the prompt through the send request's generation-configuration override. |
| `PROMPT_SOURCE_PROFILE_TEMPLATE` | 2 | Canonical | The prompt was rendered from the active agent profile template. |
| `PROMPT_SOURCE_DEFAULT_CONFIG` | 3 | Canonical | The prompt came from the conversation or project default generation configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**baseConfig** `any`
Generation configuration resolved before per-call overrides and timeout adjustments, with
system_prompt omitted. The active profile supplies the base when selected; otherwise the
conversation default does. May be absent on older turns or when neither supplies a
configuration.
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/generation-config#response).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#response).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: -2147483648
Maximum: 2147483647
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#response).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinition]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinition]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#response).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRule]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#response).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#response).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#response).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**languagePreference** `string`
Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware)
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#response).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#response).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#response).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#response).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#response).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#response).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
**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/generation-config#response).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#response).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: -2147483648
Maximum: 2147483647
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#response).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinition]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinition]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#response).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRule]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#response).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#response).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#response).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**languagePreference** `string`
Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware)
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#response).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#response).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#response).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#response).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#response).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#response).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
**profileVersion** `integer(int32)`
Immutable version of the active agent profile used to render this turn’s prompt. Absent on
older turns and turns without a profile template.
Minimum: -2147483648
Maximum: 2147483647
**fragmentsVersion** `integer(int32)`
Version of the prompt-fragment set used to render the profile prompt.
Minimum: -2147483648
Maximum: 2147483647
**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 [User Context] block as rendered into this turn's prompt: the user's
name, locale, and location conditions (weather/AQI/UV/sun times). This is
the literal text the model received, not a reconstruction.
Empty when the user has no stored location, when enrichment degraded, or
on turns predating capture.
**resolvedMcpServers** `array[MCPServerReference]`
The MCP server list that governed this turn — the tier actually resolved
(conversation settings -> active profile -> per-turn override_mcp_servers),
which is simultaneously the tool-discovery source and the CallTool
allow/block basis.
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/mcp-server-reference#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** `integer(int32)`
Priority override for tool selection (higher = preferred).
Minimum: -2147483648
Maximum: 2147483647
**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.
**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/client-context#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[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.
Model reference: [MessageFeedback](/api/models/message-feedback#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` | 1 | Canonical | Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice. |
| `FEEDBACK_KIND_SCALE` | 2 | Canonical | Feedback expressed as an integer rating from 1 through 10. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `FEEDBACK_KIND_THUMB`, `FEEDBACK_KIND_SCALE`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**thumbUp** `boolean`
Positive when true and negative when false; used for THUMB feedback.
**rating** `integer(int32)`
Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent.
Minimum: -2147483648
Maximum: 2147483647
**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.
**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.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `AGENT_STATUS_ACTIVE` | 1 | Canonical | The run is active and has not yet reached a more specific execution phase or terminal outcome. |
| `AGENT_STATUS_GENERATING` | 2 | Canonical | The run is generating a model response. |
| `AGENT_STATUS_EXECUTING_TOOLS` | 3 | Canonical | The run is executing server-side tools. |
| `AGENT_STATUS_COMPLETED` | 4 | Canonical | The run finished successfully. |
| `AGENT_STATUS_FAILED` | 5 | Canonical | The run ended with a failure; inspect its error or end reason. |
| `AGENT_STATUS_QUEUED` | 6 | Canonical | The incoming message is queued behind an ongoing run under the queue interruption policy. |
| `AGENT_STATUS_AWAITING_CLIENT_TOOLS` | 7 | Canonical | The run is waiting for the caller to execute client-side tools and submit their results. |
| `AGENT_STATUS_CANCELLED` | 8 | Canonical | The run ended because a client or its invocation cancelled it. |
| `AGENT_STATUS_TIMED_OUT` | 9 | Canonical | The run ended because a run-level time limit 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)`
Must not match:
Type: `any`
Enum: `0`
**aggregateUsage** `any`
Aggregated model usage reported for the generation run.
All of:
Variant 1:
Usage accounting
Model reference: [Usage](/api/models/usage#response).
**promptTokens** `integer(int32)`
Prompt-token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**completionTokens** `integer(int32)`
Completion-token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**totalTokens** `integer(int32)`
Total token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**costEstimate** `any`
Estimated cost in USD.
Exactly one of:
Variant 1:
Type: `number(float)`
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; one category must not be derived by subtracting the
others.
Model reference: [CompletionTokensDetails](/api/models/completion-tokens-details#response).
**reasoningTokens** `integer(int32)`
Tokens used for reasoning/thinking.
Minimum: -2147483648
Maximum: 2147483647
**imageTokens** `integer(int32)`
Completion tokens emitted as image output.
Minimum: -2147483648
Maximum: 2147483647
**audioTokens** `integer(int32)`
Completion tokens emitted as audio output.
Minimum: -2147483648
Maximum: 2147483647
**promptTokensDetails** `any`
Breakdown of prompt tokens (cache).
All of:
Variant 1:
Breakdown of prompt token usage by category (input-side cache accounting)
Model reference: [PromptTokensDetails](/api/models/prompt-tokens-details#response).
**cachedTokens** `integer(int32)`
Prompt tokens served from cache (cache READ).
Minimum: -2147483648
Maximum: 2147483647
**cacheWriteTokens** `integer(int32)`
Prompt tokens written to cache this call (cache WRITE).
Minimum: -2147483648
Maximum: 2147483647
**audioTokens** `integer(int32)`
Prompt tokens from audio input (multimodal).
Minimum: -2147483648
Maximum: 2147483647
**videoTokens** `integer(int32)`
Prompt tokens from video input (multimodal).
Minimum: -2147483648
Maximum: 2147483647
**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/cost-details#response).
**upstreamInferenceCost** `any`
Total upstream provider cost (USD) on BYOK routes.
Exactly one of:
Variant 1:
Type: `number(float)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**upstreamInferencePromptCost** `any`
Upstream cost attributed to prompt tokens (USD).
Exactly one of:
Variant 1:
Type: `number(float)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**upstreamInferenceCompletionCost** `any`
Upstream cost attributed to completion tokens (USD).
Exactly one of:
Variant 1:
Type: `number(float)`
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:
Standardized error payload following google.rpc.Status (AIP-193).
Used across all response messages and event payloads.
Model reference: [RpcError](/api/models/rpc-error#response).
**code** `any`
Machine-readable error code. Clients switch on this field.
Machine-readable reason that a request or operation failed; inspect the accompanying error details for context.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `ERROR_CODE_CANCELLED` | 1 | Canonical | The caller cancelled the operation before it completed. |
| `ERROR_CODE_UNKNOWN` | 2 | Canonical | The operation failed without a more specific error classification. |
| `ERROR_CODE_INVALID_ARGUMENT` | 3 | Canonical | The request contains an invalid argument or field value. |
| `ERROR_CODE_DEADLINE_EXCEEDED` | 4 | Canonical | The operation did not complete before its deadline. |
| `ERROR_CODE_NOT_FOUND` | 5 | Canonical | The requested resource does not exist or could not be found. |
| `ERROR_CODE_ALREADY_EXISTS` | 6 | Canonical | The requested creation conflicts with a resource that already exists. |
| `ERROR_CODE_PERMISSION_DENIED` | 7 | Canonical | The authenticated caller is not permitted to perform the operation. |
| `ERROR_CODE_RESOURCE_EXHAUSTED` | 8 | Canonical | A quota, rate limit or other capacity limit prevented the operation. |
| `ERROR_CODE_FAILED_PRECONDITION` | 9 | Canonical | The operation requires a system or resource state that is not currently satisfied. |
| `ERROR_CODE_ABORTED` | 10 | Canonical | The operation was aborted, for example by a concurrent modification conflict. |
| `ERROR_CODE_OUT_OF_RANGE` | 11 | Canonical | An argument is outside the range supported by this operation. |
| `ERROR_CODE_UNIMPLEMENTED` | 12 | Canonical | The requested operation is not implemented. |
| `ERROR_CODE_INTERNAL` | 13 | Canonical | An internal failure prevented the operation from completing. |
| `ERROR_CODE_UNAVAILABLE` | 14 | Canonical | The service or a required dependency is temporarily unavailable. |
| `ERROR_CODE_DATA_LOSS` | 15 | Canonical | The operation encountered unrecoverable loss or corruption of data. |
| `ERROR_CODE_UNAUTHENTICATED` | 16 | Canonical | Authentication credentials are missing or invalid. |
| `ERROR_CODE_MODEL_INVALID` | 600 | Canonical | The requested model identifier is absent from the model catalog. |
| `ERROR_CODE_MODEL_UNAVAILABLE` | 601 | Canonical | The model exists, but no provider is currently available to serve it. |
| `ERROR_CODE_MODERATION_FLAGGED` | 602 | Canonical | Content moderation flagged the submitted content. |
| `ERROR_CODE_GENERATION_FAILED` | 603 | Canonical | Model generation failed after its configured attempts. |
| `ERROR_CODE_TOOL_EXECUTION_FAILED` | 604 | Canonical | Execution of a requested tool failed. |
| `ERROR_CODE_UPSTREAM_PROVIDER` | 605 | Canonical | An upstream model provider returned an error. |
| `ERROR_CODE_VALIDATION_EXHAUSTED` | 606 | Canonical | Structured-output validation still failed after the configured attempts. |
| `ERROR_CODE_PAYMENT_REQUIRED` | 607 | Canonical | The account lacks the credits required for the operation. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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 terminal (non-retryable). When true, repeating the
same request will produce the same error. When false, transient condition
may resolve on retry.
**details** `any`
Structured error details. At most one of each detail type.
Follows google.rpc.Status details pattern but uses concrete types
instead of google.protobuf.Any for type safety and codegen.
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/error-details#response).
**errorInfo** `any`
Identifies the error for machine consumption.
REQUIRED on all errors per AIP-193 (enforced at Go helper level).
All of:
Variant 1:
Machine-readable error identification (per AIP-193, every error must include this).
Model reference: [ErrorInfo](/api/models/error-info#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/retry-info#response).
**retryDelayMs** `string(int64)`
Suggested minimum delay before retrying, in milliseconds.
Pattern: ^-?\d+$
**fieldViolations** `array[FieldViolation]`
Field-level validation failures.
A single field-level validation violation.
Model reference: [FieldViolation](/api/models/field-violation#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.
Model reference: [UpstreamError](/api/models/upstream-error#response).
**provider** `string`
Name of the upstream provider that reported the error.
**statusCode** `integer(int32)`
HTTP status code returned by the provider.
Minimum: -2147483648
Maximum: 2147483647
**rawBody** `string`
Raw error body from the provider. Truncated to 512 bytes (enforced at Go level).
**modelError** `any`
Model-specific error context.
All of:
Variant 1:
Model-specific error context.
Model reference: [ModelError](/api/models/model-error#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[HelpLink]`
Help links for error resolution.
A help link for error resolution.
Model reference: [HelpLink](/api/models/help-link#response).
**url** `string`
URL to documentation or resolution guide.
**description** `string`
Description of what the link provides.
**pendingClientTools** `array[ToolCall]`
Tool calls dispatched for execution by the client.
A single structured tool call emitted by the model
[`clientToolDeadlineAt`](/api/models/tool-call#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/tool-call#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 one tool call, including approval waiting and terminal outcomes.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `TOOL_EXECUTION_STATUS_PENDING` | 1 | Canonical | The tool call is waiting to begin execution. |
| `TOOL_EXECUTION_STATUS_EXECUTING` | 2 | Canonical | The tool call is currently executing. |
| `TOOL_EXECUTION_STATUS_COMPLETED` | 3 | Canonical | The tool call completed successfully. Responses use this canonical spelling for numeric value 3. |
| `TOOL_EXECUTION_STATUS_SUCCESS` | 3 | Alias of `TOOL_EXECUTION_STATUS_COMPLETED`; Name not accepted for this field; number accepted | Legacy alias of TOOL_EXECUTION_STATUS_COMPLETED with the same numeric value; use COMPLETED for new writes. |
| `TOOL_EXECUTION_STATUS_FAILED` | 4 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. |
| `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 5 | Canonical | The tool call is waiting for approval before it can execute. |
| `TOOL_EXECUTION_STATUS_CANCELLED` | 6 | Canonical | The tool call was cancelled before normal completion. |
| `TOOL_EXECUTION_STATUS_TIMED_OUT` | 7 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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 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", the underlying error. Set only once `status` is
terminal, and empty on a clean COMPLETED.
**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. Mirrors requires_approval_at.
**clientToolCursor** `integer(int32)`
Latest client-tool dispatch sequence represented by this response.
Minimum: -2147483648
Maximum: 2147483647
#### 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).
- Overview: `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.
## 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 (JWT) via `Authorization: Bearer `
## Request Body
*Required*
Content type: `application/json`
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
Model reference: [Message](/api/models/message#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` | 1 | Canonical | Instructions or context provided as a system message. |
| `ROLE_USER` | 2 | Canonical | Input supplied by the user or customer application. |
| `ROLE_ASSISTANT` | 3 | Canonical | Content produced by the assistant, including its tool-call requests. |
| `ROLE_TOOL` | 4 | 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: `1`, `2`, `3`, `4`
Must not match:
Type: `any`
Enum: `0`
**content** `array[ContentPartInput]`
Content parts composing the chat message.
Content parts composing a message (flattened structure for JSON compatibility)
Model reference: [ContentPart](/api/models/content-part#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` | 1 | Canonical | Plain text carried by the content part. |
| `CONTENT_PART_TYPE_IMAGE_URL` | 2 | Canonical | An image supplied through a remote URL. |
| `CONTENT_PART_TYPE_IMAGE_BASE64` | 3 | Canonical | An image supplied as base64-encoded bytes. |
| `CONTENT_PART_TYPE_FILE_ID` | 4 | Canonical | A provider file identifier or internal storage identifier resolved before generation. |
| `CONTENT_PART_TYPE_FILE_PATH` | 5 | Canonical | A reference to a local file path. |
| `CONTENT_PART_TYPE_FILE_URL` | 6 | Canonical | A file supplied through a public or signed URL. |
| `CONTENT_PART_TYPE_FILE_DATA_URL` | 7 | Canonical | A file embedded in a data URL, including its media type and encoded data. |
| `CONTENT_PART_TYPE_AUDIO_BASE64` | 8 | Canonical | Base64-encoded audio; the part metadata identifies its audio format. |
| `CONTENT_PART_TYPE_REASONING` | 9 | Canonical | A reasoning segment returned by a model provider, when available. |
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: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`
Must not match:
Type: `any`
Enum: `0`
**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/content-part#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/content-part#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/structured-message#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[ToolCallInput]`
Assistant-to-tool invocations.
A single structured tool call emitted by the model
[`clientToolDeadlineAt`](/api/models/tool-call#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/tool-call#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 one tool call, including approval waiting and terminal outcomes.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `TOOL_EXECUTION_STATUS_PENDING` | 1 | Canonical | The tool call is waiting to begin execution. |
| `TOOL_EXECUTION_STATUS_EXECUTING` | 2 | Canonical | The tool call is currently executing. |
| `TOOL_EXECUTION_STATUS_COMPLETED` | 3 | Canonical | The tool call completed successfully. Responses use this canonical spelling for numeric value 3. |
| `TOOL_EXECUTION_STATUS_SUCCESS` | 3 | Alias of `TOOL_EXECUTION_STATUS_COMPLETED` | Legacy alias of TOOL_EXECUTION_STATUS_COMPLETED with the same numeric value; use COMPLETED for new writes. |
| `TOOL_EXECUTION_STATUS_FAILED` | 4 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. |
| `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 5 | Canonical | The tool call is waiting for approval before it can execute. |
| `TOOL_EXECUTION_STATUS_CANCELLED` | 6 | Canonical | The tool call was cancelled before normal completion. |
| `TOOL_EXECUTION_STATUS_TIMED_OUT` | 7 | 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_SUCCESS`, `TOOL_EXECUTION_STATUS_FAILED`, `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION`, `TOOL_EXECUTION_STATUS_CANCELLED`, `TOOL_EXECUTION_STATUS_TIMED_OUT`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**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 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", the underlying error. Set only once `status` is
terminal, and empty on a clean COMPLETED.
**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. Mirrors requires_approval_at.
**name** `string`
Name identifying the sender of the chat message.
**timestamp** `string(date-time)`
Timestamp associated with the conversation message or event.
**messageId** `string`
Unique message identifier.
**annotations** `array[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/annotation#request).
**urlCitation** `any`
Submessage fields (optional); populate the one matching kind
All of:
Variant 1:
=== Annotations ===
Web source and character range cited in generated message content.
Model reference: [UrlCitation](/api/models/url-citation#request).
**url** `string`
URL associated with the resource or outbound request.
**title** `string`
Title of the web page cited by this annotation.
**content** `string`
Excerpt or snippet of the cited web page.
**startIndex** `integer(int32)`
Character index in message content.
Minimum: -2147483648
Maximum: 2147483647
**endIndex** `integer(int32)`
Character index in message content.
Minimum: -2147483648
Maximum: 2147483647
**pdf** `any`
PDF annotation or parser configuration selected by the enclosing message.
All of:
Variant 1:
Provider annotation identifying a parsed PDF and reusable parsing output.
Model reference: [PdfAnnotation](/api/models/pdf-annotation#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[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 (flattened structure for JSON compatibility)
Model reference: [ContentPart](/api/models/content-part#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` | 1 | Canonical | Plain text carried by the content part. |
| `CONTENT_PART_TYPE_IMAGE_URL` | 2 | Canonical | An image supplied through a remote URL. |
| `CONTENT_PART_TYPE_IMAGE_BASE64` | 3 | Canonical | An image supplied as base64-encoded bytes. |
| `CONTENT_PART_TYPE_FILE_ID` | 4 | Canonical | A provider file identifier or internal storage identifier resolved before generation. |
| `CONTENT_PART_TYPE_FILE_PATH` | 5 | Canonical | A reference to a local file path. |
| `CONTENT_PART_TYPE_FILE_URL` | 6 | Canonical | A file supplied through a public or signed URL. |
| `CONTENT_PART_TYPE_FILE_DATA_URL` | 7 | Canonical | A file embedded in a data URL, including its media type and encoded data. |
| `CONTENT_PART_TYPE_AUDIO_BASE64` | 8 | Canonical | Base64-encoded audio; the part metadata identifies its audio format. |
| `CONTENT_PART_TYPE_REASONING` | 9 | Canonical | A reasoning segment returned by a model provider, when available. |
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: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`
Must not match:
Type: `any`
Enum: `0`
**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/content-part#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/content-part#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/structured-message#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.
**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` | 1 | Canonical | A citation to a source identified by its URL. |
| `ANNOTATION_KIND_PDF` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/usage#request).
**promptTokens** `integer(int32)`
Prompt-token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**completionTokens** `integer(int32)`
Completion-token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**totalTokens** `integer(int32)`
Total token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**costEstimate** `any`
Estimated cost in USD.
Exactly one of:
Variant 1:
Type: `number(float)`
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; one category must not be derived by subtracting the
others.
Model reference: [CompletionTokensDetails](/api/models/completion-tokens-details#request).
**reasoningTokens** `integer(int32)`
Tokens used for reasoning/thinking.
Minimum: -2147483648
Maximum: 2147483647
**imageTokens** `integer(int32)`
Completion tokens emitted as image output.
Minimum: -2147483648
Maximum: 2147483647
**audioTokens** `integer(int32)`
Completion tokens emitted as audio output.
Minimum: -2147483648
Maximum: 2147483647
**promptTokensDetails** `any`
Breakdown of prompt tokens (cache).
All of:
Variant 1:
Breakdown of prompt token usage by category (input-side cache accounting)
Model reference: [PromptTokensDetails](/api/models/prompt-tokens-details#request).
**cachedTokens** `integer(int32)`
Prompt tokens served from cache (cache READ).
Minimum: -2147483648
Maximum: 2147483647
**cacheWriteTokens** `integer(int32)`
Prompt tokens written to cache this call (cache WRITE).
Minimum: -2147483648
Maximum: 2147483647
**audioTokens** `integer(int32)`
Prompt tokens from audio input (multimodal).
Minimum: -2147483648
Maximum: 2147483647
**videoTokens** `integer(int32)`
Prompt tokens from video input (multimodal).
Minimum: -2147483648
Maximum: 2147483647
**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/cost-details#request).
**upstreamInferenceCost** `any`
Total upstream provider cost (USD) on BYOK routes.
Exactly one of:
Variant 1:
Type: `number(float)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**upstreamInferencePromptCost** `any`
Upstream cost attributed to prompt tokens (USD).
Exactly one of:
Variant 1:
Type: `number(float)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**upstreamInferenceCompletionCost** `any`
Upstream cost attributed to completion tokens (USD).
Exactly one of:
Variant 1:
Type: `number(float)`
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/generation-context#request).
**memories** `array[MemoryReferenceInput]`
Memory records captured in the generation context.
A memory record retrieved and included in generation context.
Model reference: [MemoryReference](/api/models/memory-reference#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(float)`
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[RelationReferenceInput]`
Graph relationships captured in the generation context.
A graph relationship retrieved and included in generation context.
Model reference: [RelationReference](/api/models/relation-reference#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/memory-search-params#request).
**query** `string`
Text submitted to memory retrieval for this generation.
**topK** `integer(int32)`
Maximum memory matches requested during generation-context retrieval.
Minimum: -2147483648
Maximum: 2147483647
**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** `integer(int32)`
Number of memory records returned by the search.
Minimum: -2147483648
Maximum: 2147483647
**relationsReturned** `integer(int32)`
Number of graph relationships returned by the search.
Minimum: -2147483648
Maximum: 2147483647
**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/turn-info#request).
**currentTurn** `integer(int32)`
Current turn position within the generation run.
Minimum: -2147483648
Maximum: 2147483647
**maxTurns** `integer(int32)`
Maximum turns configured for the generation run.
Minimum: -2147483648
Maximum: 2147483647
**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 prompt for a generation turn.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `PROMPT_SOURCE_CLIENT_OVERRIDE` | 1 | Canonical | The caller supplied the prompt through the send request's generation-configuration override. |
| `PROMPT_SOURCE_PROFILE_TEMPLATE` | 2 | Canonical | The prompt was rendered from the active agent profile template. |
| `PROMPT_SOURCE_DEFAULT_CONFIG` | 3 | Canonical | The prompt came from the conversation or project default generation configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**baseConfig** `any`
Generation configuration resolved before per-call overrides and timeout adjustments, with
system_prompt omitted. The active profile supplies the base when selected; otherwise the
conversation default does. May be absent on older turns or when neither supplies a
configuration.
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/generation-config#request).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#request).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: 0
Maximum: 3
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#request).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinitionInput]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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**
Which server provides this tool (for MCP tools).
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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinitionInput]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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**
Which server provides this tool (for MCP tools).
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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#request).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRuleInput]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#request).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#request).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#request).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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})*$
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#request).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#request).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#request).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#request).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#request).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#request).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
**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/generation-config#request).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#request).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: 0
Maximum: 3
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#request).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinitionInput]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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**
Which server provides this tool (for MCP tools).
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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinitionInput]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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**
Which server provides this tool (for MCP tools).
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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#request).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRuleInput]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#request).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#request).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#request).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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})*$
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#request).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#request).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#request).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#request).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#request).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#request).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
**profileVersion** `integer(int32)`
Immutable version of the active agent profile used to render this turn’s prompt. Absent on
older turns and turns without a profile template.
Minimum: -2147483648
Maximum: 2147483647
**fragmentsVersion** `integer(int32)`
Version of the prompt-fragment set used to render the profile prompt.
Minimum: -2147483648
Maximum: 2147483647
**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 [User Context] block as rendered into this turn's prompt: the user's
name, locale, and location conditions (weather/AQI/UV/sun times). This is
the literal text the model received, not a reconstruction.
Empty when the user has no stored location, when enrichment degraded, or
on turns predating capture.
**resolvedMcpServers** `array[MCPServerReferenceInput]`
The MCP server list that governed this turn — the tier actually resolved
(conversation settings -> active profile -> per-turn override_mcp_servers),
which is simultaneously the tool-discovery source and the CallTool
allow/block basis.
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/mcp-server-reference#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** `integer(int32)`
Priority override for tool selection (higher = preferred).
Minimum: -2147483648
Maximum: 2147483647
**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.
**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/client-context#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[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.
Model reference: [MessageFeedback](/api/models/message-feedback#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` | 1 | Canonical | Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice. |
| `FEEDBACK_KIND_SCALE` | 2 | Canonical | Feedback expressed as an integer rating from 1 through 10. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `FEEDBACK_KIND_THUMB`, `FEEDBACK_KIND_SCALE`
Variant 2:
Type: `integer(int32)`
Enum: `1`, `2`
Must not match:
Type: `any`
Enum: `0`
**thumbUp** `boolean`
Positive when true and negative when false; used for THUMB feedback.
**rating** `integer(int32)`
Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent.
Minimum: 0
Maximum: 10
**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.
**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/map values inherit, so clear_tools is used
to clear inherited 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/generation-config#request).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#request).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: 0
Maximum: 3
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#request).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinitionInput]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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**
Which server provides this tool (for MCP tools).
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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinitionInput]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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**
Which server provides this tool (for MCP tools).
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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#request).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRuleInput]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#request).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#request).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#request).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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})*$
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#request).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#request).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#request).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#request).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#request).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#request).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
**setActiveProfileId** `string`
Set the active agent profile for this and subsequent conversation turns.
**setActiveProfileVersion** `integer(int32)`
Version of the active agent profile forwarded with this turn.
Minimum: -2147483648
Maximum: 2147483647
**overrideMcpServers** `array[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/mcp-server-reference#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** `integer(int32)`
Priority override for tool selection (higher = preferred).
Minimum: -2147483648
Maximum: 2147483647
**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.
**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.
Model reference: [ExperimentContext](/api/models/experiment-context#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).
- Overview: `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.
## 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 (JWT) 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[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.
Model reference: [ClientToolResult](/api/models/client-tool-result#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:
Standardized error payload following google.rpc.Status (AIP-193).
Used across all response messages and event payloads.
Model reference: [RpcError](/api/models/rpc-error#request).
**code** `any`
Machine-readable error code. Clients switch on this field.
Machine-readable reason that a request or operation failed; inspect the accompanying error details for context.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `ERROR_CODE_CANCELLED` | 1 | Canonical | The caller cancelled the operation before it completed. |
| `ERROR_CODE_UNKNOWN` | 2 | Canonical | The operation failed without a more specific error classification. |
| `ERROR_CODE_INVALID_ARGUMENT` | 3 | Canonical | The request contains an invalid argument or field value. |
| `ERROR_CODE_DEADLINE_EXCEEDED` | 4 | Canonical | The operation did not complete before its deadline. |
| `ERROR_CODE_NOT_FOUND` | 5 | Canonical | The requested resource does not exist or could not be found. |
| `ERROR_CODE_ALREADY_EXISTS` | 6 | Canonical | The requested creation conflicts with a resource that already exists. |
| `ERROR_CODE_PERMISSION_DENIED` | 7 | Canonical | The authenticated caller is not permitted to perform the operation. |
| `ERROR_CODE_RESOURCE_EXHAUSTED` | 8 | Canonical | A quota, rate limit or other capacity limit prevented the operation. |
| `ERROR_CODE_FAILED_PRECONDITION` | 9 | Canonical | The operation requires a system or resource state that is not currently satisfied. |
| `ERROR_CODE_ABORTED` | 10 | Canonical | The operation was aborted, for example by a concurrent modification conflict. |
| `ERROR_CODE_OUT_OF_RANGE` | 11 | Canonical | An argument is outside the range supported by this operation. |
| `ERROR_CODE_UNIMPLEMENTED` | 12 | Canonical | The requested operation is not implemented. |
| `ERROR_CODE_INTERNAL` | 13 | Canonical | An internal failure prevented the operation from completing. |
| `ERROR_CODE_UNAVAILABLE` | 14 | Canonical | The service or a required dependency is temporarily unavailable. |
| `ERROR_CODE_DATA_LOSS` | 15 | Canonical | The operation encountered unrecoverable loss or corruption of data. |
| `ERROR_CODE_UNAUTHENTICATED` | 16 | Canonical | Authentication credentials are missing or invalid. |
| `ERROR_CODE_MODEL_INVALID` | 600 | Canonical | The requested model identifier is absent from the model catalog. |
| `ERROR_CODE_MODEL_UNAVAILABLE` | 601 | Canonical | The model exists, but no provider is currently available to serve it. |
| `ERROR_CODE_MODERATION_FLAGGED` | 602 | Canonical | Content moderation flagged the submitted content. |
| `ERROR_CODE_GENERATION_FAILED` | 603 | Canonical | Model generation failed after its configured attempts. |
| `ERROR_CODE_TOOL_EXECUTION_FAILED` | 604 | Canonical | Execution of a requested tool failed. |
| `ERROR_CODE_UPSTREAM_PROVIDER` | 605 | Canonical | An upstream model provider returned an error. |
| `ERROR_CODE_VALIDATION_EXHAUSTED` | 606 | Canonical | Structured-output validation still failed after the configured attempts. |
| `ERROR_CODE_PAYMENT_REQUIRED` | 607 | Canonical | The account lacks the credits required for the operation. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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 terminal (non-retryable). When true, repeating the
same request will produce the same error. When false, transient condition
may resolve on retry.
**details** `any`
Structured error details. At most one of each detail type.
Follows google.rpc.Status details pattern but uses concrete types
instead of google.protobuf.Any for type safety and codegen.
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/error-details#request).
**errorInfo** `any`
Identifies the error for machine consumption.
REQUIRED on all errors per AIP-193 (enforced at Go helper level).
All of:
Variant 1:
Machine-readable error identification (per AIP-193, every error must include this).
Model reference: [ErrorInfo](/api/models/error-info#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/retry-info#request).
**retryDelayMs** `string(int64)`
Suggested minimum delay before retrying, in milliseconds.
Pattern: ^-?\d+$
**fieldViolations** `array[FieldViolationInput]`
Field-level validation failures.
A single field-level validation violation.
Model reference: [FieldViolation](/api/models/field-violation#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.
Model reference: [UpstreamError](/api/models/upstream-error#request).
**provider** `string`
Name of the upstream provider that reported the error.
**statusCode** `integer(int32)`
HTTP status code returned by the provider.
Minimum: -2147483648
Maximum: 2147483647
**rawBody** `string`
Raw error body from the provider. Truncated to 512 bytes (enforced at Go level).
**modelError** `any`
Model-specific error context.
All of:
Variant 1:
Model-specific error context.
Model reference: [ModelError](/api/models/model-error#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[HelpLinkInput]`
Help links for error resolution.
A help link for error resolution.
Model reference: [HelpLink](/api/models/help-link#request).
**url** `string`
URL to documentation or resolution guide.
**description** `string`
Description of what the link provides.
**clientToolCursor** `integer(int32)`
dispatch_seq this caller last observed — same semantics as
AwaitGenerationRequest.client_tool_cursor. 0 on first call.
Minimum: -2147483648
Maximum: 2147483647
#### 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[Message]`
Conversation messages returned by the generation segment.
Chat message
Model reference: [Message](/api/models/message#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` | 1 | Canonical | Instructions or context provided as a system message. |
| `ROLE_USER` | 2 | Canonical | Input supplied by the user or customer application. |
| `ROLE_ASSISTANT` | 3 | Canonical | Content produced by the assistant, including its tool-call requests. |
| `ROLE_TOOL` | 4 | 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)`
Must not match:
Type: `any`
Enum: `0`
**content** `array[ContentPart]`
Content parts composing the chat message.
Content parts composing a message (flattened structure for JSON compatibility)
Model reference: [ContentPart](/api/models/content-part#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` | 1 | Canonical | Plain text carried by the content part. |
| `CONTENT_PART_TYPE_IMAGE_URL` | 2 | Canonical | An image supplied through a remote URL. |
| `CONTENT_PART_TYPE_IMAGE_BASE64` | 3 | Canonical | An image supplied as base64-encoded bytes. |
| `CONTENT_PART_TYPE_FILE_ID` | 4 | Canonical | A provider file identifier or internal storage identifier resolved before generation. |
| `CONTENT_PART_TYPE_FILE_PATH` | 5 | Canonical | A reference to a local file path. |
| `CONTENT_PART_TYPE_FILE_URL` | 6 | Canonical | A file supplied through a public or signed URL. |
| `CONTENT_PART_TYPE_FILE_DATA_URL` | 7 | Canonical | A file embedded in a data URL, including its media type and encoded data. |
| `CONTENT_PART_TYPE_AUDIO_BASE64` | 8 | Canonical | Base64-encoded audio; the part metadata identifies its audio format. |
| `CONTENT_PART_TYPE_REASONING` | 9 | Canonical | A reasoning segment returned by a model provider, when available. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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/content-part#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/content-part#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/structured-message#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[ToolCall]`
Assistant-to-tool invocations.
A single structured tool call emitted by the model
[`clientToolDeadlineAt`](/api/models/tool-call#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/tool-call#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 one tool call, including approval waiting and terminal outcomes.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `TOOL_EXECUTION_STATUS_PENDING` | 1 | Canonical | The tool call is waiting to begin execution. |
| `TOOL_EXECUTION_STATUS_EXECUTING` | 2 | Canonical | The tool call is currently executing. |
| `TOOL_EXECUTION_STATUS_COMPLETED` | 3 | Canonical | The tool call completed successfully. Responses use this canonical spelling for numeric value 3. |
| `TOOL_EXECUTION_STATUS_SUCCESS` | 3 | Alias of `TOOL_EXECUTION_STATUS_COMPLETED`; Name not accepted for this field; number accepted | Legacy alias of TOOL_EXECUTION_STATUS_COMPLETED with the same numeric value; use COMPLETED for new writes. |
| `TOOL_EXECUTION_STATUS_FAILED` | 4 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. |
| `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 5 | Canonical | The tool call is waiting for approval before it can execute. |
| `TOOL_EXECUTION_STATUS_CANCELLED` | 6 | Canonical | The tool call was cancelled before normal completion. |
| `TOOL_EXECUTION_STATUS_TIMED_OUT` | 7 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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 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", the underlying error. Set only once `status` is
terminal, and empty on a clean COMPLETED.
**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. Mirrors requires_approval_at.
**name** `string`
Name identifying the sender of the chat message.
**timestamp** `string(date-time)`
Timestamp associated with the conversation message or event.
**messageId** `string`
Unique message identifier.
**annotations** `array[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/annotation#response).
**urlCitation** `any`
Submessage fields (optional); populate the one matching kind
All of:
Variant 1:
=== Annotations ===
Web source and character range cited in generated message content.
Model reference: [UrlCitation](/api/models/url-citation#response).
**url** `string`
URL associated with the resource or outbound request.
**title** `string`
Title of the web page cited by this annotation.
**content** `string`
Excerpt or snippet of the cited web page.
**startIndex** `integer(int32)`
Character index in message content.
Minimum: -2147483648
Maximum: 2147483647
**endIndex** `integer(int32)`
Character index in message content.
Minimum: -2147483648
Maximum: 2147483647
**pdf** `any`
PDF annotation or parser configuration selected by the enclosing message.
All of:
Variant 1:
Provider annotation identifying a parsed PDF and reusable parsing output.
Model reference: [PdfAnnotation](/api/models/pdf-annotation#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[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 (flattened structure for JSON compatibility)
Model reference: [ContentPart](/api/models/content-part#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` | 1 | Canonical | Plain text carried by the content part. |
| `CONTENT_PART_TYPE_IMAGE_URL` | 2 | Canonical | An image supplied through a remote URL. |
| `CONTENT_PART_TYPE_IMAGE_BASE64` | 3 | Canonical | An image supplied as base64-encoded bytes. |
| `CONTENT_PART_TYPE_FILE_ID` | 4 | Canonical | A provider file identifier or internal storage identifier resolved before generation. |
| `CONTENT_PART_TYPE_FILE_PATH` | 5 | Canonical | A reference to a local file path. |
| `CONTENT_PART_TYPE_FILE_URL` | 6 | Canonical | A file supplied through a public or signed URL. |
| `CONTENT_PART_TYPE_FILE_DATA_URL` | 7 | Canonical | A file embedded in a data URL, including its media type and encoded data. |
| `CONTENT_PART_TYPE_AUDIO_BASE64` | 8 | Canonical | Base64-encoded audio; the part metadata identifies its audio format. |
| `CONTENT_PART_TYPE_REASONING` | 9 | Canonical | A reasoning segment returned by a model provider, when available. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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/content-part#response-field-structuredmessage); ordinary text is still present. [`structuredMessage`](/api/models/content-part#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/structured-message#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.
**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` | 1 | Canonical | A citation to a source identified by its URL. |
| `ANNOTATION_KIND_PDF` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/usage#response).
**promptTokens** `integer(int32)`
Prompt-token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**completionTokens** `integer(int32)`
Completion-token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**totalTokens** `integer(int32)`
Total token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**costEstimate** `any`
Estimated cost in USD.
Exactly one of:
Variant 1:
Type: `number(float)`
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; one category must not be derived by subtracting the
others.
Model reference: [CompletionTokensDetails](/api/models/completion-tokens-details#response).
**reasoningTokens** `integer(int32)`
Tokens used for reasoning/thinking.
Minimum: -2147483648
Maximum: 2147483647
**imageTokens** `integer(int32)`
Completion tokens emitted as image output.
Minimum: -2147483648
Maximum: 2147483647
**audioTokens** `integer(int32)`
Completion tokens emitted as audio output.
Minimum: -2147483648
Maximum: 2147483647
**promptTokensDetails** `any`
Breakdown of prompt tokens (cache).
All of:
Variant 1:
Breakdown of prompt token usage by category (input-side cache accounting)
Model reference: [PromptTokensDetails](/api/models/prompt-tokens-details#response).
**cachedTokens** `integer(int32)`
Prompt tokens served from cache (cache READ).
Minimum: -2147483648
Maximum: 2147483647
**cacheWriteTokens** `integer(int32)`
Prompt tokens written to cache this call (cache WRITE).
Minimum: -2147483648
Maximum: 2147483647
**audioTokens** `integer(int32)`
Prompt tokens from audio input (multimodal).
Minimum: -2147483648
Maximum: 2147483647
**videoTokens** `integer(int32)`
Prompt tokens from video input (multimodal).
Minimum: -2147483648
Maximum: 2147483647
**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/cost-details#response).
**upstreamInferenceCost** `any`
Total upstream provider cost (USD) on BYOK routes.
Exactly one of:
Variant 1:
Type: `number(float)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**upstreamInferencePromptCost** `any`
Upstream cost attributed to prompt tokens (USD).
Exactly one of:
Variant 1:
Type: `number(float)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**upstreamInferenceCompletionCost** `any`
Upstream cost attributed to completion tokens (USD).
Exactly one of:
Variant 1:
Type: `number(float)`
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/generation-context#response).
**memories** `array[MemoryReference]`
Memory records captured in the generation context.
A memory record retrieved and included in generation context.
Model reference: [MemoryReference](/api/models/memory-reference#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(float)`
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[RelationReference]`
Graph relationships captured in the generation context.
A graph relationship retrieved and included in generation context.
Model reference: [RelationReference](/api/models/relation-reference#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/memory-search-params#response).
**query** `string`
Text submitted to memory retrieval for this generation.
**topK** `integer(int32)`
Maximum memory matches requested during generation-context retrieval.
Minimum: -2147483648
Maximum: 2147483647
**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** `integer(int32)`
Number of memory records returned by the search.
Minimum: -2147483648
Maximum: 2147483647
**relationsReturned** `integer(int32)`
Number of graph relationships returned by the search.
Minimum: -2147483648
Maximum: 2147483647
**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/turn-info#response).
**currentTurn** `integer(int32)`
Current turn position within the generation run.
Minimum: -2147483648
Maximum: 2147483647
**maxTurns** `integer(int32)`
Maximum turns configured for the generation run.
Minimum: -2147483648
Maximum: 2147483647
**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 prompt for a generation turn.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `PROMPT_SOURCE_CLIENT_OVERRIDE` | 1 | Canonical | The caller supplied the prompt through the send request's generation-configuration override. |
| `PROMPT_SOURCE_PROFILE_TEMPLATE` | 2 | Canonical | The prompt was rendered from the active agent profile template. |
| `PROMPT_SOURCE_DEFAULT_CONFIG` | 3 | Canonical | The prompt came from the conversation or project default generation configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**baseConfig** `any`
Generation configuration resolved before per-call overrides and timeout adjustments, with
system_prompt omitted. The active profile supplies the base when selected; otherwise the
conversation default does. May be absent on older turns or when neither supplies a
configuration.
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/generation-config#response).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#response).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: -2147483648
Maximum: 2147483647
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#response).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinition]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinition]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#response).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRule]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#response).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#response).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#response).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**languagePreference** `string`
Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware)
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#response).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#response).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#response).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#response).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#response).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#response).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
**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/generation-config#response).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#response).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: -2147483648
Maximum: 2147483647
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#response).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinition]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinition]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#response).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRule]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#response).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#response).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#response).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**languagePreference** `string`
Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware)
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#response).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#response).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#response).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#response).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#response).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#response).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
**profileVersion** `integer(int32)`
Immutable version of the active agent profile used to render this turn’s prompt. Absent on
older turns and turns without a profile template.
Minimum: -2147483648
Maximum: 2147483647
**fragmentsVersion** `integer(int32)`
Version of the prompt-fragment set used to render the profile prompt.
Minimum: -2147483648
Maximum: 2147483647
**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 [User Context] block as rendered into this turn's prompt: the user's
name, locale, and location conditions (weather/AQI/UV/sun times). This is
the literal text the model received, not a reconstruction.
Empty when the user has no stored location, when enrichment degraded, or
on turns predating capture.
**resolvedMcpServers** `array[MCPServerReference]`
The MCP server list that governed this turn — the tier actually resolved
(conversation settings -> active profile -> per-turn override_mcp_servers),
which is simultaneously the tool-discovery source and the CallTool
allow/block basis.
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/mcp-server-reference#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** `integer(int32)`
Priority override for tool selection (higher = preferred).
Minimum: -2147483648
Maximum: 2147483647
**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.
**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/client-context#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[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.
Model reference: [MessageFeedback](/api/models/message-feedback#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` | 1 | Canonical | Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice. |
| `FEEDBACK_KIND_SCALE` | 2 | Canonical | Feedback expressed as an integer rating from 1 through 10. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `FEEDBACK_KIND_THUMB`, `FEEDBACK_KIND_SCALE`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**thumbUp** `boolean`
Positive when true and negative when false; used for THUMB feedback.
**rating** `integer(int32)`
Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent.
Minimum: -2147483648
Maximum: 2147483647
**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.
**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.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `AGENT_STATUS_ACTIVE` | 1 | Canonical | The run is active and has not yet reached a more specific execution phase or terminal outcome. |
| `AGENT_STATUS_GENERATING` | 2 | Canonical | The run is generating a model response. |
| `AGENT_STATUS_EXECUTING_TOOLS` | 3 | Canonical | The run is executing server-side tools. |
| `AGENT_STATUS_COMPLETED` | 4 | Canonical | The run finished successfully. |
| `AGENT_STATUS_FAILED` | 5 | Canonical | The run ended with a failure; inspect its error or end reason. |
| `AGENT_STATUS_QUEUED` | 6 | Canonical | The incoming message is queued behind an ongoing run under the queue interruption policy. |
| `AGENT_STATUS_AWAITING_CLIENT_TOOLS` | 7 | Canonical | The run is waiting for the caller to execute client-side tools and submit their results. |
| `AGENT_STATUS_CANCELLED` | 8 | Canonical | The run ended because a client or its invocation cancelled it. |
| `AGENT_STATUS_TIMED_OUT` | 9 | Canonical | The run ended because a run-level time limit 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)`
Must not match:
Type: `any`
Enum: `0`
**aggregateUsage** `any`
Aggregated model usage reported for the generation run.
All of:
Variant 1:
Usage accounting
Model reference: [Usage](/api/models/usage#response).
**promptTokens** `integer(int32)`
Prompt-token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**completionTokens** `integer(int32)`
Completion-token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**totalTokens** `integer(int32)`
Total token usage reported by the model provider.
Minimum: -2147483648
Maximum: 2147483647
**costEstimate** `any`
Estimated cost in USD.
Exactly one of:
Variant 1:
Type: `number(float)`
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; one category must not be derived by subtracting the
others.
Model reference: [CompletionTokensDetails](/api/models/completion-tokens-details#response).
**reasoningTokens** `integer(int32)`
Tokens used for reasoning/thinking.
Minimum: -2147483648
Maximum: 2147483647
**imageTokens** `integer(int32)`
Completion tokens emitted as image output.
Minimum: -2147483648
Maximum: 2147483647
**audioTokens** `integer(int32)`
Completion tokens emitted as audio output.
Minimum: -2147483648
Maximum: 2147483647
**promptTokensDetails** `any`
Breakdown of prompt tokens (cache).
All of:
Variant 1:
Breakdown of prompt token usage by category (input-side cache accounting)
Model reference: [PromptTokensDetails](/api/models/prompt-tokens-details#response).
**cachedTokens** `integer(int32)`
Prompt tokens served from cache (cache READ).
Minimum: -2147483648
Maximum: 2147483647
**cacheWriteTokens** `integer(int32)`
Prompt tokens written to cache this call (cache WRITE).
Minimum: -2147483648
Maximum: 2147483647
**audioTokens** `integer(int32)`
Prompt tokens from audio input (multimodal).
Minimum: -2147483648
Maximum: 2147483647
**videoTokens** `integer(int32)`
Prompt tokens from video input (multimodal).
Minimum: -2147483648
Maximum: 2147483647
**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/cost-details#response).
**upstreamInferenceCost** `any`
Total upstream provider cost (USD) on BYOK routes.
Exactly one of:
Variant 1:
Type: `number(float)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**upstreamInferencePromptCost** `any`
Upstream cost attributed to prompt tokens (USD).
Exactly one of:
Variant 1:
Type: `number(float)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**upstreamInferenceCompletionCost** `any`
Upstream cost attributed to completion tokens (USD).
Exactly one of:
Variant 1:
Type: `number(float)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**isByok** `boolean`
Whether this generation used the customer's own model-provider key.
**pendingClientTools** `array[ToolCall]`
Tool calls dispatched for execution by the client.
A single structured tool call emitted by the model
[`clientToolDeadlineAt`](/api/models/tool-call#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/tool-call#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 one tool call, including approval waiting and terminal outcomes.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `TOOL_EXECUTION_STATUS_PENDING` | 1 | Canonical | The tool call is waiting to begin execution. |
| `TOOL_EXECUTION_STATUS_EXECUTING` | 2 | Canonical | The tool call is currently executing. |
| `TOOL_EXECUTION_STATUS_COMPLETED` | 3 | Canonical | The tool call completed successfully. Responses use this canonical spelling for numeric value 3. |
| `TOOL_EXECUTION_STATUS_SUCCESS` | 3 | Alias of `TOOL_EXECUTION_STATUS_COMPLETED`; Name not accepted for this field; number accepted | Legacy alias of TOOL_EXECUTION_STATUS_COMPLETED with the same numeric value; use COMPLETED for new writes. |
| `TOOL_EXECUTION_STATUS_FAILED` | 4 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. |
| `TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION` | 5 | Canonical | The tool call is waiting for approval before it can execute. |
| `TOOL_EXECUTION_STATUS_CANCELLED` | 6 | Canonical | The tool call was cancelled before normal completion. |
| `TOOL_EXECUTION_STATUS_TIMED_OUT` | 7 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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 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", the underlying error. Set only once `status` is
terminal, and empty on a clean COMPLETED.
**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. Mirrors requires_approval_at.
**clientToolCursor** `integer(int32)`
Latest client-tool dispatch sequence represented by this response.
Minimum: -2147483648
Maximum: 2147483647
**error** `any`
Structured error for partial success scenarios. Full failures propagate
as TerminalError → HTTP error status + RpcError JSON body.
All of:
Variant 1:
Standardized error payload following google.rpc.Status (AIP-193).
Used across all response messages and event payloads.
Model reference: [RpcError](/api/models/rpc-error#response).
**code** `any`
Machine-readable error code. Clients switch on this field.
Machine-readable reason that a request or operation failed; inspect the accompanying error details for context.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `ERROR_CODE_CANCELLED` | 1 | Canonical | The caller cancelled the operation before it completed. |
| `ERROR_CODE_UNKNOWN` | 2 | Canonical | The operation failed without a more specific error classification. |
| `ERROR_CODE_INVALID_ARGUMENT` | 3 | Canonical | The request contains an invalid argument or field value. |
| `ERROR_CODE_DEADLINE_EXCEEDED` | 4 | Canonical | The operation did not complete before its deadline. |
| `ERROR_CODE_NOT_FOUND` | 5 | Canonical | The requested resource does not exist or could not be found. |
| `ERROR_CODE_ALREADY_EXISTS` | 6 | Canonical | The requested creation conflicts with a resource that already exists. |
| `ERROR_CODE_PERMISSION_DENIED` | 7 | Canonical | The authenticated caller is not permitted to perform the operation. |
| `ERROR_CODE_RESOURCE_EXHAUSTED` | 8 | Canonical | A quota, rate limit or other capacity limit prevented the operation. |
| `ERROR_CODE_FAILED_PRECONDITION` | 9 | Canonical | The operation requires a system or resource state that is not currently satisfied. |
| `ERROR_CODE_ABORTED` | 10 | Canonical | The operation was aborted, for example by a concurrent modification conflict. |
| `ERROR_CODE_OUT_OF_RANGE` | 11 | Canonical | An argument is outside the range supported by this operation. |
| `ERROR_CODE_UNIMPLEMENTED` | 12 | Canonical | The requested operation is not implemented. |
| `ERROR_CODE_INTERNAL` | 13 | Canonical | An internal failure prevented the operation from completing. |
| `ERROR_CODE_UNAVAILABLE` | 14 | Canonical | The service or a required dependency is temporarily unavailable. |
| `ERROR_CODE_DATA_LOSS` | 15 | Canonical | The operation encountered unrecoverable loss or corruption of data. |
| `ERROR_CODE_UNAUTHENTICATED` | 16 | Canonical | Authentication credentials are missing or invalid. |
| `ERROR_CODE_MODEL_INVALID` | 600 | Canonical | The requested model identifier is absent from the model catalog. |
| `ERROR_CODE_MODEL_UNAVAILABLE` | 601 | Canonical | The model exists, but no provider is currently available to serve it. |
| `ERROR_CODE_MODERATION_FLAGGED` | 602 | Canonical | Content moderation flagged the submitted content. |
| `ERROR_CODE_GENERATION_FAILED` | 603 | Canonical | Model generation failed after its configured attempts. |
| `ERROR_CODE_TOOL_EXECUTION_FAILED` | 604 | Canonical | Execution of a requested tool failed. |
| `ERROR_CODE_UPSTREAM_PROVIDER` | 605 | Canonical | An upstream model provider returned an error. |
| `ERROR_CODE_VALIDATION_EXHAUSTED` | 606 | Canonical | Structured-output validation still failed after the configured attempts. |
| `ERROR_CODE_PAYMENT_REQUIRED` | 607 | Canonical | The account lacks the credits required for the operation. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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 terminal (non-retryable). When true, repeating the
same request will produce the same error. When false, transient condition
may resolve on retry.
**details** `any`
Structured error details. At most one of each detail type.
Follows google.rpc.Status details pattern but uses concrete types
instead of google.protobuf.Any for type safety and codegen.
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/error-details#response).
**errorInfo** `any`
Identifies the error for machine consumption.
REQUIRED on all errors per AIP-193 (enforced at Go helper level).
All of:
Variant 1:
Machine-readable error identification (per AIP-193, every error must include this).
Model reference: [ErrorInfo](/api/models/error-info#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/retry-info#response).
**retryDelayMs** `string(int64)`
Suggested minimum delay before retrying, in milliseconds.
Pattern: ^-?\d+$
**fieldViolations** `array[FieldViolation]`
Field-level validation failures.
A single field-level validation violation.
Model reference: [FieldViolation](/api/models/field-violation#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.
Model reference: [UpstreamError](/api/models/upstream-error#response).
**provider** `string`
Name of the upstream provider that reported the error.
**statusCode** `integer(int32)`
HTTP status code returned by the provider.
Minimum: -2147483648
Maximum: 2147483647
**rawBody** `string`
Raw error body from the provider. Truncated to 512 bytes (enforced at Go level).
**modelError** `any`
Model-specific error context.
All of:
Variant 1:
Model-specific error context.
Model reference: [ModelError](/api/models/model-error#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[HelpLink]`
Help links for error resolution.
A help link for error resolution.
Model reference: [HelpLink](/api/models/help-link#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).
- Overview: `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.
## 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 (JWT) 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[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.
Model reference: [ClientToolResult](/api/models/client-tool-result#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:
Standardized error payload following google.rpc.Status (AIP-193).
Used across all response messages and event payloads.
Model reference: [RpcError](/api/models/rpc-error#request).
**code** `any`
Machine-readable error code. Clients switch on this field.
Machine-readable reason that a request or operation failed; inspect the accompanying error details for context.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `ERROR_CODE_CANCELLED` | 1 | Canonical | The caller cancelled the operation before it completed. |
| `ERROR_CODE_UNKNOWN` | 2 | Canonical | The operation failed without a more specific error classification. |
| `ERROR_CODE_INVALID_ARGUMENT` | 3 | Canonical | The request contains an invalid argument or field value. |
| `ERROR_CODE_DEADLINE_EXCEEDED` | 4 | Canonical | The operation did not complete before its deadline. |
| `ERROR_CODE_NOT_FOUND` | 5 | Canonical | The requested resource does not exist or could not be found. |
| `ERROR_CODE_ALREADY_EXISTS` | 6 | Canonical | The requested creation conflicts with a resource that already exists. |
| `ERROR_CODE_PERMISSION_DENIED` | 7 | Canonical | The authenticated caller is not permitted to perform the operation. |
| `ERROR_CODE_RESOURCE_EXHAUSTED` | 8 | Canonical | A quota, rate limit or other capacity limit prevented the operation. |
| `ERROR_CODE_FAILED_PRECONDITION` | 9 | Canonical | The operation requires a system or resource state that is not currently satisfied. |
| `ERROR_CODE_ABORTED` | 10 | Canonical | The operation was aborted, for example by a concurrent modification conflict. |
| `ERROR_CODE_OUT_OF_RANGE` | 11 | Canonical | An argument is outside the range supported by this operation. |
| `ERROR_CODE_UNIMPLEMENTED` | 12 | Canonical | The requested operation is not implemented. |
| `ERROR_CODE_INTERNAL` | 13 | Canonical | An internal failure prevented the operation from completing. |
| `ERROR_CODE_UNAVAILABLE` | 14 | Canonical | The service or a required dependency is temporarily unavailable. |
| `ERROR_CODE_DATA_LOSS` | 15 | Canonical | The operation encountered unrecoverable loss or corruption of data. |
| `ERROR_CODE_UNAUTHENTICATED` | 16 | Canonical | Authentication credentials are missing or invalid. |
| `ERROR_CODE_MODEL_INVALID` | 600 | Canonical | The requested model identifier is absent from the model catalog. |
| `ERROR_CODE_MODEL_UNAVAILABLE` | 601 | Canonical | The model exists, but no provider is currently available to serve it. |
| `ERROR_CODE_MODERATION_FLAGGED` | 602 | Canonical | Content moderation flagged the submitted content. |
| `ERROR_CODE_GENERATION_FAILED` | 603 | Canonical | Model generation failed after its configured attempts. |
| `ERROR_CODE_TOOL_EXECUTION_FAILED` | 604 | Canonical | Execution of a requested tool failed. |
| `ERROR_CODE_UPSTREAM_PROVIDER` | 605 | Canonical | An upstream model provider returned an error. |
| `ERROR_CODE_VALIDATION_EXHAUSTED` | 606 | Canonical | Structured-output validation still failed after the configured attempts. |
| `ERROR_CODE_PAYMENT_REQUIRED` | 607 | Canonical | The account lacks the credits required for the operation. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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 terminal (non-retryable). When true, repeating the
same request will produce the same error. When false, transient condition
may resolve on retry.
**details** `any`
Structured error details. At most one of each detail type.
Follows google.rpc.Status details pattern but uses concrete types
instead of google.protobuf.Any for type safety and codegen.
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/error-details#request).
**errorInfo** `any`
Identifies the error for machine consumption.
REQUIRED on all errors per AIP-193 (enforced at Go helper level).
All of:
Variant 1:
Machine-readable error identification (per AIP-193, every error must include this).
Model reference: [ErrorInfo](/api/models/error-info#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/retry-info#request).
**retryDelayMs** `string(int64)`
Suggested minimum delay before retrying, in milliseconds.
Pattern: ^-?\d+$
**fieldViolations** `array[FieldViolationInput]`
Field-level validation failures.
A single field-level validation violation.
Model reference: [FieldViolation](/api/models/field-violation#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.
Model reference: [UpstreamError](/api/models/upstream-error#request).
**provider** `string`
Name of the upstream provider that reported the error.
**statusCode** `integer(int32)`
HTTP status code returned by the provider.
Minimum: -2147483648
Maximum: 2147483647
**rawBody** `string`
Raw error body from the provider. Truncated to 512 bytes (enforced at Go level).
**modelError** `any`
Model-specific error context.
All of:
Variant 1:
Model-specific error context.
Model reference: [ModelError](/api/models/model-error#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[HelpLinkInput]`
Help links for error resolution.
A help link for error resolution.
Model reference: [HelpLink](/api/models/help-link#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.
**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).
- Overview: `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.
## 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 (JWT) 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[ToolApproval]`
Approval decisions for the identified pending tool calls.
Approval decision for a specific tool call
Model reference: [ToolApproval](/api/models/tool-approval#request).
**toolCallId** `string`
Identifier of the tool call being approved, executed, or retrieved.
**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).
- Overview: `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.
## 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 (JWT) 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/context-management-settings#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` | 1 | Canonical | Use completed compaction summaries and remaining history; fall back to windowing when no completed summary is available. |
| `CONTEXT_STRATEGY_WINDOWING` | 2 | Canonical | Keep a bounded window of recent conversation messages according to the windowing configuration. |
| `CONTEXT_STRATEGY_NONE` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**compactionConfig** `any`
Configuration applied when summarizing the conversation context.
All of:
Variant 1:
Configuration for compaction strategy
Model reference: [CompactionConfig](/api/models/compaction-config#request).
**mode** `any`
Context compaction mode selected by the operation.
Whether context compaction blocks the triggering operation or proceeds asynchronously.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `COMPACTION_MODE_SYNC` | 1 | Canonical | Wait for compaction to finish before continuing the dependent operation. |
| `COMPACTION_MODE_ASYNC` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**threshold** `any`
Token-count or context-window-percentage threshold that triggers compaction.
All of:
Variant 1:
Threshold configuration for triggering compaction
Model reference: [ThresholdConfig](/api/models/threshold-config#request).
All of:
Variant 1:
Type: `any`
Must not match:
Type: `any`
**tokenCount** `integer(int32)`
Absolute token limit.
Minimum: -2147483648
Maximum: 2147483647
**percentage** `integer(int32)`
% of model's context window.
Minimum: -2147483648
Maximum: 2147483647
**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/generation-config#request).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#request).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: 0
Maximum: 3
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#request).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinitionInput]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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**
Which server provides this tool (for MCP tools).
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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinitionInput]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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**
Which server provides this tool (for MCP tools).
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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#request).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRuleInput]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#request).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#request).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#request).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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})*$
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#request).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#request).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#request).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#request).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#request).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#request).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
**preserveRecent** `integer(int32)`
Messages to keep uncompacted.
Minimum: -2147483648
Maximum: 2147483647
**windowingConfig** `any`
Rules selecting the message window retained in model context.
All of:
Variant 1:
Configuration for windowing strategy
Model reference: [WindowingConfig](/api/models/windowing-config#request).
**maxMessages** `integer(int32)`
Maximum number of conversation messages to retain in the context window.
Minimum: -2147483648
Maximum: 2147483647
**selectiveExclusionConfig** `any`
Rules selecting content to omit from the model context.
All of:
Variant 1:
Configuration for selective exclusion
Model reference: [SelectiveExclusionConfig](/api/models/selective-exclusion-config#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/context-management-settings#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` | 1 | Canonical | Use completed compaction summaries and remaining history; fall back to windowing when no completed summary is available. |
| `CONTEXT_STRATEGY_WINDOWING` | 2 | Canonical | Keep a bounded window of recent conversation messages according to the windowing configuration. |
| `CONTEXT_STRATEGY_NONE` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**compactionConfig** `any`
Configuration applied when summarizing the conversation context.
All of:
Variant 1:
Configuration for compaction strategy
Model reference: [CompactionConfig](/api/models/compaction-config#response).
**mode** `any`
Context compaction mode selected by the operation.
Whether context compaction blocks the triggering operation or proceeds asynchronously.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `COMPACTION_MODE_SYNC` | 1 | Canonical | Wait for compaction to finish before continuing the dependent operation. |
| `COMPACTION_MODE_ASYNC` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**threshold** `any`
Token-count or context-window-percentage threshold that triggers compaction.
All of:
Variant 1:
Threshold configuration for triggering compaction
Model reference: [ThresholdConfig](/api/models/threshold-config#response).
All of:
Variant 1:
Type: `any`
Must not match:
Type: `any`
**tokenCount** `integer(int32)`
Absolute token limit.
Minimum: -2147483648
Maximum: 2147483647
**percentage** `integer(int32)`
% of model's context window.
Minimum: -2147483648
Maximum: 2147483647
**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/generation-config#response).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#response).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: -2147483648
Maximum: 2147483647
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#response).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinition]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinition]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#response).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRule]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#response).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#response).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#response).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**languagePreference** `string`
Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware)
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#response).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#response).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#response).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#response).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#response).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#response).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
**preserveRecent** `integer(int32)`
Messages to keep uncompacted.
Minimum: -2147483648
Maximum: 2147483647
**windowingConfig** `any`
Rules selecting the message window retained in model context.
All of:
Variant 1:
Configuration for windowing strategy
Model reference: [WindowingConfig](/api/models/windowing-config#response).
**maxMessages** `integer(int32)`
Maximum number of conversation messages to retain in the context window.
Minimum: -2147483648
Maximum: 2147483647
**selectiveExclusionConfig** `any`
Rules selecting content to omit from the model context.
All of:
Variant 1:
Configuration for selective exclusion
Model reference: [SelectiveExclusionConfig](/api/models/selective-exclusion-config#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).
- Overview: `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 default LLM generation configuration for a conversation. These defaults apply to every subsequent SendMessage unless overridden per-request.
## 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 (JWT) 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/generation-config#request).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#request).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: 0
Maximum: 3
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#request).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinitionInput]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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**
Which server provides this tool (for MCP tools).
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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinitionInput]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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**
Which server provides this tool (for MCP tools).
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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#request).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRuleInput]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#request).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#request).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#request).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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})*$
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#request).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#request).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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` | 1 | Canonical | Fail generation when a file content part cannot be resolved. |
| `FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT` | 2 | Canonical | Skip the unresolved content part and continue with the remaining content. |
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)`
Must not match:
Type: `any`
Enum: `0`
**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.
**topK** `integer(int32)`
Additional provider knobs
Minimum: -2147483648
Maximum: 2147483647
**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’s token-selection logits.
Map values:
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**topLogprobs** `integer(int32)`
Number of top token log probabilities requested from the provider.
Minimum: -2147483648
Maximum: 2147483647
**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` | 1 | Canonical | Request generated text output. |
| `MODALITY_IMAGE` | 2 | Canonical | Request generated image output where the model supports it. |
| `MODALITY_AUDIO` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**plugins** `array[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/plugin-config#request).
**id** `string`
Provider plugin identifier, such as 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/plugin-pdf-config#request).
**engine** `string`
PDF parsing engine selected for the provider plugin.
**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/plugin-web-config#request).
**engine** `string`
Search engine selected for the provider’s web-search plugin.
**maxResults** `integer(int32)`
Maximum web-search result count requested by the plugin.
Minimum: -2147483648
Maximum: 2147483647
**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/web-search-options#request).
**searchContextSize** `string`
Requested amount of web-search context: low, medium, or high.
**params** `map[string, string]`
Additional provider-specific plugin parameters.
#### 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/generation-config#response).
**temperature** `any`
Sampling temperature. 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.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxOutputTokens** `integer(int32)`
Maximum output-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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]`
Stop tokens/sequences (unchanged).
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/response-format#response).
**jsonObject** `boolean`
Whether the model provider is requested to return a valid JSON object.
**jsonSchema** `map[string, any]`
JSON Schema describing the requested structured model output.
**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** `integer(int32)`
Maximum retries when server-side validation fails.
Default: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).
Minimum: -2147483648
Maximum: 2147483647
**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
**model** `string`
Model selection
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/zero-value fields are ignored (no filtering on that dimension).
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/model-routing-filter#request-field-maxpromptcost) and [`maxCompletionCost`](/api/models/model-routing-filter#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; comprehensive [spending controls](/core-platform/billing-spend#spending-and-funding) are upcoming. Metadata-based capability filters also do not prove that a provider will honor a parameter on the eventual request.
Model reference: [ModelRoutingFilter](/api/models/model-routing-filter#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/provider-preferences#response).
**order** `array[string]`
Preferred ordering of model providers for routing.
Type: `string`
**allowFallbacks** `boolean`
Whether provider routing may fall back beyond the preferred order.
**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` | 1 | Canonical | Allow routing to providers that may collect submitted data under their policies. |
| `DATA_COLLECTION_MODE_DENY` | 2 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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.
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` | 1 | Canonical | Prefer providers with lower price. |
| `PROVIDER_SORT_THROUGHPUT` | 2 | Canonical | Prefer providers with higher throughput. |
| `PROVIDER_SORT_LATENCY` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**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/provider-max-price#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.
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.
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/percentile-threshold#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/percentile-threshold#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/reasoning-options#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/reasoning-options#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` | 1 | Canonical | Request the provider's high reasoning-effort level. |
| `EFFORT_MEDIUM` | 2 | Canonical | Request the provider's medium reasoning-effort level. |
| `EFFORT_LOW` | 3 | Canonical | Request the provider's low reasoning-effort level. |
| `EFFORT_XHIGH` | 4 | Canonical | Request the provider's extra-high reasoning-effort level where supported. |
| `EFFORT_MINIMAL` | 5 | Canonical | Request the provider's minimal reasoning-effort level where supported. |
| `EFFORT_NONE` | 6 | 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)`
Must not match:
Type: `any`
Enum: `0`
**maxTokens** `integer(int32)`
Maximum reasoning-token count requested from the model provider.
Minimum: -2147483648
Maximum: 2147483647
**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/usage-options#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[ToolDefinition]`
Tools & tool policy
Tool definitions exposed to the model for server-side execution.
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-choice#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` | 1 | Canonical | Let the provider decide whether to call an available tool. |
| `TOOL_CHOICE_KIND_NONE` | 2 | Canonical | Disable tool selection for this generation. |
| `TOOL_CHOICE_KIND_SPECIFIC` | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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)`
Must not match:
Type: `any`
Enum: `0`
**specificToolName** `string`
Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.
**clientTools** `array[ToolDefinition]`
Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)
Canonical tool/function definition used across all services
**[`serverId`](/api/models/tool-definition#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/tool-definition#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/tool-definition#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`
Which server provides this tool (for MCP tools).
**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/tool-execution-policy#request-field-approvaltimeoutms)
waits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#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/tool-execution-policy#request-field-retriabletoolnamepatterns),
[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),
[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),
[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and
[`retryBackoff`](/api/models/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-execution-policy#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/tool-call#response-field-clienttooldeadlineat).
See [Tool execution policies](/api/tool-execution/policies) for policy selection and
caller reconciliation.
Model reference: [ToolExecutionPolicy](/api/models/tool-execution-policy#response).
**requireApprovalToolNamePatterns** `array[string]`
Approvals
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
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `APPROVAL_MODE_MIXED` | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
| `APPROVAL_MODE_BLOCK_ALL` | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `APPROVAL_MODE_MIXED`, `APPROVAL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**clientToolMode** `any`
Stored requested client-tool scheduling mode; not enforced by the current workflow.
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `CLIENT_TOOL_MODE_MIXED` | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
| `CLIENT_TOOL_MODE_BLOCK_ALL` | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Exactly one of:
Variant 1:
Type: `string`
Enum: `CLIENT_TOOL_MODE_MIXED`, `CLIENT_TOOL_MODE_BLOCK_ALL`
Variant 2:
Type: `integer(int32)`
Must not match:
Type: `any`
Enum: `0`
**approvalTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**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[ToolExecutionOrderRule]`
Stored requested ordering rules; not applied by the current generation workflow.
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/tool-execution-order-rule#response).
**toolNamePatterns** `array[string]`
Requested tool-name patterns; not evaluated by the current generation workflow.
Type: `string`
**serverIds** `array[string]`
Requested MCP server filter; not evaluated by the current generation workflow.
Type: `string`
**weight** `integer(int32)`
Requested ordering weight; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**stableSortByCallIndexOnTie** `boolean`
Stored requested ordering tie-breaker; not applied by the current generation workflow.
**maxParallelToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**maxToolCallsPerLoop** `integer(int32)`
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**maxTotalToolCalls** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**retriableToolNamePatterns** `array[string]`
Stored requested retry selection; does not enable retries in the current workflow.
Type: `string`
**maxRetries** `integer(int32)`
Stored requested retry count; does not enable retries in the current workflow.
Minimum: -2147483648
Maximum: 2147483647
**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/backoff#response).
**initialMs** `integer(int32)`
Requested initial retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**multiplier** `any`
Requested retry-delay multiplier; not applied by the current generation workflow.
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**maxMs** `integer(int32)`
Requested maximum retry delay in milliseconds; not applied by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**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`
Timeouts
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/timeout-policy#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/tool-call#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/timeout-policy#response).
**overallMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**clientToolTimeoutMs** `integer(int32)`
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.
Minimum: -2147483648
Maximum: 2147483647
**failureMode** `any`
Stored requested failure action; not enforced by the current generation workflow.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**stopOnFailureRules** `array[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/tool-execution-policy#request-field-stoponfailurerules),
including [`priority`](/api/models/stop-on-failure-rule#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/stop-on-failure-rule#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.
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
| `FAILURE_MODE_CONTINUE` | 1 | Canonical | Request continued processing after the failed tool call. |
| `FAILURE_MODE_STOP_LOOP` | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
| `FAILURE_MODE_STOP_RUN` | 3 | 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)`
Must not match:
Type: `any`
Enum: `0`
**includeTimeouts** `boolean`
Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.
**errorSubstrings** `array[string]`
Requested error-text selection; not evaluated by the current generation workflow.
Type: `string`
**priority** `integer(int32)`
Requested rule priority; not evaluated by the current generation workflow.
Minimum: -2147483648
Maximum: 2147483647
**languagePreference** `string`
Language preference (BCP-47), e.g., "en-US", "es-ES" (presence-aware)
Nullable: true
**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.
Model reference: [TimeAwareConfig](/api/models/time-aware-config#response).
**includeCurrentTime** `boolean`
Append the current date and time to the system prompt as temporal context. Default: true.
**includeMessageTimestamps** `boolean`
Include timestamps on messages in the model 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/turn-context-config#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.
Memory integration is configured in the [`mem0`](/api/models/generation-config#request-field-mem0) block of a thread's [`defaultGenerationConfig`](/api/conversations/update-default-generation-config#request-field-defaultgenerationconfig)
(set at thread creation or via `update-default-generation-config`) or per turn via
[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).
Enabled memory integration provides retrieval **and asynchronous extraction**. Despite the legacy [`injectAsSystemContext`](/api/models/memory-config#request-field-injectassystemcontext) name, the current injection path adds retrieved context to the latest user message. [`addMemoriesAsync`](/api/models/memory-config#request-field-addmemoriesasync) is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. [`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) has no effect.
[`exposeAsMcpTool`](/api/models/memory-config#request-field-exposeasmcptool) currently has no effect. Use `search-memories` from your application or enable automatic retrieval with [`mem0.enabled`](/api/models/memory-config#request-field-enabled); setting this flag alone does not give the model a new tool.
Model reference: [MemoryConfig](/api/models/memory-config#response).
**enabled** `boolean`
Enable searching for relevant memories, adding them to generation context and extracting new
memories after generation. Default: false.
**searchTopK** `integer(int32)`
Number of memories to retrieve during search.
Higher values provide more context but increase token usage.
Range: 1-50 (validated only when enabled = true)
Default: 5
Minimum: -2147483648
Maximum: 2147483647
**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)
Default: 0.3
Exactly one of:
Variant 1:
Type: `number(double)`
Variant 2:
Type: `string`
Enum: `NaN`, `Infinity`, `-Infinity`
**injectAsSystemContext** `boolean`
When true, inject found memories into the system prompt context.
Memories are formatted as a bullet list under a "[Relevant memories:]" header.
Default: true
**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`
Enable reranking for improved search relevance.
Reranking provides better results but adds latency.
Default: false
**addMemoriesAsync** `boolean`
When true, memory extraction happens asynchronously after generation completes.
This prevents extraction latency from affecting response time.
Default: true
**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`
Expose memory search as an MCP tool during generation.
When true, the LLM can explicitly search memories via tool calls.
Rate limited to 3 searches per generation turn.
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** `integer(int32)`
Timeout for an individual model-provider request, in seconds. Zero selects the 30-second
default; other values are clamped to the range 1–600.
Minimum: -2147483648
Maximum: 2147483647
**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/file-resolution-config#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.