{ "version": 2, "contractRevision": "b8a4cbeb1c11d9bc869349b96b3f8763ec2b3d07eb97173f76109939c65a1c01", "operations": [ { "key": "agent-profiles:createAgentProfile", "operationId": "createAgentProfile", "bundle": "agent-profiles.yaml", "title": "Create an agent profile", "description": "Creates a profile in the caller's project library. A duplicate profile ID fails\nwith `ALREADY_EXISTS`; use [update](/api/agent-profiles/update-agent-profile) to\nreplace an existing profile. The store assigns the initial immutable version.\nThe system prompt must be a valid template and every variable spec needs a unique name;\notherwise create fails with `400`.\n\nEnabled profiles are immediately selectable. Disabled profiles are omitted from\nthe selection library, and a direct send naming one fails with\n`ACTIVE_PROFILE_DISABLED`. Queued messages currently take a different fallback\npath; see [unusable profiles](/managed-agents/conversations/configuration#when-the-active-profile-cannot-be-used).", "slug": "/api/agent-profiles/create-agent-profile", "method": "POST", "path": "/api/v1/agent-profiles/create", "requestSchema": "CreateAgentProfileRequest", "responseSchema": "CreateAgentProfileResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Profile created; the stored record is echoed back", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Authorized tenant backend secret key (`sk_…`). No end-user identity is needed for these configuration operations. Keep the key out of client apps; authorization and provisioning still apply." } } }, { "key": "agent-profiles:getAgentProfile", "operationId": "getAgentProfile", "bundle": "agent-profiles.yaml", "title": "Get an agent profile", "description": "Returns a full profile record at the selected immutable version. A profile or\nversion that never existed returns `NOT_FOUND`.", "slug": "/api/agent-profiles/get-agent-profile", "method": "POST", "path": "/api/v1/agent-profiles/get", "requestSchema": "GetAgentProfileRequest", "responseSchema": "GetAgentProfileResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Profile returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Authorized tenant backend secret key (`sk_…`). No end-user identity is needed for these configuration operations. Keep the key out of client apps; authorization and provisioning still apply." } } }, { "key": "agent-profiles:listAgentProfiles", "operationId": "listAgentProfiles", "bundle": "agent-profiles.yaml", "title": "List agent profiles", "description": "Returns a paginated collection of full profile records for inspection or editing.\nFor a lightweight selection view, use\n[library](/api/agent-profiles/get-agent-profile-library), which omits runtime\nconfiguration.", "slug": "/api/agent-profiles/list-agent-profiles", "method": "POST", "path": "/api/v1/agent-profiles/list", "requestSchema": "ListAgentProfilesRequest", "responseSchema": "ListAgentProfilesResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Page of profiles", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Authorized tenant backend secret key (`sk_…`). No end-user identity is needed for these configuration operations. Keep the key out of client apps; authorization and provisioning still apply." } } }, { "key": "agent-profiles:updateAgentProfile", "operationId": "updateAgentProfile", "bundle": "agent-profiles.yaml", "title": "Update an agent profile", "description": "Updates an agent profile. Each successful update appends a new immutable version; the\nprofile ID remains fixed and the store assigns the version.\n\n:::info Which fields change\nWithout an [`updateMask`](/api/agent-profiles/update-agent-profile#request-field-updatemask),\nonly the fields the supplied [`profile`](/api/agent-profiles/update-agent-profile#request-field-profile)\nsets change, and inside `generationConfig` only the sub-fields it sets. Nothing left out\nis cleared, so clearing a field needs a mask. A mask naming fields changes exactly those,\nclearing a named field the profile leaves unset; to replace the whole profile, name\nevery field. An update that would leave `name` or `whenToUse` empty is refused with\n`400`, as is one writing a system prompt that is not a valid template or variable specs\nwithout unique names.\n:::", "slug": "/api/agent-profiles/update-agent-profile", "method": "POST", "path": "/api/v1/agent-profiles/update", "requestSchema": "UpdateAgentProfileRequest", "responseSchema": "UpdateAgentProfileResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Profile updated; the new stored record is echoed back", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Authorized tenant backend secret key (`sk_…`). No end-user identity is needed for these configuration operations. Keep the key out of client apps; authorization and provisioning still apply." } } }, { "key": "agent-profiles:deleteAgentProfile", "operationId": "deleteAgentProfile", "bundle": "agent-profiles.yaml", "title": "Delete an agent profile", "description": "Deletes the profile from the current library without checking whether conversations\nstill reference it. Resolve dependent conversations before deletion.\n\n- If it was the project's [`defaultProfileId`](/api/models/agent-profile-library#response-field-defaultprofileid),\n that pointer is cleared.\n- Direct sends on conversations still naming it in [`activeProfileId`](/api/conversations/create-thread#request-field-activeprofileid)\n fail with `ACTIVE_PROFILE_NOT_FOUND`. Select an enabled replacement or restore the\n profile. A disabled replacement fails with `ACTIVE_PROFILE_DISABLED`. Queued\n messages can fall back to defaults and log the problem; see\n [unusable profiles](/managed-agents/conversations/configuration#when-the-active-profile-cannot-be-used).\n- Historical version records remain. Their retention does not prove that every\n dependent turn remains reproducible.", "slug": "/api/agent-profiles/delete-agent-profile", "method": "POST", "path": "/api/v1/agent-profiles/delete", "requestSchema": "DeleteAgentProfileRequest", "responseSchema": "DeleteAgentProfileResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Profile deleted", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Authorized tenant backend secret key (`sk_…`). No end-user identity is needed for these configuration operations. Keep the key out of client apps; authorization and provisioning still apply." } } }, { "key": "agent-profiles:getAgentProfileLibrary", "operationId": "getAgentProfileLibrary", "bundle": "agent-profiles.yaml", "title": "Get the profile library", "description": "Returns the project's profile-selection library for building a picker. Its\nselection metadata omits runtime configuration; use\n[get](/api/agent-profiles/get-agent-profile) to inspect or edit a full profile.\nThis discovery projection neither proves that an autonomous router is active nor\nguarantees a measured cost or latency improvement.\n\nFor a native conversation, pass the chosen profile ID through `activeProfileId`\non thread creation or `setActiveProfileId` when sending a message; Travila loads its\nconfiguration. The returned `defaultProfileId` is not applied automatically when\n`activeProfileId` is empty. Your client must explicitly select its intended profile.", "slug": "/api/agent-profiles/get-agent-profile-library", "method": "POST", "path": "/api/v1/agent-profiles/library", "requestSchema": "GetAgentProfileLibraryRequest", "responseSchema": "GetAgentProfileLibraryResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Selection metadata for the project", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Authorized tenant backend secret key (`sk_…`). No end-user identity is needed for these configuration operations. Keep the key out of client apps; authorization and provisioning still apply." } } }, { "key": "agent-profiles:listAgentProfileVersions", "operationId": "listAgentProfileVersions", "bundle": "agent-profiles.yaml", "title": "List a profile's versions", "description": "Returns stored profile versions newest first. Use a version with get to inspect that profile record. It does not establish what a past turn ran: actual fragment versions, resolved variables, renderer and effective generation settings must also be captured. A profile that never existed returns an empty list.", "slug": "/api/agent-profiles/list-agent-profile-versions", "method": "POST", "path": "/api/v1/agent-profiles/versions", "requestSchema": "ListAgentProfileVersionsRequest", "responseSchema": "ListAgentProfileVersionsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Version history, descending", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Authorized tenant backend secret key (`sk_…`). No end-user identity is needed for these configuration operations. Keep the key out of client apps; authorization and provisioning still apply." } } }, { "key": "agent-profiles:getPromptFragmentSet", "operationId": "getPromptFragmentSet", "bundle": "agent-profiles.yaml", "title": "Get a fragment set by version", "description": "Returns the fragments in a specified project-wide fragment-set version, ordered by fragment ID. Fragment writes advance the set version. A set version reconstructs that stored set, not a complete rendered turn. Current profile and fragment reads are independent and rendering can use the latest set; capture the set actually used alongside variables and effective configuration.", "slug": "/api/agent-profiles/get-prompt-fragment-set", "method": "POST", "path": "/api/v1/prompt-fragments/get-set", "requestSchema": "GetPromptFragmentSetRequest", "responseSchema": "GetPromptFragmentSetResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Fragments at that set version", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Authorized tenant backend secret key (`sk_…`). No end-user identity is needed for these configuration operations. Keep the key out of client apps; authorization and provisioning still apply." } } }, { "key": "agent-profiles:createPromptFragment", "operationId": "createPromptFragment", "bundle": "agent-profiles.yaml", "title": "Create a prompt fragment", "description": "Creates a reusable template block in the caller's project. The fragment ID must be\nunique within that project. Profiles that include the fragment share the stored\ntext, so a later edit affects every referencing profile.", "slug": "/api/agent-profiles/create-prompt-fragment", "method": "POST", "path": "/api/v1/prompt-fragments/create", "requestSchema": "CreatePromptFragmentRequest", "responseSchema": "CreatePromptFragmentResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Fragment created; the stored record is echoed back", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Authorized tenant backend secret key (`sk_…`). No end-user identity is needed for these configuration operations. Keep the key out of client apps; authorization and provisioning still apply." } } }, { "key": "agent-profiles:getPromptFragment", "operationId": "getPromptFragment", "bundle": "agent-profiles.yaml", "title": "Get a prompt fragment", "description": "Returns one fragment by id.", "slug": "/api/agent-profiles/get-prompt-fragment", "method": "POST", "path": "/api/v1/prompt-fragments/get", "requestSchema": "GetPromptFragmentRequest", "responseSchema": "GetPromptFragmentResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Fragment returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Authorized tenant backend secret key (`sk_…`). No end-user identity is needed for these configuration operations. Keep the key out of client apps; authorization and provisioning still apply." } } }, { "key": "agent-profiles:listPromptFragments", "operationId": "listPromptFragments", "bundle": "agent-profiles.yaml", "title": "List prompt fragments", "description": "Returns the project's fragments, paginated, together with the current project-wide\nfragment-set version.", "slug": "/api/agent-profiles/list-prompt-fragments", "method": "POST", "path": "/api/v1/prompt-fragments/list", "requestSchema": "ListPromptFragmentsRequest", "responseSchema": "ListPromptFragmentsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Page of fragments", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Authorized tenant backend secret key (`sk_…`). No end-user identity is needed for these configuration operations. Keep the key out of client apps; authorization and provisioning still apply." } } }, { "key": "agent-profiles:updatePromptFragment", "operationId": "updatePromptFragment", "bundle": "agent-profiles.yaml", "title": "Update a prompt fragment", "description": "Partially updates a fragment via [`updateMask`](/api/agent-profiles/update-prompt-fragment#request-field-updatemask),\nusing the mask semantics of [profile update](/managed-agents/profiles-prompts#update-a-profile).\n\nThe change reaches every profile that includes this fragment on its next turn and\nincrements the project-wide fragment-set version. There is no per-profile rollout.", "slug": "/api/agent-profiles/update-prompt-fragment", "method": "POST", "path": "/api/v1/prompt-fragments/update", "requestSchema": "UpdatePromptFragmentRequest", "responseSchema": "UpdatePromptFragmentResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Fragment updated; the new stored record is echoed back", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Authorized tenant backend secret key (`sk_…`). No end-user identity is needed for these configuration operations. Keep the key out of client apps; authorization and provisioning still apply." } } }, { "key": "agent-profiles:deletePromptFragment", "operationId": "deletePromptFragment", "bundle": "agent-profiles.yaml", "title": "Delete a prompt fragment", "description": "Deletes a fragment from the current set. The renderer reports missing fragments and\nother reachable-template errors; its caller can then return the original prompt.\n\n:::warning Deleting does not rewrite the profiles that include it\nA missing fragment can leave the system prompt unrendered, so literal\n`{{template \"safety\" .}}` text reaches the model. Generation may continue with that\nraw template; this is not a validated or safe fallback, and a successful response\ndoes not prove that the intended instructions were rendered. Other failures can\nstill stop the turn.\n\nCheck dependencies before removal: page through all profiles and inspect their\n[`generationConfig.systemPrompt`](/api/models/generation-config#request-field-systemprompt)\nvalues, then check nested fragment includes too. Checking one page or only direct\nincludes can miss a dependent profile.\n:::", "slug": "/api/agent-profiles/delete-prompt-fragment", "method": "POST", "path": "/api/v1/prompt-fragments/delete", "requestSchema": "DeletePromptFragmentRequest", "responseSchema": "DeletePromptFragmentResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Fragment deleted", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Authorized tenant backend secret key (`sk_…`). No end-user identity is needed for these configuration operations. Keep the key out of client apps; authorization and provisioning still apply." } } }, { "key": "agent-profiles:importAgentProfiles", "operationId": "importAgentProfiles", "bundle": "agent-profiles.yaml", "title": "Import a prompt library", "description": "Bulk-converts a source prompt library into profiles and reusable fragments.\nConversion happens at import time: prompts are rewritten to the platform template\nsyntax and variable specifications are derived from usage. The platform never\ninterprets the source DSL when serving a turn.\n\nExisting rows cause the import to stop at the first conflict with `ALREADY_EXISTS`,\nunless overwrite is enabled. In overwrite mode, existing profiles and fragments\nare replaced. Writes apply fragments before profiles and are not atomic across\nrows: a later failure can leave earlier writes in place. Re-read the library and\nreconcile it before retrying.", "slug": "/api/agent-profiles/import-agent-profiles", "method": "POST", "path": "/api/v1/agent-profiles/import", "requestSchema": "ImportAgentProfilesRequest", "responseSchema": "ImportAgentProfilesResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Converted profiles and fragments, as stored", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Authorized tenant backend secret key (`sk_…`). No end-user identity is needed for these configuration operations. Keep the key out of client apps; authorization and provisioning still apply." } } }, { "key": "connected-apps:pipedreamListApps", "operationId": "pipedreamListApps", "bundle": "connected-apps.yaml", "title": "List connectable apps", "description": "Lists the apps a user can connect, newest catalog first unless you sort. Use this to\nbuild an app picker.\n\nThis is public catalog data. It does not tell you what the caller has already\nconnected; use [`list-accounts`](/api/connected-apps/pipedream-list-accounts-for-current-user)\nfor that.", "slug": "/api/connected-apps/pipedream-list-apps", "method": "POST", "path": "/api/v1/integrations/pipedream/list-apps", "requestSchema": "PipedreamListAppsRequest", "responseSchema": "PipedreamListAppsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "A page of apps", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "connected-apps:pipedreamRetrieveApp", "operationId": "pipedreamRetrieveApp", "bundle": "connected-apps.yaml", "title": "Retrieve one app by slug", "description": "Returns a single app by its `nameSlug` — the stable identifier used everywhere else\nin this API (`github`, `slack`, `google_calendar`). Use it to render an app detail\npage without paging the whole catalog.", "slug": "/api/connected-apps/pipedream-retrieve-app", "method": "POST", "path": "/api/v1/integrations/pipedream/retrieve-app", "requestSchema": "PipedreamRetrieveAppRequest", "responseSchema": "PipedreamRetrieveAppResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "The app", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "connected-apps:pipedreamListAppCategories", "operationId": "pipedreamListAppCategories", "bundle": "connected-apps.yaml", "title": "List app categories", "description": "Lists the categories apps are grouped under (\"Developer Tools\", \"Communication\").\nFeed the returned `id` values into `categoryIds` on\n[`list-apps`](/api/connected-apps/pipedream-list-apps) to filter a picker by category.", "slug": "/api/connected-apps/pipedream-list-app-categories", "method": "POST", "path": "/api/v1/integrations/pipedream/list-app-categories", "requestSchema": "PipedreamListAppCategoriesRequest", "responseSchema": "PipedreamListAppCategoriesResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "A page of categories", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "connected-apps:pipedreamCreateConnectToken", "operationId": "pipedreamCreateConnectToken", "bundle": "connected-apps.yaml", "title": "Start connecting an app", "description": "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.\n\nFor 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.", "slug": "/api/connected-apps/pipedream-create-connect-token", "method": "POST", "path": "/api/v1/integrations/pipedream/create-connect-token", "requestSchema": "PipedreamCreateConnectTokenRequest", "responseSchema": "PipedreamCreateConnectTokenResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Connect token and hosted link", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "connected-apps:pipedreamListAccountsForCurrentUser", "operationId": "pipedreamListAccountsForCurrentUser", "bundle": "connected-apps.yaml", "title": "List the caller's connected accounts", "description": "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.", "slug": "/api/connected-apps/pipedream-list-accounts-for-current-user", "method": "POST", "path": "/api/v1/integrations/pipedream/list-accounts", "requestSchema": "PipedreamListAccountsForCurrentUserRequest", "responseSchema": "PipedreamListAccountsForCurrentUserResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "A page of the caller's connected accounts", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "connected-apps:pipedreamDeleteAccountForCurrentUser", "operationId": "pipedreamDeleteAccountForCurrentUser", "bundle": "connected-apps.yaml", "title": "Disconnect one account", "description": "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.", "slug": "/api/connected-apps/pipedream-delete-account-for-current-user", "method": "POST", "path": "/api/v1/integrations/pipedream/delete-account", "requestSchema": "PipedreamDeleteAccountForCurrentUserRequest", "responseSchema": "PipedreamDeleteAccountForCurrentUserResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Account disconnected", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "connected-apps:pipedreamDeleteExternalUserForCurrentUser", "operationId": "pipedreamDeleteExternalUserForCurrentUser", "bundle": "connected-apps.yaml", "title": "Delete the caller's integration data entirely", "description": "Requests irreversible deletion of the authenticated beneficiary's Pipedream external\nuser and associated connections. Use it as one step of offboarding, not as proof\nof erasure across every provider and backup. Reconnection creates new connection\nstate and requires fresh user authorization.\n\n[`accountsDeleted`](/api/connected-apps/pipedream-delete-external-user-for-current-user#response-field-accountsdeleted)\nis counted immediately before deletion and can differ under concurrent changes;\nit is not a per-account deletion receipt. Preserve your application's record of\ncleanup and unresolved external actions.", "slug": "/api/connected-apps/pipedream-delete-external-user-for-current-user", "method": "POST", "path": "/api/v1/integrations/pipedream/delete-external-user", "requestSchema": "PipedreamDeleteExternalUserForCurrentUserRequest", "responseSchema": "PipedreamDeleteExternalUserForCurrentUserResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "User and all their connected accounts deleted", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "connected-apps:pipedreamProxyForCurrentUser", "operationId": "pipedreamProxyForCurrentUser", "bundle": "connected-apps.yaml", "title": "Call a connected app's API as the user", "description": "Makes an HTTP request through the selected connected account. The account must\nbelong to the effective user and the destination is subject to the provider's\nallowed-domain rules. Those checks do not replace permission for the requested\naction. Each upstream app defines its own payload.\n\n### Upstream response handling\n\nRead the returned upstream [`status`](/api/connected-apps/pipedream-proxy-for-current-user#response-field-status)\nbefore treating the operation as successful: Travila can return HTTP 200 while\nthe app's response contains a 404. Upstream headers and the\n[`body`](/api/connected-apps/pipedream-proxy-for-current-user#response-field-body) are\nreturned as data, including on non-success status codes. Decode the body according\nto its content type; headers and bodies can contain third-party sensitive data.\n\nRedirects are returned, not followed. Treat `Location` as untrusted: it need not be\na signed or credential-free download URL. Validate the destination before opening\nit and never forward platform or account credentials to it.\n\nThe provider request timeout is 30 seconds. Page large results or use an\nappropriate provider download flow to stay within the response-body limit.\nA timeout can leave the external action's outcome unknown; check that action\nbefore retrying.", "slug": "/api/connected-apps/pipedream-proxy-for-current-user", "method": "POST", "path": "/api/v1/integrations/pipedream/proxy", "requestSchema": "PipedreamProxyForCurrentUserRequest", "responseSchema": "PipedreamProxyForCurrentUserResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "The upstream response, whatever its status", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:createThread", "operationId": "createThread", "bundle": "conversations.yaml", "title": "Create a new conversation thread", "description": "Creates a conversation thread for the authenticated user.", "slug": "/api/conversations/create-thread", "method": "POST", "path": "/api/v1/llm/create-thread", "requestSchema": "CreateThreadRequest", "responseSchema": "CreateThreadResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Thread created successfully", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:listThreads", "operationId": "listThreads", "bundle": "conversations.yaml", "title": "List conversation threads", "description": "Returns a paginated list of conversation threads for the authenticated user,\nordered by `lastMessageAt` descending, then `threadId` descending for ties.\nChanges to `updatedAt` alone do not change the list position.\n\nPass `nextPageToken` as `pageToken` to continue after the last returned\nthread in that order. Pages read the current conversation projection;\nthey do not share a point-in-time snapshot. Concurrent message activity\ncan move a thread ahead of a continuation token, so a multi-page traversal\ncan miss threads that move while it is in progress.", "slug": "/api/conversations/list-threads", "method": "POST", "path": "/api/v1/llm/list-threads", "requestSchema": "ListThreadsRequest", "responseSchema": "ListThreadsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Threads listed successfully", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:sendMessage", "operationId": "sendMessage", "bundle": "conversations.yaml", "title": "Send a message to a conversation", "description": "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.\n\nSee [Messages and run outcomes](/api/conversations/messages-and-runs) for status interpretation and recovery.", "slug": "/api/conversations/send-message", "method": "POST", "path": "/api/v1/llm/send-message", "requestSchema": "SendMessageRequest", "responseSchema": "SendMessageResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Message accepted and generation initiated", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:appendMessage", "operationId": "appendMessage", "bundle": "conversations.yaml", "title": "Append a message without generating", "description": "Appends a context message to the thread's history without starting generation for\nthis call. Use it to record a system note, an external event or other context that\nlater generations should see without triggering a reply.\n\nRead `conversation-state` to confirm the event: append assigns the next monotonic\nsequence immediately and publishes a message event. `ROLE_USER` opens a new user\nturn; other roles join the most recent user turn. Choose the role for how the event\nshould appear in history, without changing the fact it records.\n\nAppend bypasses the interrupt policy and pending queue. It can run while another\nturn is active, but that turn may already have assembled its provider request.\nThis call does not stop already running work or guarantee zero account-level cost:\nstorage and future model input can still cost money.", "slug": "/api/conversations/append-message", "method": "POST", "path": "/api/v1/llm/append-message", "requestSchema": "AppendMessageRequest", "responseSchema": "AppendMessageResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Message appended", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:sendMessageSync", "operationId": "sendMessageSync", "bundle": "conversations.yaml", "title": "Send a message and wait for the result", "description": "Sends a message and waits for a bounded interval, returning generated messages\ninline when available. Use it when you need the assistant reply in the HTTP\nresponse, such as structured output or a classification.\n\nInspect [`status`](/api/conversations/send-message-sync#response-field-status) even\non HTTP 200: a queued message, a pause for client tools or the bounded wait ending\ncan return before the run finishes. A transport timeout or unknown status does\nnot authorize resending the message; reconcile the accepted run.\n\nSee [Messages and run outcomes](/api/conversations/messages-and-runs) for status\ninterpretation and recovery.", "slug": "/api/conversations/send-message-sync", "method": "POST", "path": "/api/v1/llm/send-message-sync", "requestSchema": "SendMessageSyncRequest", "responseSchema": "SendMessageSyncResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Run status returned; generation may still be active or waiting", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:updateSettings", "operationId": "updateSettings", "bundle": "conversations.yaml", "title": "Update conversation settings", "description": "Updates the conversation's behavior settings.", "slug": "/api/conversations/update-settings", "method": "POST", "path": "/api/v1/llm/update-settings", "requestSchema": "UpdateSettingsRequest", "responseSchema": "UpdateSettingsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Settings updated", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:updatePromptVariables", "operationId": "updatePromptVariables", "bundle": "conversations.yaml", "title": "Update prompt variables", "description": "Agent Profiles: merges prompt variables into the thread for late-binding. The variables are re-rendered into the active profile's prompt on the next turn. Returns the merged conversation settings.\n\n### Prompt-variable update masks\n\nWhen you supply [`updateMask`](/api/conversations/update-prompt-variables#request-field-updatemask):\n\n- **Masked keys are authoritative.** A masked key whose value is `null` or absent **clears** that variable.\n- **Unmasked keys are untouched.** Variables not listed in the mask keep their current values, even if you include them in the payload.\n\nWithout [`updateMask`](/api/conversations/update-prompt-variables#request-field-updatemask):\n\n- Supplied keys overwrite or add.\n- Null or empty values clear the variable.\n- Keys you omit are not touched.", "slug": "/api/conversations/update-prompt-variables", "method": "POST", "path": "/api/v1/llm/update-prompt-variables", "requestSchema": "UpdatePromptVariablesRequest", "responseSchema": "UpdatePromptVariablesResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Prompt variables merged", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:updateDefaultGenerationConfig", "operationId": "updateDefaultGenerationConfig", "bundle": "conversations.yaml", "title": "Update default generation config", "description": "Updates the default LLM generation configuration for a conversation. These defaults apply to every subsequent SendMessage unless overridden per-request.", "slug": "/api/conversations/update-default-generation-config", "method": "POST", "path": "/api/v1/llm/update-default-generation-config", "requestSchema": "ConversationUpdateDefaultGenerationConfigRequest", "responseSchema": "ConversationUpdateDefaultGenerationConfigResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Generation config updated", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:updateContextManagementSettings", "operationId": "updateContextManagementSettings", "bundle": "conversations.yaml", "title": "Update context management settings", "description": "Updates how the conversation selects and compacts context for later generations.\n\nSee [Context and compaction](/api/conversations/context-and-compaction) for strategy\nselection and outcome handling.", "slug": "/api/conversations/update-context-management-settings", "method": "POST", "path": "/api/v1/llm/update-context-management-settings", "requestSchema": "UpdateContextManagementSettingsRequest", "responseSchema": "UpdateContextManagementSettingsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Context management settings updated", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:compactConversation", "operationId": "compactConversation", "bundle": "conversations.yaml", "title": "Compact a conversation", "description": "Triggers context compaction, summarizing older conversation messages. The trigger\nestimate can differ from the next request's actual size, especially after changing\nprompts or tools. Leave room below the model limit and handle context-limit errors.\n\nWhen configured for asynchronous compaction, this call returns a pending result\nimmediately. Use the returned `compactionId` to inspect the completed record in\n`conversation-state`'s `compactions` array. Compaction can still delay other messages\nin the conversation; asynchronous acceptance does not guarantee uninterrupted\nconcurrent messaging.\n\nSee [Context and compaction](/api/conversations/context-and-compaction) for strategy\nselection and outcome handling.", "slug": "/api/conversations/compact-conversation", "method": "POST", "path": "/api/v1/llm/compact-conversation", "requestSchema": "CompactConversationRequest", "responseSchema": "CompactConversationResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Compaction completed", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:getConversationState", "operationId": "getConversationState", "bundle": "conversations.yaml", "title": "Get full conversation state", "description": "Returns the complete conversation state. An unknown or non-owned `externalId`\nreturns `404`.\n\nWhen polling, the absence of an active run does not prove that an accepted or\nqueued request completed. Reconcile the original `runId` and its outcome before\nretrying an accepted send.", "slug": "/api/conversations/get-conversation-state", "method": "POST", "path": "/api/v1/llm/conversation-state", "requestSchema": "GetConversationStateRequest", "responseSchema": "GetConversationStateResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Conversation state returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:rateMessage", "operationId": "rateMessage", "bundle": "conversations.yaml", "title": "Rate an assistant message", "description": "Records the caller's rating on an assistant-generated message. One entry is stored\nper rater per message; re-rating replaces only the caller's previous entry.\n\nSerialize re-rating and withdrawal actions and reconcile stored state: uniqueness\ndoes not guarantee ordering against a delayed request or analytics event.", "slug": "/api/conversations/rate-message", "method": "POST", "path": "/api/v1/llm/rate-message", "requestSchema": "RateMessageRequest", "responseSchema": "RateMessageResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Rating recorded", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:deleteMessageRating", "operationId": "deleteMessageRating", "bundle": "conversations.yaml", "title": "Withdraw your rating on a message", "description": "Removes the caller's own rating from a message. As with `rate-message`, the rater\nis derived server-side from the verified request headers.\n\nThis is idempotent: withdrawing a rating that was never left is a success, not an\nerror — the response returns `removed: false` in that case.", "slug": "/api/conversations/delete-message-rating", "method": "POST", "path": "/api/v1/llm/delete-message-rating", "requestSchema": "DeleteMessageRatingRequest", "responseSchema": "DeleteMessageRatingResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Rating withdrawn (or confirmed absent)", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:createDailySession", "operationId": "createDailySession", "bundle": "conversations.yaml", "title": "Create a voice session (in progress)", "description": "Starts the configured hosted-provider voice session for an initialized conversation.\nConfirm room connection and agent readiness through provider events. A returned\nsession alone does not establish that the agent joined or that transcripts were\nstored in conversation history.\n\nAt session end, handle room expiry and the client's local capture separately; a\nlocal disconnect alone does not establish remote cleanup.", "slug": "/api/conversations/create-daily-session", "method": "POST", "path": "/api/v1/llm/create-daily-session", "requestSchema": "CreateDailySessionRequest", "responseSchema": "CreateDailySessionResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Voice session created", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:mintSttToken", "operationId": "mintSttToken", "bundle": "conversations.yaml", "title": "Mint a speech-to-text token (in progress)", "description": "Mints a short-lived speech-to-text token using the configured Cartesia credential.\nThe request fails when that credential is missing. The client uses this token to\ncall the STT API directly so the backend key never reaches the client.", "slug": "/api/conversations/mint-stt-token", "method": "POST", "path": "/api/v1/llm/stt-token", "requestSchema": "MintSttTokenRequest", "responseSchema": "MintSttTokenResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "STT token minted", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:listPendingApprovals", "operationId": "listPendingApprovals", "bundle": "conversations.yaml", "title": "List pending tool approvals", "description": "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.", "slug": "/api/conversations/list-pending-approvals", "method": "POST", "path": "/api/v1/llm/list-pending-approvals", "requestSchema": "ListPendingApprovalsRequest", "responseSchema": "ListPendingApprovalsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Pending approvals listed", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:submitToolApprovals", "operationId": "submitToolApprovals", "bundle": "conversations.yaml", "title": "Approve or reject pending tool calls", "description": "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.", "slug": "/api/conversations/submit-tool-approvals", "method": "POST", "path": "/api/v1/llm/submit-tool-approvals", "requestSchema": "SubmitToolApprovalsRequest", "responseSchema": "SubmitToolApprovalsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Approvals submitted", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:submitClientToolResults", "operationId": "submitClientToolResults", "bundle": "conversations.yaml", "title": "Submit client-side tool execution results", "description": "Submits results for client-side tool calls and returns without waiting for the next\ngeneration segment. While the conversation still identifies a run, workflow\nvalidation rejects unmatched calls with `400` and already-resolved calls with `410`.\n\nIf no active run is recorded, this call can succeed without applying any results.\nReconcile stored run and tool state before treating HTTP success as confirmation\nthat the results were applied.\n\nA run can request further batches. Read pending client tools, execute each new\nbatch and submit its results until the run reaches a terminal outcome. An unknown\nstatus requires reconciliation with a bounded wait, not an assumption of success.\nSee [Messages and run outcomes](/api/conversations/messages-and-runs) for outcome\nhandling and the synchronous client-tool loop.", "slug": "/api/conversations/submit-client-tool-results", "method": "POST", "path": "/api/v1/llm/submit-client-tool-results", "requestSchema": "SubmitClientToolResultsRequest", "responseSchema": "SubmitClientToolResultsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Client tool results submitted", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:submitClientToolResultsSync", "operationId": "submitClientToolResultsSync", "bundle": "conversations.yaml", "title": "Submit client-side tool results and wait for the next segment", "description": "Submits client-side tool results and waits until the run arms another client-tool\nbatch or finishes. This continues the loop started by `send-message-sync`. While\nthe conversation still identifies a run, workflow validation rejects unmatched\ncalls with `400` and already-resolved calls with `410`.\n\nIf no active run is recorded, this call can return success immediately without\napplying any results. Reconcile stored run and tool state before treating HTTP\nsuccess as confirmation that the results were applied.\n\nEcho the `clientToolCursor` from the response that armed the calls. A stale cursor\nre-delivers a batch rather than skipping one. When another batch arrives, execute\nit and submit again with its new cursor until the run reaches a terminal outcome.\nReconcile an unknown status with a bounded wait; do not assume success.\n\nAn empty `results` array returns `400`: submitting nothing resolves nothing. Use\n`list-pending-client-tools` to inspect pending work or recover after a dropped\nconnection. Do not resend the original user message, which would start another run.\nUse `submit-client-tool-results` when you do not want to hold the connection.\n\nSee [Messages and run outcomes](/api/conversations/messages-and-runs) for status\ninterpretation and recovery.", "slug": "/api/conversations/submit-client-tool-results-sync", "method": "POST", "path": "/api/v1/llm/submit-client-tool-results-sync", "requestSchema": "SubmitClientToolResultsSyncRequest", "responseSchema": "SubmitClientToolResultsSyncResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Run status and available messages or pending client tools returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:listPendingClientTools", "operationId": "listPendingClientTools", "bundle": "conversations.yaml", "title": "List client-side tool calls awaiting a result", "description": "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.\n\nOn 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.", "slug": "/api/conversations/list-pending-client-tools", "method": "POST", "path": "/api/v1/llm/list-pending-client-tools", "requestSchema": "ListPendingClientToolsRequest", "responseSchema": "ListPendingClientToolsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Outstanding client-side tool calls", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:getToolCall", "operationId": "getToolCall", "bundle": "conversations.yaml", "title": "Get a single tool call by ID", "description": "Reads the identified tool call from the conversation's current run state, including\nresolved calls retained there. An empty response means the call was not found in\nthat current run; it does not prove the call never executed.\n\nMatch the call ID and inspect both status and result. If its answer window expired,\nthe result reports `client tool timeout`. Inspect both the status and reason\nbefore deciding whether any work remains; expiration does not establish whether\nan action dispatched to the client took effect.", "slug": "/api/conversations/get-tool-call", "method": "POST", "path": "/api/v1/llm/get-tool-call", "requestSchema": "GetToolCallRequest", "responseSchema": "GetToolCallResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "The tool call", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:mcpListAvailableServers", "operationId": "mcpListAvailableServers", "bundle": "conversations.yaml", "title": "List available MCP servers", "description": "Returns the discovered availability of configured MCP servers.\n\n### Built-in catalog entries\n\nThe 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.", "slug": "/api/conversations/mcp-list-available-servers", "method": "POST", "path": "/api/v1/llm/mcp-list-available-servers", "requestSchema": "MCPListAvailableServersRequest", "responseSchema": "MCPListAvailableServersResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Server list returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:mcpGetServerInfo", "operationId": "mcpGetServerInfo", "bundle": "conversations.yaml", "title": "Get detailed MCP server info", "description": "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.", "slug": "/api/conversations/mcp-get-server-info", "method": "POST", "path": "/api/v1/llm/mcp-get-server-info", "requestSchema": "MCPGetServerInfoRequest", "responseSchema": "MCPGetServerInfoResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Server info returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:mcpListTools", "operationId": "mcpListTools", "bundle": "conversations.yaml", "title": "List available MCP tools", "description": "Returns tools discovered across the selected MCP servers.", "slug": "/api/conversations/mcp-list-tools", "method": "POST", "path": "/api/v1/llm/mcp-list-tools", "requestSchema": "MCPListToolsRequest", "responseSchema": "MCPListToolsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Tools listed", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:mcpCallTool", "operationId": "mcpCallTool", "bundle": "conversations.yaml", "title": "Execute an MCP tool", "description": "Invokes an MCP tool directly, outside a conversation flow. Use it to test a tool\nwithout starting a generation run.", "slug": "/api/conversations/mcp-call-tool", "method": "POST", "path": "/api/v1/llm/mcp-call-tool", "requestSchema": "MCPCallToolRequest", "responseSchema": "MCPCallToolResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Tool executed", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:mcpListResources", "operationId": "mcpListResources", "bundle": "conversations.yaml", "title": "List MCP resources", "description": "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.", "slug": "/api/conversations/mcp-list-resources", "method": "POST", "path": "/api/v1/llm/mcp-list-resources", "requestSchema": "MCPListResourcesRequest", "responseSchema": "MCPListResourcesResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Empty response; resource listing is not yet available", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:mcpReadResource", "operationId": "mcpReadResource", "bundle": "conversations.yaml", "title": "Read an MCP resource", "description": "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.", "slug": "/api/conversations/mcp-read-resource", "method": "POST", "path": "/api/v1/llm/mcp-read-resource", "requestSchema": "MCPReadResourceRequest", "responseSchema": "MCPReadResourceResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Empty response; resource retrieval is not yet available", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:mcpListPrompts", "operationId": "mcpListPrompts", "bundle": "conversations.yaml", "title": "List MCP prompt templates", "description": "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.", "slug": "/api/conversations/mcp-list-prompts", "method": "POST", "path": "/api/v1/llm/mcp-list-prompts", "requestSchema": "MCPListPromptsRequest", "responseSchema": "MCPListPromptsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Empty response; prompt listing is not yet available", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:mcpGetPrompt", "operationId": "mcpGetPrompt", "bundle": "conversations.yaml", "title": "Get an MCP prompt template", "description": "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.", "slug": "/api/conversations/mcp-get-prompt", "method": "POST", "path": "/api/v1/llm/mcp-get-prompt", "requestSchema": "MCPGetPromptRequest", "responseSchema": "MCPGetPromptResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Empty response; prompt retrieval is not yet available", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:searchMemories", "operationId": "searchMemories", "bundle": "conversations.yaml", "title": "Semantic search over memories", "description": "Searches memories by meaning within the authenticated user's tenant scope. Results\nand relationships depend on the configured provider. An empty result can represent\na handled provider failure and does not prove that no memories exist. Search does\nnot provide pagination or a complete inventory.\n\nUse an authorized backend key with X-On-Behalf-Of and users:impersonate scope, or a\npublishable key with a user JWT. A configured user JWT can also authenticate\ndirectly. An effective user and tenant are required; raw identity headers do not\ngrant authority. See the [memory cookbook](/managed-agents/memory-knowledge).", "slug": "/api/conversations/search-memories", "method": "POST", "path": "/api/v1/llm/search-memories", "requestSchema": "SearchMemoriesRequest", "responseSchema": "SearchMemoriesResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Search results returned", "requestBodyRequired": true, "errors": { "400": { "description": "Invalid decoded request, including omitted topK or values outside their bounds, or missing tenant context." }, "401": { "description": "Missing or invalid authentication, or no effective user." }, "403": { "description": "Insufficient impersonation scope or required tenant membership." }, "500": { "description": "Unexpected server failure." }, "502": { "description": "Authentication upstream returned an unreadable or invalid response." }, "503": { "description": "Authentication service unavailable." }, "default": { "description": "Other failures may be forwarded from upstream. Error bodies vary by origin; this slice does not assert a single error envelope." } }, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:listMemories", "operationId": "listMemories", "bundle": "conversations.yaml", "title": "List user memories", "description": "Returns memories in the effective user's scope. This operation has no pagination\ncursor or category filter. A capped response does not prove that the user has seen\nevery stored record or provide a complete all-records traversal guarantee.", "slug": "/api/conversations/list-memories", "method": "POST", "path": "/api/v1/llm/list-memories", "requestSchema": "ListMemoriesRequest", "responseSchema": "ListMemoriesResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Memories listed", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:getMemory", "operationId": "getMemory", "bundle": "conversations.yaml", "title": "Get a specific memory", "description": "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.", "slug": "/api/conversations/get-memory", "method": "POST", "path": "/api/v1/llm/get-memory", "requestSchema": "GetMemoryRequest", "responseSchema": "GetMemoryResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Memory returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:updateMemory", "operationId": "updateMemory", "bundle": "conversations.yaml", "title": "Update a memory", "description": "Updates a memory by ID. Full project/user ownership checks are not currently enforced for these by-ID operations. They are not a supported access boundary for an untrusted end-user client. See [Memory](/managed-agents/memory-knowledge) for the current limits.", "slug": "/api/conversations/update-memory", "method": "POST", "path": "/api/v1/llm/update-memory", "requestSchema": "UpdateMemoryRequest", "responseSchema": "UpdateMemoryResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Memory updated", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "conversations:deleteMemory", "operationId": "deleteMemory", "bundle": "conversations.yaml", "title": "Delete a memory", "description": "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).", "slug": "/api/conversations/delete-memory", "method": "POST", "path": "/api/v1/llm/delete-memory", "requestSchema": "DeleteMemoryRequest", "responseSchema": "DeleteMemoryResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Memory deleted", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "end-users:getEndUser", "operationId": "getEndUser", "bundle": "end-users.yaml", "title": "Get the caller's end-user profile", "description": "Returns the caller's full end-user record — identity claims sourced from the\nidentity provider, profile settings the user has set, and lifecycle timestamps.\n\n:::note A user with no profile is not a 404\nIf no row exists yet, the call still succeeds and returns an empty [`endUser`](/api/end-users/get-end-user#response-field-enduser) object.\nTreat \"no profile yet\" and \"profile with no overrides\" identically — do not branch on the\ndifference when choosing settings. Treat the missing profile as an absent record;\ndefault-valued fields alone do not prove that an account exists or that deletion\ncompleted.\n:::", "slug": "/api/end-users/get-end-user", "method": "POST", "path": "/api/v1/enduser/get", "requestSchema": "GetEndUserRequest", "responseSchema": "GetEndUserResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Profile returned (possibly empty if no row exists yet)", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "end-users:updateLocation", "operationId": "updateLocation", "bundle": "end-users.yaml", "title": "Update the caller's location", "description": "Sets the caller's coordinates. The IANA timezone is **derived server-side** from\nthe coordinates and returned on the response — do not send a timezone.\n\nCoordinates (0, 0) are a real location, not a deletion command. This operation does not offer a location-clear control.", "slug": "/api/end-users/update-location", "method": "POST", "path": "/api/v1/enduser/update-location", "requestSchema": "UpdateLocationRequest", "responseSchema": "UpdateLocationResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Location updated; response carries the derived timezone", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "end-users:updateLocale", "operationId": "updateLocale", "bundle": "end-users.yaml", "title": "Update the caller's locale override", "description": "Sets a BCP-47 locale override for the caller, e.g. `es-MX`. This overrides the\nlocale supplied by the identity provider.\n\nSend an **empty string** to clear the override and fall back to the\nidentity-provider locale.", "slug": "/api/end-users/update-locale", "method": "POST", "path": "/api/v1/enduser/update-locale", "requestSchema": "UpdateLocaleRequest", "responseSchema": "UpdateLocaleResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Locale override updated", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "end-users:updateDefaultGenerationConfig", "operationId": "updateDefaultGenerationConfig", "bundle": "end-users.yaml", "title": "Update the caller's default generation config", "description": "Stores the caller's generation preferences. The generation path fills fields\nleft unset by the selected per-send, profile or conversation configuration;\nalready set values remain unchanged. Explicitly present sampling values,\nincluding zero, preserve their presence. Model/provider support determines\nwhich accepted controls affect a response.\n\nOnly user-settable controls are accepted. A recognized operational setting or a\nmodel outside the platform allowlist fails the whole request; settings are not\nsilently removed to make a config acceptable. Read the saved profile after an\nupdate rather than assuming every submitted setting took effect.", "slug": "/api/end-users/update-default-generation-config", "method": "POST", "path": "/api/v1/enduser/update-generation-config", "requestSchema": "EndUserUpdateDefaultGenerationConfigRequest", "responseSchema": "EndUserUpdateDefaultGenerationConfigResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Default generation config updated", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "end-users:updateMetadata", "operationId": "updateMetadata", "bundle": "end-users.yaml", "title": "Update the caller's metadata", "description": "Merges the supplied key/value pairs into the caller's metadata map.\n\nThis is a **merge, not a replace**: keys you omit are left untouched. To delete a key,\nsend it with an empty-string value. Example:\n\nBefore:\n```json\n{\"preferredView\": \"expanded\", \"dismissedWelcome\": \"true\", \"referralCode\": \"SPRING24\"}\n```\n\nAfter calling `update-metadata` with `{\"preferredView\": \"compact\", \"dismissedWelcome\": \"\"}`:\n```json\n{\"preferredView\": \"compact\", \"referralCode\": \"SPRING24\"}\n```\n\n`preferredView` is overwritten, `dismissedWelcome` is deleted (empty string), and `referralCode`\nis untouched.", "slug": "/api/end-users/update-metadata", "method": "POST", "path": "/api/v1/enduser/update-metadata", "requestSchema": "UpdateMetadataRequest", "responseSchema": "UpdateMetadataResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Metadata merged", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "evals:addDatasetItem", "operationId": "addDatasetItem", "bundle": "evals.yaml", "title": "Add a dataset item", "description": "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.\n\n### Dataset input capture and identity\n\n| Input or identity | Contract |\n|---|---|\n| Dataset item address | Derived from the dataset and source turn. Adding the same turn to different datasets produces different items. |\n| [`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. |\n| 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. |\n\nCapture and curate source material explicitly, including redaction, omitted fields and the provenance of tool or memory fixtures.", "slug": "/api/evals/add-dataset-item", "method": "POST", "path": "/api/v1/evals/add-dataset-item", "requestSchema": "AddDatasetItemRequest", "responseSchema": "AddDatasetItemResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:completeAnnotationQueueItem", "operationId": "completeAnnotationQueueItem", "bundle": "evals.yaml", "title": "Complete an annotation queue item", "description": "Marks an annotation queue item completed. The immediate response can contain\n[`completedBy`](/api/models/annotation-queue-item#response-field-completedby), but\nthe current API does not persist that attribution for later list reads. Do not use\nthis response alone as a durable reviewer audit record.", "slug": "/api/evals/complete-annotation-queue-item", "method": "POST", "path": "/api/v1/evals/complete-annotation-queue-item", "requestSchema": "CompleteAnnotationQueueItemRequest", "responseSchema": "CompleteAnnotationQueueItemResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:createAnnotationQueue", "operationId": "createAnnotationQueue", "bundle": "evals.yaml", "title": "Create an annotation queue", "description": "Creates a review queue bound to a set of score configs — the scales reviewers will use on it.", "slug": "/api/evals/create-annotation-queue", "method": "POST", "path": "/api/v1/evals/create-annotation-queue", "requestSchema": "CreateAnnotationQueueRequest", "responseSchema": "CreateAnnotationQueueResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:createComment", "operationId": "createComment", "bundle": "evals.yaml", "title": "Create a comment", "description": "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.", "slug": "/api/evals/create-comment", "method": "POST", "path": "/api/v1/evals/create-comment", "requestSchema": "CreateCommentRequest", "responseSchema": "CreateCommentResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:createDataset", "operationId": "createDataset", "bundle": "evals.yaml", "title": "Create a dataset", "description": "Creates an evaluation dataset.", "slug": "/api/evals/create-dataset", "method": "POST", "path": "/api/v1/evals/create-dataset", "requestSchema": "CreateDatasetRequest", "responseSchema": "CreateDatasetResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:createScoreConfig", "operationId": "createScoreConfig", "bundle": "evals.yaml", "title": "Create a score config", "description": "Creates a rating scale that gives scores a consistent interpretation across turns.", "slug": "/api/evals/create-score-config", "method": "POST", "path": "/api/v1/evals/create-score-config", "requestSchema": "CreateScoreConfigRequest", "responseSchema": "CreateScoreConfigResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:deleteComment", "operationId": "deleteComment", "bundle": "evals.yaml", "title": "Delete a comment", "description": "Deletes one comment by id.", "slug": "/api/evals/delete-comment", "method": "POST", "path": "/api/v1/evals/delete-comment", "requestSchema": "DeleteCommentRequest", "responseSchema": "DeleteCommentResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:deleteScore", "operationId": "deleteScore", "bundle": "evals.yaml", "title": "Delete a score", "description": "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.\n\nObtain 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.", "slug": "/api/evals/delete-score", "method": "POST", "path": "/api/v1/evals/delete-score", "requestSchema": "DeleteScoreRequest", "responseSchema": "DeleteScoreResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:enqueueForAnnotation", "operationId": "enqueueForAnnotation", "bundle": "evals.yaml", "title": "Enqueue an item for annotation", "description": "Adds a trace, observation or session to a review queue.", "slug": "/api/evals/enqueue-for-annotation", "method": "POST", "path": "/api/v1/evals/enqueue-for-annotation", "requestSchema": "EnqueueForAnnotationRequest", "responseSchema": "EnqueueForAnnotationResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:getDatasetRun", "operationId": "getDatasetRun", "bundle": "evals.yaml", "title": "Get a dataset run", "description": "Fetches run metadata by dataset name and run name. It does not return per-item results.", "slug": "/api/evals/get-dataset-run", "method": "POST", "path": "/api/v1/evals/get-dataset-run", "requestSchema": "GetDatasetRunRequest", "responseSchema": "GetDatasetRunResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:getOverview", "operationId": "getOverview", "bundle": "evals.yaml", "title": "Get the eval overview", "description": "Aggregate trace counts, score averages and totals for a time window — the numbers behind a dashboard.\n\nCoverage 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.\n\n### Overview populations and configuration identity\n\nInterpret quality alongside a fixed dataset's eligible, evaluated, failed and excluded cases; sampled coverage is not the proportion of every turn reviewed.\n\nSave the full configuration in the [regression workflow](/insights/evaluation/datasets-and-runs#4-record-the-run) before attributing a difference to one change.", "slug": "/api/evals/get-overview", "method": "POST", "path": "/api/v1/evals/get-overview", "requestSchema": "GetOverviewRequest", "responseSchema": "GetOverviewResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:getSession", "operationId": "getSession", "bundle": "evals.yaml", "title": "Get a session", "description": "Fetch one session and the traces belonging to it.\n\n### Session summaries\n\nSession 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.", "slug": "/api/evals/get-session", "method": "POST", "path": "/api/v1/evals/get-session", "requestSchema": "GetSessionRequest", "responseSchema": "GetSessionResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:getTrace", "operationId": "getTrace", "bundle": "evals.yaml", "title": "Get a trace", "description": "Fetch one trace with its observations expanded.\n\nWhen addressing a turn, `conversationId` accepts a bare thread id and is\nqualified with your verified tenant. The assistant message or rating event\ncarries the source user-message identity needed to find that turn.\n\nObservation/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.", "slug": "/api/evals/get-trace", "method": "POST", "path": "/api/v1/evals/get-trace", "requestSchema": "GetTraceRequest", "responseSchema": "GetTraceResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:listAnnotationQueueItems", "operationId": "listAnnotationQueueItems", "bundle": "evals.yaml", "title": "List annotation queue items", "description": "Lists annotation queue items.\n\n### Reading an item\n\nFor 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.", "slug": "/api/evals/list-annotation-queue-items", "method": "POST", "path": "/api/v1/evals/list-annotation-queue-items", "requestSchema": "ListAnnotationQueueItemsRequest", "responseSchema": "ListAnnotationQueueItemsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:listAnnotationQueues", "operationId": "listAnnotationQueues", "bundle": "evals.yaml", "title": "List annotation queues", "description": "Lists the review queues defined for this tenant.", "slug": "/api/evals/list-annotation-queues", "method": "POST", "path": "/api/v1/evals/list-annotation-queues", "requestSchema": "ListAnnotationQueuesRequest", "responseSchema": "ListAnnotationQueuesResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:listComments", "operationId": "listComments", "bundle": "evals.yaml", "title": "List comments", "description": "Lists the comments on one object.", "slug": "/api/evals/list-comments", "method": "POST", "path": "/api/v1/evals/list-comments", "requestSchema": "ListCommentsRequest", "responseSchema": "ListCommentsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:listDatasetItems", "operationId": "listDatasetItems", "bundle": "evals.yaml", "title": "List dataset items", "description": "Lists items in a dataset.", "slug": "/api/evals/list-dataset-items", "method": "POST", "path": "/api/v1/evals/list-dataset-items", "requestSchema": "ListDatasetItemsRequest", "responseSchema": "ListDatasetItemsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:listDatasetRuns", "operationId": "listDatasetRuns", "bundle": "evals.yaml", "title": "List dataset runs", "description": "Lists past runs against a dataset.\n\nUses 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.", "slug": "/api/evals/list-dataset-runs", "method": "POST", "path": "/api/v1/evals/list-dataset-runs", "requestSchema": "ListDatasetRunsRequest", "responseSchema": "ListDatasetRunsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:listDatasets", "operationId": "listDatasets", "bundle": "evals.yaml", "title": "List datasets", "description": "Lists the evaluation datasets defined for this tenant.", "slug": "/api/evals/list-datasets", "method": "POST", "path": "/api/v1/evals/list-datasets", "requestSchema": "ListDatasetsRequest", "responseSchema": "ListDatasetsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:listObservations", "operationId": "listObservations", "bundle": "evals.yaml", "title": "List observations", "description": "Lists the individual spans, generations and events inside traces.", "slug": "/api/evals/list-observations", "method": "POST", "path": "/api/v1/evals/list-observations", "requestSchema": "ListObservationsRequest", "responseSchema": "ListObservationsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:listScoreConfigs", "operationId": "listScoreConfigs", "bundle": "evals.yaml", "title": "List score configs", "description": "Lists the rating scales defined for this tenant.\n\nUse this list to select a compatible scale before recording a score. Archived\nconfigs remain readable for historical interpretation but are not offered for new ratings.", "slug": "/api/evals/list-score-configs", "method": "POST", "path": "/api/v1/evals/list-score-configs", "requestSchema": "ListScoreConfigsRequest", "responseSchema": "ListScoreConfigsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:listScores", "operationId": "listScores", "bundle": "evals.yaml", "title": "List scores", "description": "Lists recorded scores across their sources and evaluation targets.\n\n### Filtering by what the rating is about\n\n`conversationId` and `profileId` answer \"every rating on this conversation\" and\n\"every rating on turns this agent profile produced\". Each is decided per score —\non the score's own metadata, or on the trace it scores when the metadata does\nnot say — and combining them is an intersection. `conversationId` accepts a bare\nthread id and qualifies it with your verified tenant.\n\n### Reading the result honestly\n\n**`filterNarrowed`** matters when you paginate. Some filters cannot be applied by\nthe underlying store, so rows are removed after they are fetched: `conversationId`,\n`profileId`, `userId`, the platform `source` values the store does not distinguish,\nand the rows of the `filters` array. The response sets `filterNarrowed: true`\nonly when at least one row was removed from the pages fetched for this response.\nIt can remain false or be omitted even when these filters were evaluated. A page\nmay be shorter than `pageSize` or empty while `cursorPage.nextCursor` still leads\nto more matches — keep following the cursor until it is omitted rather than\nstopping at a short page. A false or omitted flag is not a complete-history or\nconsistent-snapshot guarantee. There is no total.\n\nDeduplicate IDs across pages when collecting a report.\n\n### Score filters and result coverage\n\nCurrent 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.", "slug": "/api/evals/list-scores", "method": "POST", "path": "/api/v1/evals/list-scores", "requestSchema": "ListScoresRequest", "responseSchema": "ListScoresResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:listSessions", "operationId": "listSessions", "bundle": "evals.yaml", "title": "List sessions", "description": "Lists sessions for the authenticated tenant.\n\nThe `filters` array accepts the session columns `id` (the session id), `userIds`,\n`traceTags`, `createdAt`, `environment` and `metadata`. Columns aggregated over a\nsession — duration, trace count, tokens, scores, comments — cannot be filtered and\nare rejected with HTTP 400. There is no free-text search.\n\nReads 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.", "slug": "/api/evals/list-sessions", "method": "POST", "path": "/api/v1/evals/list-sessions", "requestSchema": "ListSessionsRequest", "responseSchema": "ListSessionsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:listTraces", "operationId": "listTraces", "bundle": "evals.yaml", "title": "List traces", "description": "Lists traces for the authenticated tenant, newest first — the only ordering, so an\n`orderBy` other than `timestamp.desc` is rejected with HTTP 400. One trace is one\nconversation turn.\n\n### Filtering by entity\n\n`conversationId`, `profileId`, `userId` and `sessionId` are applied at the source,\nnot over the returned page. Repeated entity filters intersect: `conversationId` +\n`profileId` returns turns in that conversation produced by that profile, not the\nunion.\n\n`cursorPage.totalItems` is the only total any cursor-paged operation returns, and\nit is omitted whenever a profile, config-hash or level filter is set — that total\ncannot be counted exactly — or the count is unavailable.\n\n`conversationId` accepts the bare thread id — it is qualified with your verified\ntenant server-side, so an id held by a product surface works without the caller\nreconstructing the tenant-prefixed form.\n\nThe `filters` array is the general filter-builder vocabulary. Entity columns there\n(`conversationId`, `profileId`, `configHash`, `sourceUserMessageId`) accept an exact\n`=` match or `any of` a set. A `level` row matches traces with at least one\nobservation at that level. Latency, token and cost columns are aggregates over a\ntrace and cannot be filtered here (use `list-observations`). A filter row the\nunderlying store cannot express — an inexact operator on an entity column, an\naggregate column, or an unsupported column — is rejected with HTTP 400 rather than\napplied to the returned page.\n\nHistorical 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.\n\n### Trace query support\n\nA 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.\n\nFor 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.", "slug": "/api/evals/list-traces", "method": "POST", "path": "/api/v1/evals/list-traces", "requestSchema": "ListTracesRequest", "responseSchema": "ListTracesResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:recordDatasetRun", "operationId": "recordDatasetRun", "bundle": "evals.yaml", "title": "Record a dataset run", "description": "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.\n\nThis 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.", "slug": "/api/evals/record-dataset-run", "method": "POST", "path": "/api/v1/evals/record-dataset-run", "requestSchema": "RecordDatasetRunRequest", "responseSchema": "RecordDatasetRunResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:recordScore", "operationId": "recordScore", "bundle": "evals.yaml", "title": "Record a score", "description": "Records a tenant-side reviewer/operator score.\n\n### Resolving the rated turn\n\nTurn 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.\n\nThe 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.\n\n### Supported ratings\n\nUse 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.\n\n### Examples\n\n```json\n{\n \"targetType\": \"EVAL_TARGET_TYPE_TRACE\",\n \"targetId\": \"\",\n \"name\": \"helpfulness\",\n \"dataType\": \"SCORE_DATA_TYPE_NUMERIC\",\n \"numericValue\": 4,\n \"configId\": \"\"\n}\n```\n\n### Re-rating and withdrawing\n\nA 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.", "slug": "/api/evals/record-score", "method": "POST", "path": "/api/v1/evals/record-score", "requestSchema": "RecordScoreRequest", "responseSchema": "RecordScoreResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:updateDatasetItem", "operationId": "updateDatasetItem", "bundle": "evals.yaml", "title": "Update a dataset item", "description": "Edits an item — typically to fill in `expectedOutputJson` after review.", "slug": "/api/evals/update-dataset-item", "method": "POST", "path": "/api/v1/evals/update-dataset-item", "requestSchema": "UpdateDatasetItemRequest", "responseSchema": "UpdateDatasetItemResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "evals:updateScoreConfig", "operationId": "updateScoreConfig", "bundle": "evals.yaml", "title": "Update a score config", "description": "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\".", "slug": "/api/evals/update-score-config", "method": "POST", "path": "/api/v1/evals/update-score-config", "requestSchema": "UpdateScoreConfigRequest", "responseSchema": "UpdateScoreConfigResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "mcp-servers:createCustomMcpServer", "operationId": "createCustomMcpServer", "bundle": "mcp-servers.yaml", "title": "Register a custom MCP server", "description": "Registers an HTTP MCP server in the caller's project. A duplicate server ID fails\nwith `409`; use [update](/api/mcp-servers/update-custom-mcp-server) to replace the\nrecord.\n\nConfiguration validation and the egress guard run before storage. Invalid\nconfiguration, a referenced secret absent from this project, or an attempt to\ncreate at the configured project limit (20 servers by default) returns `400`.\nConcurrent creates can exceed this count-before-create limit. Secret existence\nis checked at write time so a missing credential is reported before the first\ntool call. Endpoint restrictions also apply when connecting; an HTTPS URL alone\ndoes not establish a safe destination.", "slug": "/api/mcp-servers/create-custom-mcp-server", "method": "POST", "path": "/api/v1/mcp-servers/create", "requestSchema": "CreateCustomMCPServerRequest", "responseSchema": "CreateCustomMCPServerResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Server registered; the stored record is echoed back", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "mcp-servers:getCustomMcpServer", "operationId": "getCustomMcpServer", "bundle": "mcp-servers.yaml", "title": "Get a custom MCP server", "description": "Returns one server record, including disabled ones. An unknown server ID returns\n`404`. The response does not expose the referenced credential's value.", "slug": "/api/mcp-servers/get-custom-mcp-server", "method": "POST", "path": "/api/v1/mcp-servers/get", "requestSchema": "GetCustomMCPServerRequest", "responseSchema": "GetCustomMCPServerResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Server returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "mcp-servers:listCustomMcpServers", "operationId": "listCustomMcpServers", "bundle": "mcp-servers.yaml", "title": "List custom MCP servers", "description": "Returns the project's matching custom servers without pagination. Use the secret\nname filter to inspect dependencies before rotating or deleting a credential.", "slug": "/api/mcp-servers/list-custom-mcp-servers", "method": "POST", "path": "/api/v1/mcp-servers/list", "requestSchema": "ListCustomMCPServersRequest", "responseSchema": "ListCustomMCPServersResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "The project's servers", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "mcp-servers:updateCustomMcpServer", "operationId": "updateCustomMcpServer", "bundle": "mcp-servers.yaml", "title": "Update a custom MCP server", "description": "Replaces the mutable server configuration and increments its version. Read the\nsaved record, edit the intended fields and submit the complete desired server:\nomitting [`enabled`](/api/models/custom-mcp-server#request-field-enabled) disables it,\nand omitted optional fields are cleared. The top-level `serverId` selects the\nrecord; an update cannot rename it. There is no revision precondition, so concurrent\nstale updates can overwrite one another.\n\nA saved update does not confirm that every subsequent call has switched to the\nnew configuration, and it does not cancel in-flight calls. Use `get` to inspect the\nsaved record and `test-connection` to check a connection using it. The same\nvalidation as create applies; an unknown server returns `404`.", "slug": "/api/mcp-servers/update-custom-mcp-server", "method": "POST", "path": "/api/v1/mcp-servers/update", "requestSchema": "UpdateCustomMCPServerRequest", "responseSchema": "UpdateCustomMCPServerResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Server updated; the stored record is echoed back", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "mcp-servers:deleteCustomMcpServer", "operationId": "deleteCustomMcpServer", "bundle": "mcp-servers.yaml", "title": "Delete a custom MCP server", "description": "Removes the server record. Deleting an absent server succeeds with `deleted: false`.\nConversations and profiles retain references to the deleted ID, so remove those\nreferences separately. New resolution fails once deletion is observed; in-flight\ncalls and previously loaded definitions are not recalled. The referenced secret\nis left in place.\n\nTo retain the configuration while disabling the server, set `enabled: false`\nthrough [update](/api/mcp-servers/update-custom-mcp-server).", "slug": "/api/mcp-servers/delete-custom-mcp-server", "method": "POST", "path": "/api/v1/mcp-servers/delete", "requestSchema": "DeleteCustomMCPServerRequest", "responseSchema": "DeleteCustomMCPServerResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Delete processed", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "mcp-servers:testCustomMcpServerConnection", "operationId": "testCustomMcpServerConnection", "bundle": "mcp-servers.yaml", "title": "Test a custom MCP server connection", "description": "Reads a stored configuration snapshot, performs the MCP handshake/tool listing and\nreturns the observed count and latency. A concurrent update can change the record\nafter that read. This operation reads the stored definition directly, making it\nuseful after a configuration change.\n\nCheck [`success`](/api/mcp-servers/test-custom-mcp-server-connection#response-field-success)\nis `true`; a connection failure can return HTTP 200 with `success` false or omitted\nand an error. Inspect the error and repair the endpoint, authentication or network\naccess before retrying. Authentication, validation, rate limiting and infrastructure\nfailures can also return non-success HTTP responses.\n\nTests are limited to 10 per minute per project; destination restrictions apply\nwhen connecting. Rate limiting does not replace network isolation or authorization.\nA successful test is a point-in-time connection check, not a guarantee that every\nadvertised tool is safe or available.", "slug": "/api/mcp-servers/test-custom-mcp-server-connection", "method": "POST", "path": "/api/v1/mcp-servers/test-connection", "requestSchema": "TestCustomMCPServerConnectionRequest", "responseSchema": "TestCustomMCPServerConnectionResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "The test ran; read `success` for the outcome", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "notifications:registerPushDevice", "operationId": "registerPushDevice", "bundle": "notifications.yaml", "title": "Register a push notification device", "description": "Registers an FCM device token for push notifications. Associates the token with the user's subscriber profile.", "slug": "/api/notifications/register-push-device", "method": "POST", "path": "/api/v1/notifications/register-push-device", "requestSchema": "RegisterPushDeviceRequest", "responseSchema": "RegisterPushDeviceResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Device registered successfully", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:unregisterPushDevice", "operationId": "unregisterPushDevice", "bundle": "notifications.yaml", "title": "Unregister a push notification device", "description": "Removes an FCM device token from the user's subscriber profile.", "slug": "/api/notifications/unregister-push-device", "method": "POST", "path": "/api/v1/notifications/unregister-push-device", "requestSchema": "UnregisterPushDeviceRequest", "responseSchema": "UnregisterPushDeviceResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Device unregistered successfully", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:getRegisteredChannels", "operationId": "getRegisteredChannels", "bundle": "notifications.yaml", "title": "Get registered notification channels", "description": "Returns the list of notification channels and their registration status for the authenticated user.", "slug": "/api/notifications/get-registered-channels", "method": "POST", "path": "/api/v1/notifications/get-registered-channels", "requestSchema": "GetRegisteredChannelsRequest", "responseSchema": "GetRegisteredChannelsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Channels retrieved successfully", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:getInboxSession", "operationId": "getInboxSession", "bundle": "notifications.yaml", "title": "Get an inbox session token", "description": "Returns a session token and connection URLs for the real-time in-app inbox. The token is short-lived and should be refreshed before expiry.", "slug": "/api/notifications/get-inbox-session", "method": "POST", "path": "/api/v1/notifications/get-inbox-session", "requestSchema": "GetInboxSessionRequest", "responseSchema": "GetInboxSessionResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Inbox session created successfully", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:getInboxFeed", "operationId": "getInboxFeed", "bundle": "notifications.yaml", "title": "Get inbox feed messages", "description": "Returns a paginated list of in-app inbox messages for the authenticated user,\napplying the supplied selection criteria.", "slug": "/api/notifications/get-inbox-feed", "method": "POST", "path": "/api/v1/notifications/get-inbox-feed", "requestSchema": "GetInboxFeedRequest", "responseSchema": "GetInboxFeedResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Inbox feed retrieved successfully", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:getInboxUnseenCount", "operationId": "getInboxUnseenCount", "bundle": "notifications.yaml", "title": "Get unseen and unread inbox counts", "description": "Returns the number of unseen and unread messages in the user's inbox, optionally filtered by feed IDs.\n\nCounts are capped. Inspect the overflow flags before treating them as exact totals.", "slug": "/api/notifications/get-inbox-unseen-count", "method": "POST", "path": "/api/v1/notifications/get-inbox-unseen-count", "requestSchema": "GetInboxUnseenCountRequest", "responseSchema": "GetInboxUnseenCountResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Counts retrieved successfully", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:markInboxMessageAs", "operationId": "markInboxMessageAs", "bundle": "notifications.yaml", "title": "Mark a single inbox message", "description": "Marks a specific inbox message as seen, read, unseen, or unread.", "slug": "/api/notifications/mark-inbox-message-as", "method": "POST", "path": "/api/v1/notifications/mark-inbox-message", "requestSchema": "MarkInboxMessageAsRequest", "responseSchema": "MarkInboxMessageAsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Message marked successfully", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:markAllInboxMessagesAs", "operationId": "markAllInboxMessagesAs", "bundle": "notifications.yaml", "title": "Mark all inbox messages", "description": "Marks all inbox messages as seen, read, unseen, or unread. Optionally scoped to specific feed IDs.", "slug": "/api/notifications/mark-all-inbox-messages-as", "method": "POST", "path": "/api/v1/notifications/mark-all-inbox-messages", "requestSchema": "MarkAllInboxMessagesAsRequest", "responseSchema": "MarkAllInboxMessagesAsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Messages marked successfully", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:deleteInboxMessage", "operationId": "deleteInboxMessage", "bundle": "notifications.yaml", "title": "Delete an inbox message", "description": "Deletes the specified inbox message in the effective user’s inbox. This does not recall copies already delivered through other channels or attest to backup erasure.", "slug": "/api/notifications/delete-inbox-message", "method": "POST", "path": "/api/v1/notifications/delete-inbox-message", "requestSchema": "DeleteInboxMessageRequest", "responseSchema": "DeleteInboxMessageResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Message deleted successfully", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:archiveInboxMessage", "operationId": "archiveInboxMessage", "bundle": "notifications.yaml", "title": "Archive an inbox message", "description": "Archives a single inbox message. Archived messages are hidden from the default feed but retained.", "slug": "/api/notifications/archive-inbox-message", "method": "POST", "path": "/api/v1/notifications/archive-inbox-message", "requestSchema": "ArchiveInboxMessageRequest", "responseSchema": "ArchiveInboxMessageResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Message archived", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:unarchiveInboxMessage", "operationId": "unarchiveInboxMessage", "bundle": "notifications.yaml", "title": "Unarchive an inbox message", "description": "Restores a previously archived inbox message back into the default feed.", "slug": "/api/notifications/unarchive-inbox-message", "method": "POST", "path": "/api/v1/notifications/unarchive-inbox-message", "requestSchema": "UnarchiveInboxMessageRequest", "responseSchema": "UnarchiveInboxMessageResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Message unarchived", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:archiveAllInboxMessages", "operationId": "archiveAllInboxMessages", "bundle": "notifications.yaml", "title": "Archive all inbox messages", "description": "Archives all inbox messages for the authenticated user. Optionally scoped to specific workflow tags (OR logic).", "slug": "/api/notifications/archive-all-inbox-messages", "method": "POST", "path": "/api/v1/notifications/archive-all-inbox-messages", "requestSchema": "ArchiveAllInboxMessagesRequest", "responseSchema": "ArchiveAllInboxMessagesResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Messages archived", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:archiveAllReadInboxMessages", "operationId": "archiveAllReadInboxMessages", "bundle": "notifications.yaml", "title": "Archive all read inbox messages", "description": "Archives every already-read inbox message for the authenticated user. Optionally scoped to specific workflow tags (OR logic).", "slug": "/api/notifications/archive-all-read-inbox-messages", "method": "POST", "path": "/api/v1/notifications/archive-all-read-inbox-messages", "requestSchema": "ArchiveAllReadInboxMessagesRequest", "responseSchema": "ArchiveAllReadInboxMessagesResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Read messages archived", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:completeInboxAction", "operationId": "completeInboxAction", "bundle": "notifications.yaml", "title": "Complete an inbox message action", "description": "Marks an inbox action button completed. This changes inbox presentation state; it does not execute or authorize the business operation behind that button. Verify the actual business operation separately.", "slug": "/api/notifications/complete-inbox-action", "method": "POST", "path": "/api/v1/notifications/complete-inbox-action", "requestSchema": "CompleteInboxActionRequest", "responseSchema": "CompleteInboxActionResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Action completed", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:revertInboxAction", "operationId": "revertInboxAction", "bundle": "notifications.yaml", "title": "Revert an inbox message action", "description": "Restores an inbox action button’s pending state. It does not undo the business operation previously associated with the button.", "slug": "/api/notifications/revert-inbox-action", "method": "POST", "path": "/api/v1/notifications/revert-inbox-action", "requestSchema": "RevertInboxActionRequest", "responseSchema": "RevertInboxActionResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Action reverted", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:getPreferences", "operationId": "getPreferences", "bundle": "notifications.yaml", "title": "Get notification preferences", "description": "Returns the authenticated user's notification preferences, including per-channel and per-category settings.", "slug": "/api/notifications/get-preferences", "method": "POST", "path": "/api/v1/notifications/get-preferences", "requestSchema": "GetPreferencesRequest", "responseSchema": "GetPreferencesResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Preferences retrieved successfully", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:updateGlobalPreference", "operationId": "updateGlobalPreference", "bundle": "notifications.yaml", "title": "Update global notification preferences", "description": "Updates the subscriber's global (all-workflow) channel toggles. Omitted channels are left unchanged.", "slug": "/api/notifications/update-global-preference", "method": "POST", "path": "/api/v1/notifications/update-global-preference", "requestSchema": "UpdateGlobalPreferenceRequest", "responseSchema": "ProtobufEmpty", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Global preference updated", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:updateWorkflowPreference", "operationId": "updateWorkflowPreference", "bundle": "notifications.yaml", "title": "Update per-workflow notification preferences", "description": "Updates the subscriber's channel toggles for a single workflow. Omitted channels are left unchanged.", "slug": "/api/notifications/update-workflow-preference", "method": "POST", "path": "/api/v1/notifications/update-workflow-preference", "requestSchema": "UpdateWorkflowPreferenceRequest", "responseSchema": "ProtobufEmpty", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Workflow preference updated", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:bulkUpdatePreferences", "operationId": "bulkUpdatePreferences", "bundle": "notifications.yaml", "title": "Bulk-update per-workflow preferences", "description": "Updates channel toggles for multiple workflows in a single request.\n\nUpdates can partially apply before a later failure. Re-read preferences and retry only unresolved changes; a request failure does not imply an atomic rollback.", "slug": "/api/notifications/bulk-update-preferences", "method": "POST", "path": "/api/v1/notifications/bulk-update-preferences", "requestSchema": "BulkUpdatePreferencesRequest", "responseSchema": "BulkUpdatePreferencesResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Preferences bulk-updated", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:sendNotification", "operationId": "sendNotification", "bundle": "notifications.yaml", "title": "Send a notification to a user", "description": "Sends a notification to a single user by triggering a notification workflow.\nThe configured workflow determines its delivery channels.\n\nA transactionId is a provider correlation/deduplication input, not an unlimited exactly-once guarantee or an authorization grant; reconcile uncertain sends before retrying.\n\n### Workflow definitions and payload variables\n\n[`workflowId`](/api/notifications/send-notification#request-field-workflowid) selects a prepared notification workflow containing its channels and message templates. Discover workflows through [list workflows](/api/notifications/list-workflows). The send operation renders that workflow with the supplied [`payload`](/api/notifications/send-notification#request-field-payload) variables; it does not accept arbitrary message text outside the template contract.\n\nSave the returned [`transactionId`](/api/notifications/send-notification#response-field-transactionid) and any one you supplied. Use it for [cancelling](/core-platform/notifications/sending#cancel-a-pending-notification) and [checking delivery](/core-platform/notifications/administration#delivery-status).\n\nInspect the trigger acknowledgment and errors before treating the send as accepted.\nAcceptance does not confirm delivery or a read receipt: workflow configuration,\nrecipient preferences and provider delivery can produce later failures or suppression.\nCheck delivery status for the subsequent channel attempts.", "slug": "/api/notifications/send-notification", "method": "POST", "path": "/api/v1/notifications/manage/send", "requestSchema": "SendNotificationRequest", "responseSchema": "SendNotificationResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Notification trigger accepted; delivery is separate", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:sendBulkNotification", "operationId": "sendBulkNotification", "bundle": "notifications.yaml", "title": "Send a notification to multiple users", "description": "Submits per-recipient notification events together. A batch can mix workflows.\n\nResults are per-event: one recipient failing does not fail the others. Inspect each\nentry's [`acknowledged`](/api/models/bulk-trigger-result#response-field-acknowledged)\nand errors rather than the HTTP status alone. Accepted triggers are not delivery\nreceipts, and retrying an entire partially accepted batch can duplicate work.", "slug": "/api/notifications/send-bulk-notification", "method": "POST", "path": "/api/v1/notifications/manage/send-bulk", "requestSchema": "SendBulkNotificationRequest", "responseSchema": "SendBulkNotificationResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Bulk notification results", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:cancelNotification", "operationId": "cancelNotification", "bundle": "notifications.yaml", "title": "Cancel a pending notification", "description": "Requests cancellation of pending/scheduled provider work by transaction ID. It does not recall notifications already handed to a channel or undo an action the recipient performed. Inspect the cancellation result and preserve uncertainty when delivery is in flight.\n\n### Cancellation outcomes\n\nAn already processed notification can return HTTP 200 with `cancelled: false` and a message that it may already have been delivered. Inspect [`cancelled`](/api/notifications/cancel-notification#response-field-cancelled) rather than relying on HTTP status alone.", "slug": "/api/notifications/cancel-notification", "method": "POST", "path": "/api/v1/notifications/manage/cancel", "requestSchema": "CancelNotificationRequest", "responseSchema": "CancelNotificationResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Cancellation result", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:createTopic", "operationId": "createTopic", "bundle": "notifications.yaml", "title": "Create a notification topic", "description": "Creates a new topic that users can be subscribed to. Topics enable broadcasting notifications to groups of subscribers.", "slug": "/api/notifications/create-topic", "method": "POST", "path": "/api/v1/notifications/manage/create-topic", "requestSchema": "CreateTopicRequest", "responseSchema": "CreateTopicResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Topic created successfully", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:deleteTopic", "operationId": "deleteTopic", "bundle": "notifications.yaml", "title": "Delete a notification topic", "description": "Deletes an existing topic. All subscriber associations with this topic are removed.", "slug": "/api/notifications/delete-topic", "method": "POST", "path": "/api/v1/notifications/manage/delete-topic", "requestSchema": "DeleteTopicRequest", "responseSchema": "DeleteTopicResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Topic deleted", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:addSubscribersToTopic", "operationId": "addSubscribersToTopic", "bundle": "notifications.yaml", "title": "Add subscribers to a topic", "description": "Adds the selected users as subscribers to the specified topic.", "slug": "/api/notifications/add-subscribers-to-topic", "method": "POST", "path": "/api/v1/notifications/manage/add-subscribers-to-topic", "requestSchema": "AddSubscribersToTopicRequest", "responseSchema": "AddSubscribersToTopicResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Subscribers added", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:removeSubscribersFromTopic", "operationId": "removeSubscribersFromTopic", "bundle": "notifications.yaml", "title": "Remove subscribers from a topic", "description": "Removes the specified users from the topic's subscriber list.", "slug": "/api/notifications/remove-subscribers-from-topic", "method": "POST", "path": "/api/v1/notifications/manage/remove-subscribers-from-topic", "requestSchema": "RemoveSubscribersFromTopicRequest", "responseSchema": "RemoveSubscribersFromTopicResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Subscribers removed", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:listTopicSubscribers", "operationId": "listTopicSubscribers", "bundle": "notifications.yaml", "title": "List subscribers of a topic", "description": "Returns a paginated list of user IDs subscribed to the specified topic.", "slug": "/api/notifications/list-topic-subscribers", "method": "POST", "path": "/api/v1/notifications/manage/list-topic-subscribers", "requestSchema": "ListTopicSubscribersRequest", "responseSchema": "ListTopicSubscribersResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Topic subscribers listed", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:checkTopicSubscription", "operationId": "checkTopicSubscription", "bundle": "notifications.yaml", "title": "Check if a user is subscribed to a topic", "description": "Returns whether the specified user is currently subscribed to the given topic.", "slug": "/api/notifications/check-topic-subscription", "method": "POST", "path": "/api/v1/notifications/manage/check-topic-subscription", "requestSchema": "CheckTopicSubscriptionRequest", "responseSchema": "CheckTopicSubscriptionResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Subscription status returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:sendToTopic", "operationId": "sendToTopic", "bundle": "notifications.yaml", "title": "Send a notification to all topic subscribers", "description": "Broadcasts a notification to all subscribers of the specified topic. Optionally excludes a single user (e.g., the action originator).\n\nAcceptance is not a delivery or read receipt. Workflow configuration, recipient preferences and provider delivery can produce later failures or suppression. A transactionId is a provider correlation/deduplication input, not an unlimited exactly-once guarantee or an authorization grant; reconcile uncertain sends before retrying.", "slug": "/api/notifications/send-to-topic", "method": "POST", "path": "/api/v1/notifications/manage/send-to-topic", "requestSchema": "SendToTopicRequest", "responseSchema": "SendToTopicResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Topic notification trigger accepted; delivery is separate", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:sendWithDigest", "operationId": "sendWithDigest", "bundle": "notifications.yaml", "title": "Send a notification with digest aggregation", "description": "Sends a notification that will be aggregated into a digest before delivery. Multiple events within the digest window are batched into a single notification.\n\nAcceptance is not a delivery or read receipt. Workflow configuration, recipient preferences and provider delivery can produce later failures or suppression. A transactionId is a provider correlation/deduplication input, not an unlimited exactly-once guarantee or an authorization grant; reconcile uncertain sends before retrying.", "slug": "/api/notifications/send-with-digest", "method": "POST", "path": "/api/v1/notifications/manage/send-with-digest", "requestSchema": "SendWithDigestRequest", "responseSchema": "SendWithDigestResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Digest notification accepted", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:cancelDigestEvent", "operationId": "cancelDigestEvent", "bundle": "notifications.yaml", "title": "Cancel a pending digest event", "description": "Cancels a specific event from a pending digest. If the digest has already been sent, this has no effect.\n\n### Cancellation outcomes\n\nAn already processed digest event can return HTTP 200 with `cancelled: false` and a message that it may already have been processed. Inspect [`cancelled`](/api/notifications/cancel-digest-event#response-field-cancelled) rather than relying on HTTP status alone.", "slug": "/api/notifications/cancel-digest-event", "method": "POST", "path": "/api/v1/notifications/manage/cancel-digest-event", "requestSchema": "CancelDigestEventRequest", "responseSchema": "CancelDigestEventResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Digest event cancellation result", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:createSubscriber", "operationId": "createSubscriber", "bundle": "notifications.yaml", "title": "Create a notification subscriber", "description": "Creates a new subscriber profile in the notification system. The subscriber ID is used to target notifications and manage preferences.", "slug": "/api/notifications/create-subscriber", "method": "POST", "path": "/api/v1/notifications/manage/create-subscriber", "requestSchema": "CreateSubscriberRequest", "responseSchema": "CreateSubscriberResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Subscriber created", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:getSubscriber", "operationId": "getSubscriber", "bundle": "notifications.yaml", "title": "Get the caller's subscriber profile", "description": "Returns the subscriber profile for the authenticated caller, including channel registrations and notification preferences.", "slug": "/api/notifications/get-subscriber", "method": "POST", "path": "/api/v1/notifications/manage/get-subscriber", "requestSchema": "GetSubscriberRequest", "responseSchema": "GetSubscriberResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Subscriber profile returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:updateSubscriberData", "operationId": "updateSubscriberData", "bundle": "notifications.yaml", "title": "Update subscriber profile data", "description": "Updates the subscriber's profile data including name, email, phone, locale, and custom metadata.", "slug": "/api/notifications/update-subscriber-data", "method": "POST", "path": "/api/v1/notifications/manage/update-subscriber-data", "requestSchema": "UpdateSubscriberDataRequest", "responseSchema": "UpdateSubscriberDataResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Subscriber data updated", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:deleteSubscriber", "operationId": "deleteSubscriber", "bundle": "notifications.yaml", "title": "Delete the caller's subscriber profile", "description": "Requests deletion of the authenticated beneficiary's subscriber at the configured\nprovider. An absent subscriber is an idempotent success.\n\nInspect nested `status.acknowledged`. A missing\n[`status`](/api/notifications/delete-subscriber#response-field-status) is unknown:\nthe current handler can return an empty HTTP 200 response on configuration, network\nor provider errors. Reconcile that outcome instead of declaring cleanup complete.\nProvider acknowledgment does not certify complete erasure of queued work, remote\ncopies or platform records.", "slug": "/api/notifications/delete-subscriber", "method": "POST", "path": "/api/v1/notifications/manage/delete-subscriber", "requestSchema": "DeleteSubscriberRequest", "responseSchema": "DeleteSubscriberResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Provider acknowledgment when present; HTTP success alone does not confirm deletion.", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:listSubscribers", "operationId": "listSubscribers", "bundle": "notifications.yaml", "title": "List all subscribers", "description": "Returns a paginated list of all subscriber profiles in the notification system.", "slug": "/api/notifications/list-subscribers", "method": "POST", "path": "/api/v1/notifications/manage/list-subscribers", "requestSchema": "ListSubscribersRequest", "responseSchema": "ListSubscribersResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Subscribers listed", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:getDeliveryStatus", "operationId": "getDeliveryStatus", "bundle": "notifications.yaml", "title": "Get delivery status of a notification", "description": "Returns the current delivery status and metadata for a specific notification transaction, including provider-level details and timestamps.", "slug": "/api/notifications/get-delivery-status", "method": "POST", "path": "/api/v1/notifications/manage/get-delivery-status", "requestSchema": "GetDeliveryStatusRequest", "responseSchema": "GetDeliveryStatusResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Delivery status returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:getNotificationActivity", "operationId": "getNotificationActivity", "bundle": "notifications.yaml", "title": "Get notification activity log", "description": "Returns provider activity pages for diagnosing delivery across recipients.\nProvider activity can lag delivery and is not a complete authorization or\nbusiness-outcome audit. Use a bounded time window to inspect failures, and\nkeep successful recipients usable while you investigate.", "slug": "/api/notifications/get-notification-activity", "method": "POST", "path": "/api/v1/notifications/manage/get-notification-activity", "requestSchema": "GetNotificationActivityRequest", "responseSchema": "GetNotificationActivityResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Activity log returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:configureProvider", "operationId": "configureProvider", "bundle": "notifications.yaml", "title": "Configure a notification provider", "description": "Configures credentials and activation state for a notification provider (e.g., FCM, SendGrid, Twilio).\n\nUses **upsert** semantics: if an active integration already exists for the specified provider type, it updates the existing integration in place (preserving its ID and subscriber linkages). If no active integration exists, a new one is created.\n\nThe current read-then-upsert path does not establish atomic uniqueness under concurrent configuration. Credentials are sensitive and should stay in trusted backend tooling; the API shape is not proof that they bypass all internal journals or diagnostics.\n\n### Provider configuration outcomes\n\nMultiple active integrations of the same type return `409 Conflict` and need support resolution. After a credential change, test delivery to an already registered device. [Provider status](/api/notifications/get-providers) alone does not prove arrival.", "slug": "/api/notifications/configure-provider", "method": "POST", "path": "/api/v1/notifications/manage/configure-provider", "requestSchema": "ConfigureProviderRequest", "responseSchema": "ConfigureProviderResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Provider configured (created or updated)", "requestBodyRequired": true, "errors": { "409": { "description": "Multiple active connections exist for this provider type. Contact your Travila operator to resolve the conflict before retrying." } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:getProviders", "operationId": "getProviders", "bundle": "notifications.yaml", "title": "List configured providers", "description": "Returns all configured notification providers and their activation status.", "slug": "/api/notifications/get-providers", "method": "POST", "path": "/api/v1/notifications/manage/get-providers", "requestSchema": "GetProvidersRequest", "responseSchema": "GetProvidersResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Providers listed", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:createWorkflow", "operationId": "createWorkflow", "bundle": "notifications.yaml", "title": "Create a notification workflow", "description": "Creates a new notification workflow definition with steps, channel configuration, and preference settings.", "slug": "/api/notifications/create-workflow", "method": "POST", "path": "/api/v1/notifications/manage/create-workflow", "requestSchema": "CreateWorkflowRequest", "responseSchema": "CreateWorkflowResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Workflow created", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:updateWorkflow", "operationId": "updateWorkflow", "bundle": "notifications.yaml", "title": "Update an existing notification workflow", "description": "Updates the identified workflow using the supplied definition.", "slug": "/api/notifications/update-workflow", "method": "POST", "path": "/api/v1/notifications/manage/update-workflow", "requestSchema": "UpdateWorkflowRequest", "responseSchema": "UpdateWorkflowResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Workflow updated", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:getWorkflow", "operationId": "getWorkflow", "bundle": "notifications.yaml", "title": "Get a notification workflow", "description": "Returns the full workflow definition and metadata. The workflow can be identified by either workflow ID or trigger identifier.", "slug": "/api/notifications/get-workflow", "method": "POST", "path": "/api/v1/notifications/manage/get-workflow", "requestSchema": "GetWorkflowRequest", "responseSchema": "GetWorkflowResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Workflow returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:listWorkflows", "operationId": "listWorkflows", "bundle": "notifications.yaml", "title": "List notification workflows", "description": "Returns a paginated list of all notification workflows with summary information.", "slug": "/api/notifications/list-workflows", "method": "POST", "path": "/api/v1/notifications/manage/list-workflows", "requestSchema": "ListWorkflowsRequest", "responseSchema": "ListWorkflowsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Workflows listed", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:deleteWorkflow", "operationId": "deleteWorkflow", "bundle": "notifications.yaml", "title": "Delete a notification workflow", "description": "Deletes a notification workflow. The workflow can be identified by either workflow ID or trigger identifier.", "slug": "/api/notifications/delete-workflow", "method": "POST", "path": "/api/v1/notifications/manage/delete-workflow", "requestSchema": "DeleteWorkflowRequest", "responseSchema": "DeleteWorkflowResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Workflow deleted", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:getPendingChanges", "operationId": "getPendingChanges", "bundle": "notifications.yaml", "title": "Get pending workflow changes", "description": "Returns pending workflow edits in the notification provider’s development configuration. These provider environments do not create separate Travila projects or test/live isolation.", "slug": "/api/notifications/get-pending-changes", "method": "POST", "path": "/api/v1/notifications/manage/get-pending-changes", "requestSchema": "GetPendingChangesRequest", "responseSchema": "GetPendingChangesResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Pending changes returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:promoteChange", "operationId": "promoteChange", "bundle": "notifications.yaml", "title": "Promote a single workflow change", "description": "Promotes one staged workflow change to the notification provider’s live configuration by changeId.", "slug": "/api/notifications/promote-change", "method": "POST", "path": "/api/v1/notifications/manage/promote-change", "requestSchema": "PromoteChangeRequest", "responseSchema": "PromoteChangeResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Change promoted", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "notifications:promoteAllChanges", "operationId": "promoteAllChanges", "bundle": "notifications.yaml", "title": "Promote all pending workflow changes", "description": "Promotes staged workflow changes to the notification provider’s live configuration. Supply changeIds to select changes; omitting it or sending an empty array selects all pending changes. Inspect per-change errors alongside the successful results.", "slug": "/api/notifications/promote-all-changes", "method": "POST", "path": "/api/v1/notifications/manage/promote-all-changes", "requestSchema": "PromoteAllChangesRequest", "responseSchema": "PromoteAllChangesResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Changes promoted", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission." } } }, { "key": "scheduled-jobs:createJob", "operationId": "createJob", "bundle": "scheduled-jobs.yaml", "title": "Create a scheduled job", "description": "Creates a new scheduled job. The job becomes active immediately and fires on\nits next matching time.", "slug": "/api/scheduled-jobs/create-job", "method": "POST", "path": "/api/v1/scheduler/create-job", "requestSchema": "CreateJobRequest", "responseSchema": "Schedule", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Scheduled job created", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key for the configured deployment. Backend `sk_…` calls can use authorized on-behalf-of context; a client `pk_…` key requires the configured user's JWT. Owner operations and project teardown have different beneficiary requirements. Keep secret keys out of client apps." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this backend call acts for. An authorized `sk_…` request can\nomit this header where the operation permits a subjectless caller. In the\ncurrent public integration, that caller can operate across owners in its\nauthenticated tenant's `default` project. The key does not select\nan independently isolated project.\n\nSupplying this header requires `users:impersonate` and scopes ordinary reads\nand mutations to that user. `create-job` uses that beneficiary; a different\n`ownerSubject` is rejected. Without a beneficiary, creation requires\n`ownerSubject` in the request body.\n\n`delete-jobs-for-owner` requires a beneficiary. `delete-jobs-for-project`\nrequires a subjectless backend request and removes schedules across owners\nin the current tenant/default-project scope. Check each operation before\nchoosing the credential context. Keep secret keys on the backend.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "scheduled-jobs:getJob", "operationId": "getJob", "bundle": "scheduled-jobs.yaml", "title": "Get a scheduled job", "description": "Returns the metadata and current state of a single scheduled job by ID.", "slug": "/api/scheduled-jobs/get-job", "method": "POST", "path": "/api/v1/scheduler/get-job", "requestSchema": "GetJobRequest", "responseSchema": "Schedule", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Scheduled job returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key for the configured deployment. Backend `sk_…` calls can use authorized on-behalf-of context; a client `pk_…` key requires the configured user's JWT. Owner operations and project teardown have different beneficiary requirements. Keep secret keys out of client apps." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this backend call acts for. An authorized `sk_…` request can\nomit this header where the operation permits a subjectless caller. In the\ncurrent public integration, that caller can operate across owners in its\nauthenticated tenant's `default` project. The key does not select\nan independently isolated project.\n\nSupplying this header requires `users:impersonate` and scopes ordinary reads\nand mutations to that user. `create-job` uses that beneficiary; a different\n`ownerSubject` is rejected. Without a beneficiary, creation requires\n`ownerSubject` in the request body.\n\n`delete-jobs-for-owner` requires a beneficiary. `delete-jobs-for-project`\nrequires a subjectless backend request and removes schedules across owners\nin the current tenant/default-project scope. Check each operation before\nchoosing the credential context. Keep secret keys on the backend.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "scheduled-jobs:listJobs", "operationId": "listJobs", "bundle": "scheduled-jobs.yaml", "title": "List scheduled jobs", "description": "Returns a paginated list of scheduled jobs for the authenticated\ntenant and project. Optionally filter by lifecycle state or target kind.", "slug": "/api/scheduled-jobs/list-jobs", "method": "POST", "path": "/api/v1/scheduler/list-jobs", "requestSchema": "ListJobsRequest", "responseSchema": "ListJobsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Scheduled jobs returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key for the configured deployment. Backend `sk_…` calls can use authorized on-behalf-of context; a client `pk_…` key requires the configured user's JWT. Owner operations and project teardown have different beneficiary requirements. Keep secret keys out of client apps." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this backend call acts for. An authorized `sk_…` request can\nomit this header where the operation permits a subjectless caller. In the\ncurrent public integration, that caller can operate across owners in its\nauthenticated tenant's `default` project. The key does not select\nan independently isolated project.\n\nSupplying this header requires `users:impersonate` and scopes ordinary reads\nand mutations to that user. `create-job` uses that beneficiary; a different\n`ownerSubject` is rejected. Without a beneficiary, creation requires\n`ownerSubject` in the request body.\n\n`delete-jobs-for-owner` requires a beneficiary. `delete-jobs-for-project`\nrequires a subjectless backend request and removes schedules across owners\nin the current tenant/default-project scope. Check each operation before\nchoosing the credential context. Keep secret keys on the backend.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "scheduled-jobs:updateJob", "operationId": "updateJob", "bundle": "scheduled-jobs.yaml", "title": "Update a scheduled job", "description": "Updates the provided schedule settings. Only included fields change; omitted fields\nremain unchanged.\n\n### Timing changes\n\nThe scheduler applies timing edits before returning by cancelling and reinserting\nthe scheduled entry. This cannot undo an HTTP callback already dispatched or a\nbusiness action your receiver has accepted.\n\n[`nextTriggerAt`](/api/models/schedule#response-field-nexttriggerat) on the returned\njob is the scheduling snapshot after the update; it can change as work advances.\nDo not infer wall-clock firing precision or business completion from that timestamp.", "slug": "/api/scheduled-jobs/update-job", "method": "POST", "path": "/api/v1/scheduler/update-job", "requestSchema": "UpdateJobRequest", "responseSchema": "UpdateJobResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Scheduled job updated", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key for the configured deployment. Backend `sk_…` calls can use authorized on-behalf-of context; a client `pk_…` key requires the configured user's JWT. Owner operations and project teardown have different beneficiary requirements. Keep secret keys out of client apps." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this backend call acts for. An authorized `sk_…` request can\nomit this header where the operation permits a subjectless caller. In the\ncurrent public integration, that caller can operate across owners in its\nauthenticated tenant's `default` project. The key does not select\nan independently isolated project.\n\nSupplying this header requires `users:impersonate` and scopes ordinary reads\nand mutations to that user. `create-job` uses that beneficiary; a different\n`ownerSubject` is rejected. Without a beneficiary, creation requires\n`ownerSubject` in the request body.\n\n`delete-jobs-for-owner` requires a beneficiary. `delete-jobs-for-project`\nrequires a subjectless backend request and removes schedules across owners\nin the current tenant/default-project scope. Check each operation before\nchoosing the credential context. Keep secret keys on the backend.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "scheduled-jobs:pauseJob", "operationId": "pauseJob", "bundle": "scheduled-jobs.yaml", "title": "Pause a scheduled job", "description": "Pauses future scheduling for the job. A dispatch already admitted or in flight can still complete; pausing is not remote-effect cancellation.", "slug": "/api/scheduled-jobs/pause-job", "method": "POST", "path": "/api/v1/scheduler/pause-job", "requestSchema": "PauseJobRequest", "responseSchema": "Schedule", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Scheduled job paused", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key for the configured deployment. Backend `sk_…` calls can use authorized on-behalf-of context; a client `pk_…` key requires the configured user's JWT. Owner operations and project teardown have different beneficiary requirements. Keep secret keys out of client apps." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this backend call acts for. An authorized `sk_…` request can\nomit this header where the operation permits a subjectless caller. In the\ncurrent public integration, that caller can operate across owners in its\nauthenticated tenant's `default` project. The key does not select\nan independently isolated project.\n\nSupplying this header requires `users:impersonate` and scopes ordinary reads\nand mutations to that user. `create-job` uses that beneficiary; a different\n`ownerSubject` is rejected. Without a beneficiary, creation requires\n`ownerSubject` in the request body.\n\n`delete-jobs-for-owner` requires a beneficiary. `delete-jobs-for-project`\nrequires a subjectless backend request and removes schedules across owners\nin the current tenant/default-project scope. Check each operation before\nchoosing the credential context. Keep secret keys on the backend.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "scheduled-jobs:resumeJob", "operationId": "resumeJob", "bundle": "scheduled-jobs.yaml", "title": "Resume a scheduled job", "description": "Resumes a previously paused scheduled job, returning it to the active state.", "slug": "/api/scheduled-jobs/resume-job", "method": "POST", "path": "/api/v1/scheduler/resume-job", "requestSchema": "ResumeJobRequest", "responseSchema": "Schedule", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Scheduled job resumed", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key for the configured deployment. Backend `sk_…` calls can use authorized on-behalf-of context; a client `pk_…` key requires the configured user's JWT. Owner operations and project teardown have different beneficiary requirements. Keep secret keys out of client apps." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this backend call acts for. An authorized `sk_…` request can\nomit this header where the operation permits a subjectless caller. In the\ncurrent public integration, that caller can operate across owners in its\nauthenticated tenant's `default` project. The key does not select\nan independently isolated project.\n\nSupplying this header requires `users:impersonate` and scopes ordinary reads\nand mutations to that user. `create-job` uses that beneficiary; a different\n`ownerSubject` is rejected. Without a beneficiary, creation requires\n`ownerSubject` in the request body.\n\n`delete-jobs-for-owner` requires a beneficiary. `delete-jobs-for-project`\nrequires a subjectless backend request and removes schedules across owners\nin the current tenant/default-project scope. Check each operation before\nchoosing the credential context. Keep secret keys on the backend.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "scheduled-jobs:deleteJob", "operationId": "deleteJob", "bundle": "scheduled-jobs.yaml", "title": "Delete a scheduled job", "description": "Soft-deletes the schedule and stops future scheduling. The record is retained for inspection. Already dispatched work and its external effects are not undone by deleting the schedule.", "slug": "/api/scheduled-jobs/delete-job", "method": "POST", "path": "/api/v1/scheduler/delete-job", "requestSchema": "DeleteJobRequest", "responseSchema": "DeleteJobResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Scheduled job deleted", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key for the configured deployment. Backend `sk_…` calls can use authorized on-behalf-of context; a client `pk_…` key requires the configured user's JWT. Owner operations and project teardown have different beneficiary requirements. Keep secret keys out of client apps." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this backend call acts for. An authorized `sk_…` request can\nomit this header where the operation permits a subjectless caller. In the\ncurrent public integration, that caller can operate across owners in its\nauthenticated tenant's `default` project. The key does not select\nan independently isolated project.\n\nSupplying this header requires `users:impersonate` and scopes ordinary reads\nand mutations to that user. `create-job` uses that beneficiary; a different\n`ownerSubject` is rejected. Without a beneficiary, creation requires\n`ownerSubject` in the request body.\n\n`delete-jobs-for-owner` requires a beneficiary. `delete-jobs-for-project`\nrequires a subjectless backend request and removes schedules across owners\nin the current tenant/default-project scope. Check each operation before\nchoosing the credential context. Keep secret keys on the backend.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "scheduled-jobs:deleteJobsForProject", "operationId": "deleteJobsForProject", "bundle": "scheduled-jobs.yaml", "title": "Delete all scheduled jobs for a project", "description": "Soft-deletes every scheduled job belonging to the tenant and project in\nthe request context. Intended as a tenant lifecycle hook invoked during\nproject teardown. The request body carries no fields — tenant and\nproject are derived from ingress headers.", "slug": "/api/scheduled-jobs/delete-jobs-for-project", "method": "POST", "path": "/api/v1/scheduler/delete-jobs-for-project", "requestSchema": "DeleteJobsForProjectRequest", "responseSchema": "DeleteJobsForProjectResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Scheduled jobs deleted", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key for the configured deployment. Backend `sk_…` calls can use authorized on-behalf-of context; a client `pk_…` key requires the configured user's JWT. Owner operations and project teardown have different beneficiary requirements. Keep secret keys out of client apps." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this backend call acts for. An authorized `sk_…` request can\nomit this header where the operation permits a subjectless caller. In the\ncurrent public integration, that caller can operate across owners in its\nauthenticated tenant's `default` project. The key does not select\nan independently isolated project.\n\nSupplying this header requires `users:impersonate` and scopes ordinary reads\nand mutations to that user. `create-job` uses that beneficiary; a different\n`ownerSubject` is rejected. Without a beneficiary, creation requires\n`ownerSubject` in the request body.\n\n`delete-jobs-for-owner` requires a beneficiary. `delete-jobs-for-project`\nrequires a subjectless backend request and removes schedules across owners\nin the current tenant/default-project scope. Check each operation before\nchoosing the credential context. Keep secret keys on the backend.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "scheduled-jobs:deleteJobsForOwner", "operationId": "deleteJobsForOwner", "bundle": "scheduled-jobs.yaml", "title": "Delete all scheduled jobs for the calling owner", "description": "Soft-deletes schedules owned by the authenticated beneficiary within the verified tenant/project context. This is an explicit schedule-cleanup operation for offboarding or user-requested deletion. Do not call it on sign-out: schedules belong to the user/project and are not scoped to the current device session.", "slug": "/api/scheduled-jobs/delete-jobs-for-owner", "method": "POST", "path": "/api/v1/scheduler/delete-jobs-for-owner", "requestSchema": "DeleteJobsForOwnerRequest", "responseSchema": "DeleteJobsForOwnerResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Scheduled jobs deleted", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key for the configured deployment. Backend `sk_…` calls can use authorized on-behalf-of context; a client `pk_…` key requires the configured user's JWT. Owner operations and project teardown have different beneficiary requirements. Keep secret keys out of client apps." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this backend call acts for. An authorized `sk_…` request can\nomit this header where the operation permits a subjectless caller. In the\ncurrent public integration, that caller can operate across owners in its\nauthenticated tenant's `default` project. The key does not select\nan independently isolated project.\n\nSupplying this header requires `users:impersonate` and scopes ordinary reads\nand mutations to that user. `create-job` uses that beneficiary; a different\n`ownerSubject` is rejected. Without a beneficiary, creation requires\n`ownerSubject` in the request body.\n\n`delete-jobs-for-owner` requires a beneficiary. `delete-jobs-for-project`\nrequires a subjectless backend request and removes schedules across owners\nin the current tenant/default-project scope. Check each operation before\nchoosing the credential context. Keep secret keys on the backend.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "scheduled-jobs:listExecutions", "operationId": "listExecutions", "bundle": "scheduled-jobs.yaml", "title": "List executions for a scheduled job", "description": "Returns a paginated execution history for a scheduled job. Each record\ncaptures a single firing — its status, HTTP result, attempt number, and\nduration. Optionally filter by execution status.", "slug": "/api/scheduled-jobs/list-executions", "method": "POST", "path": "/api/v1/scheduler/list-executions", "requestSchema": "ListExecutionsRequest", "responseSchema": "ListExecutionsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Executions returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] }, { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key for the configured deployment. Backend `sk_…` calls can use authorized on-behalf-of context; a client `pk_…` key requires the configured user's JWT. Owner operations and project teardown have different beneficiary requirements. Keep secret keys out of client apps." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this backend call acts for. An authorized `sk_…` request can\nomit this header where the operation permits a subjectless caller. In the\ncurrent public integration, that caller can operate across owners in its\nauthenticated tenant's `default` project. The key does not select\nan independently isolated project.\n\nSupplying this header requires `users:impersonate` and scopes ordinary reads\nand mutations to that user. `create-job` uses that beneficiary; a different\n`ownerSubject` is rejected. Without a beneficiary, creation requires\n`ownerSubject` in the request body.\n\n`delete-jobs-for-owner` requires a beneficiary. `delete-jobs-for-project`\nrequires a subjectless backend request and removes schedules across owners\nin the current tenant/default-project scope. Check each operation before\nchoosing the credential context. Keep secret keys on the backend.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "secrets:putSecret", "operationId": "putSecret", "bundle": "secrets.yaml", "title": "Create or update a secret", "description": "Writes or replaces a value under `name`; this upsert also rotates the stored credential. The response contains metadata only, and no public read endpoint returns the value. Name-based bindings remain the same, but consumers can retain prior values in caches or in-flight work; this is not upstream credential revocation.\n\nValue storage and metadata updates are separate steps. On an error, metadata alone cannot confirm which value is current. Stop using the affected binding and contact your Travila operator before retrying.", "slug": "/api/secrets/put-secret", "method": "POST", "path": "/api/v1/secrets/put", "requestSchema": "PutSecretRequest", "responseSchema": "PutSecretResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Secret written; metadata only", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "secrets:getSecretMetadata", "operationId": "getSecretMetadata", "bundle": "secrets.yaml", "title": "Get a secret's metadata", "description": "Returns the secret’s metadata without exposing the credential. Unknown names return 404. The metadata revision records that row; after a partially failed write it is not independent proof of the actual stored credential version.", "slug": "/api/secrets/get-secret-metadata", "method": "POST", "path": "/api/v1/secrets/get-metadata", "requestSchema": "GetSecretMetadataRequest", "responseSchema": "GetSecretMetadataResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Metadata returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "secrets:listSecrets", "operationId": "listSecrets", "bundle": "secrets.yaml", "title": "List secrets", "description": "Returns metadata for every secret in the project, paginated. Values are not\nincluded, and there is no parameter that would include them.\n\nSend `{}` for the first page at the server's default size.\n", "slug": "/api/secrets/list-secrets", "method": "POST", "path": "/api/v1/secrets/list", "requestSchema": "ListSecretsRequest", "responseSchema": "ListSecretsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Page of secret metadata", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "secrets:deleteSecret", "operationId": "deleteSecret", "bundle": "secrets.yaml", "title": "Delete a secret", "description": "Deletes the stored value before its metadata. An absent secret is an idempotent success with `deleted` false, which may be omitted. A failure does not prove the previous value remains intact.\n\nKnown custom MCP references block deletion with 409 unless `force` is used. Detach or rebind those consumers first where possible. The reference list covers tracked custom servers, not every possible external consumer. Forced deletion can break future credential resolution; it does not recall cached or already dispatched use, revoke the credential at its issuer, or attest to backup erasure.", "slug": "/api/secrets/delete-secret", "method": "POST", "path": "/api/v1/secrets/delete", "requestSchema": "DeleteSecretRequest", "responseSchema": "DeleteSecretResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Delete processed", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." } } }, { "key": "storage:createFolder", "operationId": "createFolder", "bundle": "storage.yaml", "title": "Create a new folder", "description": "Creates the requested folder entry at the specified path. It does not create intermediate parent entries; create those explicitly when needed.", "slug": "/api/storage/create-folder", "method": "POST", "path": "/api/v1/storage/create-folder", "requestSchema": "CreateFolderRequest", "responseSchema": "CreateFolderResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Folder created (or already existed)", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "storage:deleteFolder", "operationId": "deleteFolder", "bundle": "storage.yaml", "title": "Delete a folder", "description": "Deletes the selected folder entry and reports deletion counts on success.\n\nWith `recursive` false or omitted, the operation leaves descendants in place and\ndoes not require an empty folder. This option cannot safely test whether the\nproject still contains documents.\n\nWith `recursive: true`, it also attempts descendant file and folder deletion. A\nfailure can follow earlier object deletions, so inspect the resulting state before\nrecovery.", "slug": "/api/storage/delete-folder", "method": "POST", "path": "/api/v1/storage/delete-folder", "requestSchema": "DeleteFolderRequest", "responseSchema": "DeleteFolderResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Folder deleted", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "storage:listFiles", "operationId": "listFiles", "bundle": "storage.yaml", "title": "List files and folders in a directory", "description": "Lists files and subfolders under the given folder path. The current file filter accepts upload-date fields but does not enforce them; do not rely on those fields to exclude records.", "slug": "/api/storage/list-files", "method": "POST", "path": "/api/v1/storage/list-files", "requestSchema": "ListFilesRequest", "responseSchema": "ListFilesResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "File listing returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "storage:uploadFile", "operationId": "uploadFile", "bundle": "storage.yaml", "title": "Upload a file (deprecated)", "description": "**Deprecated — use the 3-step pre-signed flow instead** (`generate-upload-url` → `PUT` → `register-uploaded-file`).\n\nUploads file content synchronously to the specified folder. For large files, prefer the pre-signed flow to avoid sending the full content through this operation.", "slug": "/api/storage/upload-file", "method": "POST", "path": "/api/v1/storage/upload-file", "requestSchema": "UploadFileRequest", "responseSchema": "UploadFileResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "File uploaded successfully", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "storage:deleteFile", "operationId": "deleteFile", "bundle": "storage.yaml", "title": "Delete a file", "description": "Deletes the stored object and tracked file metadata, releasing tracked quota on successful completion. This does not prove removal from backups, invalidate every copied URL immediately, or undo a download already in flight. Reconcile partial failures.", "slug": "/api/storage/delete-file", "method": "POST", "path": "/api/v1/storage/delete-file", "requestSchema": "DeleteFileRequest", "responseSchema": "DeleteFileResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "File deleted", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "storage:moveFile", "operationId": "moveFile", "bundle": "storage.yaml", "title": "Move or rename a file", "description": "Moves or renames a stored file while preserving its identity.", "slug": "/api/storage/move-file", "method": "POST", "path": "/api/v1/storage/move-file", "requestSchema": "MoveFileRequest", "responseSchema": "MoveFileResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "File moved", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "storage:searchFiles", "operationId": "searchFiles", "bundle": "storage.yaml", "title": "Search files", "description": "Searches the effective user's tracked files using a case-insensitive filename\nsubstring or a case-insensitive complete tag. File contents, such as text inside\na PDF, are not searched.\n\nSupported `FileFilter` fields narrow candidates before the query is applied, and\nall listed tags must be present. The date filters\n[`uploadedAfter`](/api/models/file-filter#request-field-uploadedafter) and\n[`uploadedBefore`](/api/models/file-filter#request-field-uploadedbefore) are accepted\nbut currently not enforced; do not offer a date range as an effective filter.\n\n[`maxResults`](/api/storage/search-files#request-field-maxresults) caps a single\nresponse; search does not paginate. If results are too broad, let the customer\nrefine the name, tag or folder rather than promising a complete result set.", "slug": "/api/storage/search-files", "method": "POST", "path": "/api/v1/storage/search-files", "requestSchema": "SearchFilesRequest", "responseSchema": "SearchFilesResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Search results returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "storage:getFileMetadata", "operationId": "getFileMetadata", "bundle": "storage.yaml", "title": "Get file metadata", "description": "Retrieves a file's tracked metadata without downloading its content.", "slug": "/api/storage/get-file-metadata", "method": "POST", "path": "/api/v1/storage/get-file-metadata", "requestSchema": "GetFileMetadataRequest", "responseSchema": "GetFileMetadataResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "File metadata returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "storage:updateFileMetadata", "operationId": "updateFileMetadata", "bundle": "storage.yaml", "title": "Update file metadata", "description": "Replaces the metadata map and tag list when they survive decoding as nonnil values; it does not merge individual map keys. A nonempty description replaces the old description. This public shape has no reliable explicit clear operation for every empty value. Read the current record and submit the complete intended map/list; concurrent updates can overwrite one another.\n\n### Update metadata\n\nThis operation cannot clear tags with `[]`; an empty description leaves the previous description unchanged.", "slug": "/api/storage/update-file-metadata", "method": "POST", "path": "/api/v1/storage/update-file-metadata", "requestSchema": "UpdateFileMetadataRequest", "responseSchema": "UpdateFileMetadataResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "File metadata updated", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "storage:generateUploadUrl", "operationId": "generateUploadUrl", "bundle": "storage.yaml", "title": "Generate a pre-signed upload URL", "description": "Step 1: issues a time-limited signed URL for direct upload. `sizeBytes` is checked against current tracked quota and used as the signed upper size bound; it is not an atomic reservation or an exact-size assertion. Send the returned required headers, upload, and then register the returned fileId. The URL can be reused until expiry; treat it as a credential.", "slug": "/api/storage/generate-upload-url", "method": "POST", "path": "/api/v1/storage/generate-upload-url", "requestSchema": "GenerateUploadUrlRequest", "responseSchema": "GenerateUploadUrlResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Upload URL generated", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "storage:registerUploadedFile", "operationId": "registerUploadedFile", "bundle": "storage.yaml", "title": "Register a file uploaded via pre-signed URL", "description": "Step 3: after uploading, register the fileId with the same folderPath and intended fileName. The backend checks the object at the derived caller-scoped path and reads its stored size and content-type metadata. MIME metadata can be supplied by the uploader and is not byte/content validation. The signed-upload path does not compute a checksum.\n\nAn already registered fileId returns the existing record with registered false, which may be omitted. This retry behavior does not prove that a reused signed URL cannot subsequently alter the object. Missing uploaded objects return 404; quota and backend failures require reconciliation.", "slug": "/api/storage/register-uploaded-file", "method": "POST", "path": "/api/v1/storage/register-uploaded-file", "requestSchema": "RegisterUploadedFileRequest", "responseSchema": "RegisterUploadedFileResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "File registered (or already registered)", "requestBodyRequired": true, "errors": { "404": { "description": "No uploaded object found for this `fileId` (PUT the file first)" } }, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "storage:generateDownloadUrl", "operationId": "generateDownloadUrl", "bundle": "storage.yaml", "title": "Generate a pre-signed download URL", "description": "Generates a time-limited pre-signed URL for downloading a file directly from the storage backend.", "slug": "/api/storage/generate-download-url", "method": "POST", "path": "/api/v1/storage/generate-download-url", "requestSchema": "GenerateDownloadUrlRequest", "responseSchema": "GenerateDownloadUrlResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Download URL generated", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "storage:batchGenerateDownloadUrls", "operationId": "batchGenerateDownloadUrls", "bundle": "storage.yaml", "title": "Generate pre-signed download URLs for multiple files", "description": "Generates download URLs in a batch. Inspect each result’s `success === true` and match by fileId; order is not guaranteed. Per-file errors can be returned independently, but malformed requests, authentication and request-level backend failures can still fail the whole call. URLs remain sensitive bearer credentials.", "slug": "/api/storage/batch-generate-download-urls", "method": "POST", "path": "/api/v1/storage/batch-generate-download-urls", "requestSchema": "BatchGenerateDownloadUrlsRequest", "responseSchema": "BatchGenerateDownloadUrlsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Per-file download URL results returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "storage:getStorageQuota", "operationId": "getStorageQuota", "bundle": "storage.yaml", "title": "Get storage usage and quota", "description": "Returns the authenticated user's current tracked storage usage and quota.", "slug": "/api/storage/get-storage-quota", "method": "POST", "path": "/api/v1/storage/get-storage-quota", "requestSchema": "GetStorageQuotaRequest", "responseSchema": "GetStorageQuotaResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Quota information returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "storage:getState", "operationId": "getState", "bundle": "storage.yaml", "title": "Get storage state", "description": "Returns the effective user’s full tracked storage state without pagination. Intended for restricted debugging; large accounts can produce large responses. A storage record is not an inventory or erasure certificate for every object/backend copy.", "slug": "/api/storage/get-state", "method": "POST", "path": "/api/v1/storage/get-state", "requestSchema": "GetStateRequest", "responseSchema": "GetStateResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Full state returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [], "onBehalfOf": [] }, { "apiKeyAuth": [], "bearerAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of", "description": "The end user this call acts for. Required with an `sk_…` key, because a secret\nkey identifies your tenant and not a user; omitting it returns\n`401 authenticated user_id is required`. The key needs the `users:impersonate`\nscope or the call fails with `403 insufficient_scope`.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "webhooks:createWebhookEndpoint", "operationId": "createWebhookEndpoint", "bundle": "webhooks.yaml", "title": "Create a webhook endpoint", "description": "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.", "slug": "/api/webhooks/create-webhook-endpoint", "method": "POST", "path": "/api/v1/webhooks/create-endpoint", "requestSchema": "CreateWebhookEndpointRequest", "responseSchema": "CreateWebhookEndpointResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Endpoint created successfully", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "webhooks:listWebhookEndpoints", "operationId": "listWebhookEndpoints", "bundle": "webhooks.yaml", "title": "List webhook endpoints", "description": "Returns a paginated list of all webhook endpoints belonging to the authenticated tenant.", "slug": "/api/webhooks/list-webhook-endpoints", "method": "POST", "path": "/api/v1/webhooks/list-endpoints", "requestSchema": "ListWebhookEndpointsRequest", "responseSchema": "ListWebhookEndpointsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Endpoints listed successfully", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "webhooks:updateWebhookEndpoint", "operationId": "updateWebhookEndpoint", "bundle": "webhooks.yaml", "title": "Update a webhook endpoint", "description": "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.", "slug": "/api/webhooks/update-webhook-endpoint", "method": "POST", "path": "/api/v1/webhooks/update-endpoint", "requestSchema": "UpdateWebhookEndpointRequest", "responseSchema": "UpdateWebhookEndpointResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Endpoint updated successfully", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "webhooks:deleteWebhookEndpoint", "operationId": "deleteWebhookEndpoint", "bundle": "webhooks.yaml", "title": "Delete a webhook endpoint", "description": "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.", "slug": "/api/webhooks/delete-webhook-endpoint", "method": "POST", "path": "/api/v1/webhooks/delete-endpoint", "requestSchema": "DeleteWebhookEndpointRequest", "responseSchema": "DeleteWebhookEndpointResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Endpoint deleted successfully", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "webhooks:createWebhookSubscription", "operationId": "createWebhookSubscription", "bundle": "webhooks.yaml", "title": "Create a webhook subscription", "description": "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.\n\n### One subscription per endpoint\n\nOnly 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.", "slug": "/api/webhooks/create-webhook-subscription", "method": "POST", "path": "/api/v1/webhooks/create-subscription", "requestSchema": "CreateWebhookSubscriptionRequest", "responseSchema": "CreateWebhookSubscriptionResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Subscription created successfully", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "webhooks:listWebhookSubscriptions", "operationId": "listWebhookSubscriptions", "bundle": "webhooks.yaml", "title": "List webhook subscriptions", "description": "Returns a paginated list of webhook subscriptions. Optionally filter by endpoint ID.", "slug": "/api/webhooks/list-webhook-subscriptions", "method": "POST", "path": "/api/v1/webhooks/list-subscriptions", "requestSchema": "ListWebhookSubscriptionsRequest", "responseSchema": "ListWebhookSubscriptionsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Subscriptions listed successfully", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "webhooks:deleteWebhookSubscription", "operationId": "deleteWebhookSubscription", "bundle": "webhooks.yaml", "title": "Delete a webhook subscription", "description": "Deletes the subscription without deleting its endpoint. Pending/in-flight provider deliveries and retained history require separate handling; deletion is not remote-effect rollback.", "slug": "/api/webhooks/delete-webhook-subscription", "method": "POST", "path": "/api/v1/webhooks/delete-subscription", "requestSchema": "DeleteWebhookSubscriptionRequest", "responseSchema": "DeleteWebhookSubscriptionResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Subscription deleted successfully", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "webhooks:listWebhookDeliveries", "operationId": "listWebhookDeliveries", "bundle": "webhooks.yaml", "title": "List webhook event deliveries", "description": "Returns paginated delivery records. A record is not a complete log of every HTTP attempt.", "slug": "/api/webhooks/list-webhook-deliveries", "method": "POST", "path": "/api/v1/webhooks/list-deliveries", "requestSchema": "ListWebhookDeliveriesRequest", "responseSchema": "ListWebhookDeliveriesResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Deliveries listed successfully", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } }, { "key": "webhooks:retryWebhookDelivery", "operationId": "retryWebhookDelivery", "bundle": "webhooks.yaml", "title": "Retry a failed webhook delivery", "description": "Re-queues a previously failed or discarded event delivery for another delivery attempt.\n\nA successful response only acknowledges re-queueing. The receiver must deduplicate repeated events and distinguish receipt from completed business work.", "slug": "/api/webhooks/retry-webhook-delivery", "method": "POST", "path": "/api/v1/webhooks/retry-delivery", "requestSchema": "RetryWebhookDeliveryRequest", "responseSchema": "RetryWebhookDeliveryResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Another attempt requested; inspect delivery status for the outcome", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "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." }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end user's own JWT, issued by the OIDC provider configured on the\npublishable key. Required alongside a `pk_…` key, and supplies the user\nidentity in place of `X-On-Behalf-Of`.\n" } } } ], "roots": [ { "key": "llm.message_published", "kind": "webhook", "title": "llm.message_published", "slug": "/api/events/llm-message-published", "serialization": "proto-names", "schemaName": "LLMMessagePublishedEventWebhook", "direction": "outgoing", "owner": "conversations", "transport": "http-webhook", "producerOperations": [ "conversations:sendMessage", "conversations:sendMessageSync" ], "description": "An assistant/tool message is produced or an assistant message snapshot is updated." }, { "key": "llm.generation_started", "kind": "webhook", "title": "llm.generation_started", "slug": "/api/events/llm-generation-started", "serialization": "proto-names", "schemaName": "LLMGenerationStartedEventWebhook", "direction": "outgoing", "owner": "conversations", "transport": "http-webhook", "producerOperations": [ "conversations:sendMessage", "conversations:sendMessageSync" ], "description": "A generation run starts for a conversation." }, { "key": "llm.generation_completed", "kind": "webhook", "title": "llm.generation_completed", "slug": "/api/events/llm-generation-completed", "serialization": "proto-names", "schemaName": "LLMGenerationCompletedEventWebhook", "direction": "outgoing", "owner": "conversations", "transport": "http-webhook", "producerOperations": [ "conversations:sendMessage", "conversations:sendMessageSync" ], "description": "A generation run reaches a terminal outcome. Inspect status and correlate run_id." }, { "key": "llm.tool_call_started", "kind": "webhook", "title": "llm.tool_call_started", "slug": "/api/events/llm-tool-call-started", "serialization": "proto-names", "schemaName": "ToolCallStartedEventWebhook", "direction": "outgoing", "owner": "delegation-approvals", "transport": "http-webhook", "producerOperations": [ "conversations:sendMessage", "conversations:sendMessageSync" ], "description": "A tool call is dispatched for platform or client execution." }, { "key": "llm.tool_call_approval_required", "kind": "webhook", "title": "llm.tool_call_approval_required", "slug": "/api/events/llm-tool-call-approval-required", "serialization": "proto-names", "schemaName": "ToolCallStartedEventWebhook", "direction": "outgoing", "owner": "delegation-approvals", "transport": "http-webhook", "producerOperations": [ "conversations:sendMessage", "conversations:sendMessageSync" ], "description": "A routed tool call is parked for human approval with a decision deadline." }, { "key": "llm.tool_call_completed", "kind": "webhook", "title": "llm.tool_call_completed", "slug": "/api/events/llm-tool-call-completed", "serialization": "proto-names", "schemaName": "ToolCallCompletedEventWebhook", "direction": "outgoing", "owner": "delegation-approvals", "transport": "http-webhook", "producerOperations": [ "conversations:sendMessage", "conversations:sendMessageSync" ], "description": "A tool call reaches a terminal outcome, including a rejected or timed-out approval." }, { "key": "generation-config", "kind": "configuration", "title": "Generation configuration", "slug": "/managed-agents/conversations/configuration#generation-config", "serialization": "json-names", "schemaName": "GenerationConfigInput", "direction": "request", "description": "Canonical generation configuration\n\nSet 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.\n\nSee [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes." } ], "schemas": { "CreateAgentProfileRequest": { "type": "object", "description": "=== Create ===\nInputs for creating a project-scoped agent profile with prompt and generation settings.", "properties": { "projectId": { "type": "string", "description": "Identifier of the project associated with the operation.", "x-presence": "implicit" }, "profile": { "description": "Agent profile definition to add to the project library.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/AgentProfileInput" } ], "x-protovalidate": { "required": true }, "x-validation-scope": "request" } }, "x-request-required": [ "profile" ], "required": [ "profile" ] }, "AgentProfileInput": { "type": "object", "description": "A reusable persona with model configuration, tools and metadata describing when it should be\nselected.\n\nSee [Profile selection and versioning](/api/agent-profiles/selection-and-versioning) for profile resolution and fragment versions.", "properties": { "profileId": { "type": "string", "description": "Stable id, unique within the project library.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Display name used when selecting an agent profile.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Human-facing summary.", "x-presence": "implicit" }, "whenToUse": { "type": "string", "description": "Routing hint, Skill-style \"use when…\"", "x-presence": "implicit" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords associated with discovery or selection of the agent profile.", "x-presence": "collection" }, "enabled": { "type": "boolean", "description": "Whether the profile is enabled for selection. Omission during creation defaults to true; an\nexplicitly false value creates a disabled profile.", "x-presence": "explicit" }, "generationConfig": { "description": "--- the bundle (reused as-is: model, system_prompt, temperature, …) ---\nModel, sampling, and tool configuration used for generation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GenerationConfigInput" } ] }, "mcpServers": { "type": "array", "items": { "$ref": "#/components/schemas/MCPServerReferenceInput" }, "description": "--- the tool bundle for this profile ---\nDrives per-profile MCP tool discovery; replaces the conversation-wide\nConversationSettings.mcp_servers for turns where this profile is active.", "x-presence": "collection" }, "variableSpecs": { "type": "array", "items": { "$ref": "#/components/schemas/PromptVariableSpecInput" }, "description": "Variables consumed by the profile’s system-prompt template, rendered from the conversation’s\nprompt_variables.", "x-presence": "collection" }, "version": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Output-only immutable revision of the profile. Versions start at one and increase on\nsuccessful mutations; values supplied on writes are ignored.", "x-presence": "implicit" }, "disableDefaultTools": { "type": "boolean", "description": "Exclude the default MCP tool catalog from this profile’s effective server set. When true, only\nthe profile’s configured MCP servers are used.", "x-presence": "implicit" } }, "x-reference-model": { "title": "AgentProfile", "url": "/api/models/agent-profile#request" } }, "GenerationConfigInput": { "type": "object", "description": "Canonical generation configuration\n\nSet 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.\n\nSee [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes.", "properties": { "temperature": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Sampling temperature. Omission inherits the base configuration or provider default; an\nexplicitly supplied zero remains an override.", "x-presence": "explicit" }, "topP": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Cumulative token-probability cutoff used for nucleus sampling.", "x-presence": "explicit" }, "maxOutputTokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum output-token count requested from the model provider.", "x-presence": "explicit" }, "frequencyPenalty": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Sampling penalty applied to tokens according to their prior frequency.", "x-presence": "explicit" }, "presencePenalty": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Sampling penalty applied to tokens already present in generated content.", "x-presence": "explicit" }, "stopSequences": { "type": "array", "items": { "type": "string" }, "description": "Stop tokens/sequences (unchanged).", "x-presence": "collection" }, "seed": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Deterministic control where supported.", "x-presence": "explicit" }, "responseFormat": { "description": "Structured-output format and schema requested for the model response.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ResponseFormatInput" } ] }, "allowParallelToolCalls": { "type": "boolean", "description": "Allow the model to issue multiple tool calls in parallel where supported", "x-presence": "explicit" }, "model": { "type": "string", "description": "Model selection\nPrimary model identifier requested for generation.", "x-presence": "implicit" }, "models": { "type": "array", "items": { "type": "string" }, "description": "Candidate models for routing.", "x-presence": "collection" }, "systemPrompt": { "type": "string", "description": "Optional system prompt prepended as a system message. An explicitly empty value in a per-call\noverride clears the base prompt.", "x-presence": "explicit" }, "modelRoutingFilter": { "description": "Optional metadata-based model routing filter.\nWhen set, candidate models are filtered by these criteria before routing.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ModelRoutingFilterInput" } ] }, "provider": { "description": "Provider/multi-provider routing preferences", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ProviderPreferencesInput" } ] }, "reasoning": { "description": "Reasoning effort and output options passed to the model provider.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ReasoningOptionsInput" } ] }, "usage": { "description": "Token and cost accounting associated with the operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/UsageOptionsInput" } ] }, "transforms": { "type": "array", "items": { "type": "string" }, "description": "Provider transformations requested for the generation input.", "x-presence": "collection" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinitionInput" }, "description": "Tools & tool policy\nTool definitions exposed to the model for server-side execution.", "x-presence": "collection" }, "toolChoice": { "description": "Policy controlling whether and which tool the model may call.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ToolChoiceInput" } ] }, "clientTools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinitionInput" }, "description": "Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)", "x-presence": "collection" }, "toolPolicy": { "description": "Per-run tool execution policy (approvals, ordering, limits, retries, timeouts)", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ToolExecutionPolicyInput" } ] }, "languagePreference": { "type": "string", "nullable": true, "minLength": 2, "pattern": "^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$", "description": "Language preference (BCP-47), e.g., \"en-US\", \"es-ES\" (presence-aware)", "x-presence": "message", "x-protovalidate": { "string": { "minLen": "2", "pattern": "^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$" } }, "x-validation-scope": "request" }, "timeAware": { "description": "Time-aware generation options (current time, message timestamps, file timestamps)", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/TimeAwareConfigInput" } ] }, "turnContext": { "description": "Turn context configuration for turn-aware generation", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/TurnContextConfigInput" } ] }, "mem0": { "description": "Configuration for semantic memory search, context injection and extraction during generation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/MemoryConfigInput" } ] }, "requestTimeoutSeconds": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Timeout for an individual model-provider request, in seconds. Zero selects the 30-second\ndefault; other values are clamped to the range 1–600.", "x-presence": "implicit" }, "fileResolution": { "description": "Configuration for resolving FILE_ID content parts to fresh signed URLs before calling a model\nprovider. When unset, unresolved content is skipped.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/FileResolutionConfigInput" } ] }, "clearTools": { "type": "boolean", "description": "Set to true with an empty tools list in an override to clear inherited tools. An empty list\nalone inherits the base tools. This directive applies only when merging an override.", "x-presence": "implicit" }, "clearClientTools": { "type": "boolean", "description": "Set to true with an empty client tools list in an override to clear inherited client tools for\nthat turn. An empty list alone inherits the base client tools, and a nonempty list replaces\nthem regardless of this directive. It applies only when merging an override and leaves server\ntool selection unchanged.", "x-presence": "implicit" }, "topK": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Additional provider knobs", "x-presence": "explicit" }, "repetitionPenalty": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Provider sampling penalty used to discourage repeated output.", "x-presence": "explicit" }, "logitBias": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ] }, "description": "Per-token adjustments applied to the provider’s token-selection logits.", "x-presence": "collection" }, "topLogprobs": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of top token log probabilities requested from the provider.", "x-presence": "explicit" }, "minP": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Minimum relative token probability used by supported sampling providers.", "x-presence": "explicit" }, "topA": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Adaptive probability cutoff used by supported sampling providers.", "x-presence": "explicit" }, "user": { "type": "string", "description": "User identifier forwarded for provider-side request attribution.", "x-presence": "explicit" }, "modalities": { "type": "array", "items": { "oneOf": [ { "type": "string", "enum": [ "MODALITY_TEXT", "MODALITY_IMAGE", "MODALITY_AUDIO" ], "x-enumDescriptions": { "MODALITY_TEXT": "Request generated text output.", "MODALITY_IMAGE": "Request generated image output where the model supports it.", "MODALITY_AUDIO": "Request generated audio output where the model supports it." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "MODALITY_TEXT", "number": 1, "canonical": true, "description": "Request generated text output." }, { "name": "MODALITY_IMAGE", "number": 2, "canonical": true, "description": "Request generated image output where the model supports it." }, { "name": "MODALITY_AUDIO", "number": 3, "canonical": true, "description": "Request generated audio output where the model supports it." } ], "x-enum-description": "Output media requested from a model that supports that modality.", "description": "Output media requested from a model that supports that modality." }, "description": "Output modalities (e.g., [TEXT, IMAGE])", "x-presence": "collection" }, "plugins": { "type": "array", "items": { "$ref": "#/components/schemas/PluginConfigInput" }, "description": "Provider plugins requested for pre-processing or post-processing.", "x-presence": "collection" } }, "x-reference-model": { "title": "GenerationConfig", "url": "/api/models/generation-config#request" } }, "ResponseFormatInput": { "type": "object", "description": "Structured response control\n\nWhen 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.", "properties": { "jsonObject": { "type": "boolean", "description": "Whether the model provider is requested to return a valid JSON object.", "x-presence": "implicit" }, "jsonSchema": { "type": "object", "additionalProperties": true, "description": "JSON Schema describing the requested structured model output.", "x-presence": "message" }, "schemaName": { "type": "string", "description": "Human-readable name of the structured-output schema, included in structured-message metadata\nand in the provider request’s json_schema.name.", "x-presence": "implicit" }, "validate": { "type": "boolean", "description": "Enable server-side validation of the response against json_schema.\nDefault: true when json_schema is set (applied in Go when not explicitly set).", "x-presence": "explicit" }, "maxValidationRetries": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 3, "description": "Maximum retries when server-side validation fails.\nDefault: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).", "x-presence": "explicit", "x-protovalidate": { "int32": { "lte": 3, "gte": 0 } }, "x-validation-scope": "request" }, "responseHealing": { "type": "boolean", "description": "Enable response healing for structured JSON output. Defaults to enabled for non-streaming\nrequests with json_schema unless explicitly disabled.", "x-presence": "explicit" } }, "x-reference-model": { "title": "ResponseFormat", "url": "/api/models/response-format#request" } }, "ModelRoutingFilterInput": { "type": "object", "description": "ModelRoutingFilter defines metadata-based criteria for filtering model candidates.\nAll filters are ANDed — a model must pass every specified filter.\nUnset/zero-value fields are ignored (no filtering on that dimension).\n\nUnset 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.\n\n[`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.", "properties": { "minContextLength": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Minimum context window (tokens). Models below this are excluded.", "x-presence": "implicit" }, "minMaxCompletionTokens": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Minimum max completion tokens. Models below this are excluded.\nModels reporting 0 (unknown) pass through (permissive).", "x-presence": "implicit" }, "requiredInputModalities": { "type": "array", "items": { "type": "string" }, "description": "Required input modalities (e.g., [\"image\", \"audio\"]). Model must support ALL listed.\nModels with empty input_modalities are filtered out (strict).", "x-presence": "collection" }, "requiredOutputModalities": { "type": "array", "items": { "type": "string" }, "description": "Required output modalities (e.g., [\"image\"]). Model must support ALL listed.\nModels with empty output_modalities are filtered out (strict).", "x-presence": "collection" }, "maxPromptCost": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Maximum cost per prompt token (e.g., 0.000003). 0 = no limit.\nUnparseable pricing strings pass through (permissive).", "x-presence": "implicit" }, "maxCompletionCost": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Maximum cost per completion token. 0 = no limit.\nUnparseable pricing strings pass through (permissive).", "x-presence": "implicit" }, "excludeModerated": { "type": "boolean", "description": "Exclude models with content moderation enabled.", "x-presence": "implicit" }, "requiredParameters": { "type": "array", "items": { "type": "string" }, "description": "Required supported parameters (e.g., [\"tools\", \"response_format\"]).\nModel must support ALL listed.", "x-presence": "collection" } }, "x-reference-model": { "title": "ModelRoutingFilter", "url": "/api/models/model-routing-filter#request" } }, "ProviderPreferencesInput": { "type": "object", "description": "Routing preferences restricting and ordering the model providers eligible for a request.", "properties": { "order": { "type": "array", "items": { "type": "string" }, "description": "Preferred ordering of model providers for routing.", "x-presence": "collection" }, "allowFallbacks": { "type": "boolean", "description": "Whether provider routing may fall back beyond the preferred order.", "x-presence": "implicit" }, "requireParameters": { "type": "boolean", "description": "Whether routing requires providers to support the requested parameters.", "x-presence": "implicit" }, "dataCollection": { "oneOf": [ { "type": "string", "enum": [ "DATA_COLLECTION_MODE_ALLOW", "DATA_COLLECTION_MODE_DENY" ], "x-enumDescriptions": { "DATA_COLLECTION_MODE_ALLOW": "Allow routing to providers that may collect submitted data under their policies.", "DATA_COLLECTION_MODE_DENY": "Request routing only to providers that do not collect submitted data under the routing policy." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "DATA_COLLECTION_MODE_ALLOW", "number": 1, "canonical": true, "description": "Allow routing to providers that may collect submitted data under their policies." }, { "name": "DATA_COLLECTION_MODE_DENY", "number": 2, "canonical": true, "description": "Request routing only to providers that do not collect submitted data under the routing policy." } ], "x-enum-description": "Provider-routing preference for whether providers may collect submitted data.", "description": "Provider data-collection preference used when routing the request.", "x-presence": "implicit" }, "zdr": { "type": "boolean", "description": "Whether routing requests providers offering zero data retention.", "x-presence": "implicit" }, "only": { "type": "array", "items": { "type": "string" }, "description": "Provider identifiers allowed by the routing preference.", "x-presence": "collection" }, "ignore": { "type": "array", "items": { "type": "string" }, "description": "Provider identifiers excluded by the routing preference.", "x-presence": "collection" }, "quantizations": { "type": "array", "items": { "type": "string" }, "description": "Model quantization formats allowed by the routing preference.", "x-presence": "collection" }, "sort": { "oneOf": [ { "type": "string", "enum": [ "PROVIDER_SORT_PRICE", "PROVIDER_SORT_THROUGHPUT", "PROVIDER_SORT_LATENCY" ], "x-enumDescriptions": { "PROVIDER_SORT_PRICE": "Prefer providers with lower price.", "PROVIDER_SORT_THROUGHPUT": "Prefer providers with higher throughput.", "PROVIDER_SORT_LATENCY": "Prefer providers with lower latency." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "PROVIDER_SORT_PRICE", "number": 1, "canonical": true, "description": "Prefer providers with lower price." }, { "name": "PROVIDER_SORT_THROUGHPUT", "number": 2, "canonical": true, "description": "Prefer providers with higher throughput." }, { "name": "PROVIDER_SORT_LATENCY", "number": 3, "canonical": true, "description": "Prefer providers with lower latency." } ], "x-enum-description": "Metric used to order eligible model providers.", "description": "Metric used to order eligible model providers.", "x-presence": "implicit" }, "maxPrice": { "description": "Upper price bounds used when selecting a model provider.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ProviderMaxPriceInput" } ] }, "enforceDistillableText": { "type": "boolean", "description": "Embeddings: enforce distillable text.", "x-presence": "implicit" }, "preferredMinThroughput": { "description": "Deprioritize providers below this throughput (tokens/sec).\nDoes not exclude — just pushes to end of preference list.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PercentileThresholdInput" } ] }, "preferredMaxLatency": { "description": "Deprioritize providers above this latency (ms).", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PercentileThresholdInput" } ] } }, "x-reference-model": { "title": "ProviderPreferences", "url": "/api/models/provider-preferences#request" } }, "ProviderMaxPriceInput": { "type": "object", "description": "Routing / provider preferences (generic superset)", "properties": { "prompt": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "$/1M prompt tokens.", "x-presence": "implicit" }, "completion": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "$/1M completion tokens.", "x-presence": "implicit" }, "request": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Maximum provider cost allowed per request, in US dollars.", "x-presence": "implicit" }, "image": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Maximum provider cost allowed per image, in US dollars.", "x-presence": "implicit" }, "audio": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "$/1M audio tokens.", "x-presence": "implicit" } }, "x-reference-model": { "title": "ProviderMaxPrice", "url": "/api/models/provider-max-price#request" } }, "PercentileThresholdInput": { "type": "object", "description": "Percentile thresholds for provider performance metrics", "properties": { "p50": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Threshold applied to the provider metric’s 50th percentile.", "x-presence": "implicit" }, "p90": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Threshold applied to the provider metric’s 90th percentile.", "x-presence": "implicit" } }, "x-reference-model": { "title": "PercentileThreshold", "url": "/api/models/percentile-threshold#request" } }, "ReasoningOptionsInput": { "type": "object", "description": "Reasoning options\n\nSupported 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.", "properties": { "effort": { "oneOf": [ { "type": "string", "enum": [ "EFFORT_HIGH", "EFFORT_MEDIUM", "EFFORT_LOW", "EFFORT_XHIGH", "EFFORT_MINIMAL", "EFFORT_NONE" ], "x-enumDescriptions": { "EFFORT_HIGH": "Request the provider's high reasoning-effort level.", "EFFORT_MEDIUM": "Request the provider's medium reasoning-effort level.", "EFFORT_LOW": "Request the provider's low reasoning-effort level.", "EFFORT_XHIGH": "Request the provider's extra-high reasoning-effort level where supported.", "EFFORT_MINIMAL": "Request the provider's minimal reasoning-effort level where supported.", "EFFORT_NONE": "Request no reasoning effort where the provider supports disabling it." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "EFFORT_HIGH", "number": 1, "canonical": true, "description": "Request the provider's high reasoning-effort level." }, { "name": "EFFORT_MEDIUM", "number": 2, "canonical": true, "description": "Request the provider's medium reasoning-effort level." }, { "name": "EFFORT_LOW", "number": 3, "canonical": true, "description": "Request the provider's low reasoning-effort level." }, { "name": "EFFORT_XHIGH", "number": 4, "canonical": true, "description": "Request the provider's extra-high reasoning-effort level where supported." }, { "name": "EFFORT_MINIMAL", "number": 5, "canonical": true, "description": "Request the provider's minimal reasoning-effort level where supported." }, { "name": "EFFORT_NONE", "number": 6, "canonical": true, "description": "Request no reasoning effort where the provider supports disabling it." } ], "x-enum-description": "Requested reasoning effort sent to the model provider; supported levels and their effect\ndepend on the chosen model.", "description": "Requested model reasoning effort.", "x-presence": "implicit" }, "maxTokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum reasoning-token count requested from the model provider.", "x-presence": "implicit" }, "exclude": { "type": "boolean", "description": "Whether the provider should omit reasoning content from its response.", "x-presence": "implicit" }, "includeReasoningHistory": { "type": "boolean", "description": "When true (default), reasoning content from previous turns is included\nin multi-turn requests to enable provider continuity.", "x-presence": "implicit" } }, "x-reference-model": { "title": "ReasoningOptions", "url": "/api/models/reasoning-options#request" } }, "UsageOptionsInput": { "type": "object", "description": "Usage accounting preferences", "properties": { "include": { "type": "boolean", "description": "Whether usage accounting should be included in the provider response.", "x-presence": "implicit" } }, "x-reference-model": { "title": "UsageOptions", "url": "/api/models/usage-options#request" } }, "ToolDefinitionInput": { "type": "object", "description": "Canonical tool/function definition used across all services\n\n**[`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.\n\n**[`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.", "properties": { "name": { "type": "string", "minLength": 1, "description": "Name used to select and invoke the tool.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "description": { "type": "string", "minLength": 1, "description": "Explanation of the tool’s purpose supplied to the model and callers.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "parametersJsonSchema": { "type": "object", "additionalProperties": true, "description": "JSON Schema object.", "x-presence": "message" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional tool metadata (version, category, etc.).", "x-presence": "collection" }, "serverId": { "type": "string", "minLength": 1, "description": "Which server provides this tool (for MCP tools).", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tool categorization tags.", "x-presence": "collection" }, "documentationUrl": { "type": "string", "description": "Link to detailed documentation.", "x-presence": "implicit" }, "outputJsonSchema": { "type": "object", "additionalProperties": true, "description": "Optional output schema (JSON Schema serialized as string) describing structured results", "x-presence": "message" } }, "x-reference-model": { "title": "ToolDefinition", "url": "/api/models/tool-definition#request" }, "x-request-required": [ "name", "description", "serverId" ], "required": [ "name", "description", "serverId" ] }, "ToolChoiceInput": { "type": "object", "description": "Policy selecting automatic tool choice, no tool use, or a named tool.", "properties": { "kind": { "oneOf": [ { "type": "string", "enum": [ "TOOL_CHOICE_KIND_AUTO", "TOOL_CHOICE_KIND_NONE", "TOOL_CHOICE_KIND_SPECIFIC" ], "x-enumDescriptions": { "TOOL_CHOICE_KIND_AUTO": "Let the provider decide whether to call an available tool.", "TOOL_CHOICE_KIND_NONE": "Disable tool selection for this generation.", "TOOL_CHOICE_KIND_SPECIFIC": "Require the named tool specified by the enclosing tool-choice configuration." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "TOOL_CHOICE_KIND_AUTO", "number": 1, "canonical": true, "description": "Let the provider decide whether to call an available tool." }, { "name": "TOOL_CHOICE_KIND_NONE", "number": 2, "canonical": true, "description": "Disable tool selection for this generation." }, { "name": "TOOL_CHOICE_KIND_SPECIFIC", "number": 3, "canonical": true, "description": "Require the named tool specified by the enclosing tool-choice configuration." } ], "x-enum-description": "How the model provider should choose whether and which tool to call.", "description": "Discriminator selecting the representation or policy used by this message.", "x-presence": "implicit" }, "specificToolName": { "type": "string", "description": "Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.", "x-presence": "implicit" } }, "x-reference-model": { "title": "ToolChoice", "url": "/api/models/tool-choice#request" } }, "ToolExecutionPolicyInput": { "type": "object", "description": "Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget\nand answer windows. Some stored controls are not enforced by the current workflow.\n\nIf an expected approval does not appear, inspect the tool/server require rules and\nauto-approve exceptions. Auto-approve takes precedence; server IDs are compared\ncase-insensitively after trimming whitespace. An exception does not establish that\nthe user reviewed the action.\n\nAn omitted or zero [`approvalTimeoutMs`](/api/models/tool-execution-policy#request-field-approvaltimeoutms)\nwaits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#request-field-failonapprovaltimeouttoolnamepatterns)\nyields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes\nevery expiry `FAILED`.\n\nThe retry controls [`retriableToolNamePatterns`](/api/models/tool-execution-policy#request-field-retriabletoolnamepatterns),\n[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),\n[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),\n[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and\n[`retryBackoff`](/api/models/tool-execution-policy#request-field-retrybackoff) are\nstored but do not schedule retries. Ordering rules, tie-breaking, the per-loop\ncall cap, client-tool scheduling mode, failure mode and stop-on-failure rules are\nalso not enforced; do not rely on them as execution or safety controls.\n\n[`maxTotalToolCalls`](/api/models/tool-execution-policy#request-field-maxtotaltoolcalls)\nlimits admitted calls across the run; zero or omission leaves the cap unset. A\nclient call consumes budget when armed. A routable MCP call consumes budget before\napproval, including when held for approval or later rejected. Unknown tools and\ncalls refused because the cap is already exhausted do not consume budget. Further\ncalls at the limit receive `FAILED` tool results naming the limit, which the model\ncan use when continuing the run.\n\n[`maxParallelToolCalls`](/api/models/tool-execution-policy#request-field-maxparalleltoolcalls)\nlimits concurrent MCP execution. Zero or one runs MCP calls sequentially; values\ngreater than one permit concurrency. Client calls are armed separately, and your\napplication controls their execution concurrency.\n\nChoose [`clientToolTimeoutMs`](/api/models/tool-execution-policy#request-field-clienttooltimeoutms)\nfor your application's validation and action. Zero or omission gives a five-minute\nanswer window; there is no unbounded setting. Each call returns its resolved\n[`clientToolDeadlineAt`](/api/models/tool-call#response-field-clienttooldeadlineat).\n\nSee [Tool execution policies](/api/tool-execution/policies) for policy selection and\ncaller reconciliation.", "properties": { "requireApprovalToolNamePatterns": { "type": "array", "items": { "type": "string" }, "description": "Approvals\nTool-name patterns selecting calls that require an approval decision.", "x-presence": "collection" }, "requireApprovalServerIds": { "type": "array", "items": { "type": "string" }, "description": "MCP server identifiers whose calls require approval. IDs are compared case-insensitively\nafter trimming whitespace.", "x-presence": "collection" }, "autoApproveToolNamePatterns": { "type": "array", "items": { "type": "string" }, "description": "Tool-name patterns whose matching calls may be approved automatically.", "x-presence": "collection" }, "autoApproveServerIds": { "type": "array", "items": { "type": "string" }, "description": "MCP server identifiers exempted from approval require rules. IDs are compared\ncase-insensitively after trimming whitespace.", "x-presence": "collection" }, "approvalMode": { "oneOf": [ { "type": "string", "enum": [ "APPROVAL_MODE_MIXED", "APPROVAL_MODE_BLOCK_ALL" ], "x-enumDescriptions": { "APPROVAL_MODE_MIXED": "Run automatically approved calls immediately and hold only calls that require approval.", "APPROVAL_MODE_BLOCK_ALL": "Hold execution of all tool calls in the loop until the approval-required calls are approved or\nrejected." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "APPROVAL_MODE_MIXED", "number": 1, "canonical": true, "description": "Run automatically approved calls immediately and hold only calls that require approval." }, { "name": "APPROVAL_MODE_BLOCK_ALL", "number": 2, "canonical": true, "description": "Hold execution of all tool calls in the loop until the approval-required calls are approved or\nrejected." } ], "x-enum-description": "How approval-required tool calls affect other tool calls in the same execution loop.", "description": "How to schedule execution when approvals are required for some tools", "x-presence": "implicit" }, "clientToolMode": { "oneOf": [ { "type": "string", "enum": [ "CLIENT_TOOL_MODE_MIXED", "CLIENT_TOOL_MODE_BLOCK_ALL" ], "x-enumDescriptions": { "CLIENT_TOOL_MODE_MIXED": "Record pending client tools and continue with server-executed MCP tools and the loop.", "CLIENT_TOOL_MODE_BLOCK_ALL": "Hold loop advancement until the caller submits results for all pending client tools." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "CLIENT_TOOL_MODE_MIXED", "number": 1, "canonical": true, "description": "Record pending client tools and continue with server-executed MCP tools and the loop." }, { "name": "CLIENT_TOOL_MODE_BLOCK_ALL", "number": 2, "canonical": true, "description": "Hold loop advancement until the caller submits results for all pending client tools." } ], "x-enum-description": "How unresolved caller-executed tools affect progression of the tool loop.", "description": "Stored requested client-tool scheduling mode; not enforced by the current workflow.", "x-presence": "implicit" }, "approvalTimeoutMs": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Time allowed for an approval decision, in milliseconds. Zero or omission selects the\nfive-minute default; a positive value overrides it. There is no unbounded wait setting.\nAt expiry, matching fail_on_approval_timeout_tool_name_patterns produces FAILED;\nother calls become TIMED_OUT. An empty pattern list makes every expiry FAILED.", "x-presence": "implicit" }, "failOnApprovalTimeoutToolNamePatterns": { "type": "array", "items": { "type": "string" }, "description": "Selects approval timeouts reported as FAILED; nonmatching calls become TIMED_OUT.\nAn empty list makes every approval expiry FAILED. Global failure_mode is not enforced.", "x-presence": "collection" }, "orderRules": { "type": "array", "items": { "$ref": "#/components/schemas/ToolExecutionOrderRuleInput" }, "description": "Stored requested ordering rules; not applied by the current generation workflow.", "x-presence": "collection" }, "stableSortByCallIndexOnTie": { "type": "boolean", "description": "Stored requested ordering tie-breaker; not applied by the current generation workflow.", "x-presence": "implicit" }, "maxParallelToolCalls": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls\nsequentially; larger values permit concurrency. Client calls are armed separately,\nand their execution concurrency is controlled by the caller application.", "x-presence": "implicit" }, "maxToolCallsPerLoop": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Stored requested per-loop tool-call cap; not enforced by the current generation workflow.", "x-presence": "implicit" }, "maxTotalToolCalls": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum admitted tool calls across the run; zero or omission leaves the cap unset.\nClient calls count when armed. Routable MCP calls count before approval, including\ncalls later rejected. Unknown tools and calls refused by an exhausted cap do not count.", "x-presence": "implicit" }, "retriableToolNamePatterns": { "type": "array", "items": { "type": "string" }, "description": "Stored requested retry selection; does not enable retries in the current workflow.", "x-presence": "collection" }, "maxRetries": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Stored requested retry count; does not enable retries in the current workflow.", "x-presence": "implicit" }, "retryBackoff": { "description": "Stored requested retry delays; not applied by the current generation workflow.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/BackoffInput" } ] }, "retryableErrorSubstrings": { "type": "array", "items": { "type": "string" }, "description": "Stored requested retryable-error selection; not evaluated by the current workflow.", "x-presence": "collection" }, "nonRetryableErrorSubstrings": { "type": "array", "items": { "type": "string" }, "description": "Stored requested retry exclusions; not evaluated by the current generation workflow.", "x-presence": "collection" }, "timeouts": { "description": "Timeouts\nOverall execution time budget for the generation run.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/TimeoutPolicyInput" } ] }, "clientToolTimeoutMs": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Time allowed for a client-side tool result, in milliseconds. Zero or omission selects\nthe five-minute default; a positive value overrides it. There is no unbounded wait.\nThe resolved answer deadline is returned as clientToolDeadlineAt on each call.\nA result arriving after the deadline is rejected. At expiry, an empty or matching\nfail_on_approval_timeout_tool_name_patterns list yields FAILED; other calls become TIMED_OUT.\nExpiry closes the answer window and does not cancel a client action already in progress.", "x-presence": "implicit" }, "failureMode": { "oneOf": [ { "type": "string", "enum": [ "FAILURE_MODE_CONTINUE", "FAILURE_MODE_STOP_LOOP", "FAILURE_MODE_STOP_RUN" ], "x-enumDescriptions": { "FAILURE_MODE_CONTINUE": "Request continued processing after the failed tool call.", "FAILURE_MODE_STOP_LOOP": "Request stopping the current tool-execution loop after the failure.", "FAILURE_MODE_STOP_RUN": "Request stopping the generation run after the failure." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "FAILURE_MODE_CONTINUE", "number": 1, "canonical": true, "description": "Request continued processing after the failed tool call." }, { "name": "FAILURE_MODE_STOP_LOOP", "number": 2, "canonical": true, "description": "Request stopping the current tool-execution loop after the failure." }, { "name": "FAILURE_MODE_STOP_RUN", "number": 3, "canonical": true, "description": "Request stopping the generation run after the failure." } ], "x-enum-description": "Requested scope of stopping after a tool execution failure.", "description": "Stored requested failure action; not enforced by the current generation workflow.", "x-presence": "implicit" }, "stopOnFailureRules": { "type": "array", "items": { "$ref": "#/components/schemas/StopOnFailureRuleInput" }, "description": "Stored requested stop rules; not evaluated by the current generation workflow.", "x-presence": "collection" } }, "x-reference-model": { "title": "ToolExecutionPolicy", "url": "/api/models/tool-execution-policy#request" } }, "ToolExecutionOrderRuleInput": { "type": "object", "description": "Requested ordering rule for tool execution. The current generation workflow stores\nthese rules but does not apply their patterns, server filters or weights.", "properties": { "toolNamePatterns": { "type": "array", "items": { "type": "string" }, "description": "Requested tool-name patterns; not evaluated by the current generation workflow.", "x-presence": "collection" }, "serverIds": { "type": "array", "items": { "type": "string" }, "description": "Requested MCP server filter; not evaluated by the current generation workflow.", "x-presence": "collection" }, "weight": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Requested ordering weight; not applied by the current generation workflow.", "x-presence": "implicit" } }, "x-reference-model": { "title": "ToolExecutionOrderRule", "url": "/api/models/tool-execution-order-rule#request" } }, "BackoffInput": { "type": "object", "description": "Requested initial delay, growth factor and upper bound for tool-call retries.\nThe current generation workflow stores this configuration but does not schedule\nretries from it.", "properties": { "initialMs": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Requested initial retry delay in milliseconds; not applied by the current generation workflow.", "x-presence": "implicit" }, "multiplier": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Requested retry-delay multiplier; not applied by the current generation workflow.", "x-presence": "implicit" }, "maxMs": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Requested maximum retry delay in milliseconds; not applied by the current generation workflow.", "x-presence": "implicit" } }, "x-reference-model": { "title": "Backoff", "url": "/api/models/backoff#request" } }, "TimeoutPolicyInput": { "type": "object", "description": "Bounds the run as a whole. This message has no per-tool or per-loop execution\ntimeout. Approval and client-result answer windows are configured separately on\nToolExecutionPolicy; those waits do not cancel an already dispatched remote action.\n\nSet a finite [`timeouts.overallMs`](/api/models/timeout-policy#request-field-overallms)\nwhen the task needs a duration limit. It is measured from run start; zero or\nomission leaves the run-level duration unbounded.\n\nWhen Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and\npending calls can be closed with `endReason: \"run_timed_out\"`. A call still awaiting\napproval has not been dispatched. The timeout does not guarantee a remote action\nstops at that instant, establish whether it took effect, or roll it back.\n\nUse [`endReason`](/api/models/tool-call#response-field-endreason) to distinguish a\nrun deadline from a call's own answer window: an unanswered approval reads\n`approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the\nactual tool status too; approval and client-tool expiry can produce `FAILED` or\n`TIMED_OUT`. Run and individual tool outcomes are different fields.", "properties": { "overallMs": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Overall run budget in milliseconds, measured from run start. Zero or omission\nleaves this run-level bound unset. The workflow checks the deadline and can end\nwith AGENT_STATUS_TIMED_OUT; it cannot cancel or undo a remote action already\ndispatched. Approval and client-result waits retain their separate finite limits.", "x-presence": "implicit" } }, "x-reference-model": { "title": "TimeoutPolicy", "url": "/api/models/timeout-policy#request" } }, "StopOnFailureRuleInput": { "type": "object", "description": "Requested tool-selection rule for handling an execution failure. The current\ngeneration workflow stores these rules but does not evaluate them or stop a loop\nor run because of them.\n\nThe conditions in [`stopOnFailureRules`](/api/models/tool-execution-policy#request-field-stoponfailurerules),\nincluding [`priority`](/api/models/stop-on-failure-rule#request-field-priority),\ntimeout inclusion and error matching, are not enforced. Do not rely on these\nfields as a stop control.", "properties": { "toolNamePatterns": { "type": "array", "items": { "type": "string" }, "description": "Requested tool-name selection; not evaluated by the current generation workflow.", "x-presence": "collection" }, "serverIds": { "type": "array", "items": { "type": "string" }, "description": "Requested MCP server selection; not evaluated by the current generation workflow.", "x-presence": "collection" }, "onFailure": { "oneOf": [ { "type": "string", "enum": [ "FAILURE_MODE_CONTINUE", "FAILURE_MODE_STOP_LOOP", "FAILURE_MODE_STOP_RUN" ], "x-enumDescriptions": { "FAILURE_MODE_CONTINUE": "Request continued processing after the failed tool call.", "FAILURE_MODE_STOP_LOOP": "Request stopping the current tool-execution loop after the failure.", "FAILURE_MODE_STOP_RUN": "Request stopping the generation run after the failure." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "FAILURE_MODE_CONTINUE", "number": 1, "canonical": true, "description": "Request continued processing after the failed tool call." }, { "name": "FAILURE_MODE_STOP_LOOP", "number": 2, "canonical": true, "description": "Request stopping the current tool-execution loop after the failure." }, { "name": "FAILURE_MODE_STOP_RUN", "number": 3, "canonical": true, "description": "Request stopping the generation run after the failure." } ], "x-enum-description": "Requested scope of stopping after a tool execution failure.", "description": "Requested failure action; not evaluated by the current generation workflow.", "x-presence": "implicit" }, "includeTimeouts": { "type": "boolean", "description": "Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.", "x-presence": "implicit" }, "errorSubstrings": { "type": "array", "items": { "type": "string" }, "description": "Requested error-text selection; not evaluated by the current generation workflow.", "x-presence": "collection" }, "priority": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Requested rule priority; not evaluated by the current generation workflow.", "x-presence": "implicit" } }, "x-reference-model": { "title": "StopOnFailureRule", "url": "/api/models/stop-on-failure-rule#request" } }, "TimeAwareConfigInput": { "type": "object", "description": "Configuration for time-aware LLM generation.\nControls injection of temporal context (current time, message timestamps,\nfile timestamps) into the LLM context during generation.", "properties": { "includeCurrentTime": { "type": "boolean", "description": "Append the current date and time to the system prompt as temporal context. Default: true.", "x-presence": "implicit" }, "includeMessageTimestamps": { "type": "boolean", "description": "Include timestamps on messages in the model context. Requires the message timestamp to be\npopulated. Default: false.", "x-presence": "implicit" }, "includeFileTimestamps": { "type": "boolean", "description": "Include upload/modification timestamps when resolving FILE_ID content.\nWhen true, resolved file references include \"[Uploaded: ]\" annotations.\nDefault: false", "x-presence": "implicit" }, "timezone": { "type": "string", "maxLength": 50, "description": "Timezone for formatting (IANA format, e.g., \"America/Los_Angeles\").\nDefault: \"UTC\"", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "50" } }, "x-validation-scope": "request" }, "timestampFormat": { "type": "string", "maxLength": 50, "enum": [ "", "friendly", "iso8601", "date_only" ], "description": "Format pattern for timestamps.\n\"friendly\" (default): \"Jan 2, 2026 at 3:04 PM MST\"\n\"iso8601\": \"2026-01-02T15:04:00-08:00\"\n\"date_only\": \"2026-01-02\"", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "50", "in": [ "", "friendly", "iso8601", "date_only" ] } }, "x-validation-scope": "request" } }, "x-reference-model": { "title": "TimeAwareConfig", "url": "/api/models/time-aware-config#request" } }, "TurnContextConfigInput": { "type": "object", "description": "Configuration for turn-aware LLM generation\n\nTurn 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.", "properties": { "enabled": { "type": "boolean", "description": "Enable turn context injection into system prompt\nDefault: true", "x-presence": "implicit" }, "includeToolGuidance": { "type": "boolean", "description": "Include tool usage guidance based on remaining turns\nDefault: false (can enable for agentic workflows)", "x-presence": "implicit" }, "format": { "type": "string", "enum": [ "minimal", "standard", "verbose" ], "description": "Format for turn context\n\"minimal\": \"[Turn 2/5]\"\n\"standard\": \"[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]\"\n\"verbose\": Includes detailed behavioral guidance\nDefault: \"standard\"", "x-presence": "implicit", "x-protovalidate": { "string": { "in": [ "minimal", "standard", "verbose" ] } }, "x-validation-scope": "request" } }, "x-reference-model": { "title": "TurnContextConfig", "url": "/api/models/turn-context-config#request" }, "x-request-required": [ "format" ], "required": [ "format" ] }, "MemoryConfigInput": { "type": "object", "description": "Configuration for searching, injecting and storing semantic memories during generation.\n\nMemory 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)\n(set at thread creation or via `update-default-generation-config`) or per turn via\n[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).\n\nEnabled 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.\n\nReranking 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.\n\n[`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.", "properties": { "enabled": { "type": "boolean", "description": "Enable searching for relevant memories, adding them to generation context and extracting new\nmemories after generation. Default: false.", "x-presence": "implicit" }, "searchTopK": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of memories to retrieve during search.\nHigher values provide more context but increase token usage.\n\nRange: 1-50 (validated only when enabled = true)\nDefault: 5", "x-presence": "implicit" }, "searchThreshold": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Minimum relevance score threshold for memory search results.\nMemories below this threshold are filtered out.\nRange: 0.0-1.0 (validated only when enabled = true)\nDefault: 0.3", "x-presence": "implicit" }, "injectAsSystemContext": { "type": "boolean", "description": "When true, inject found memories into the system prompt context.\nMemories are formatted as a bullet list under a \"[Relevant memories:]\" header.\nDefault: true", "x-presence": "implicit" }, "searchQueryOverride": { "type": "string", "description": "Custom search query to use instead of the last user message.\nIf empty, the last user message content is used as the search query.", "x-presence": "implicit" }, "enableRerank": { "type": "boolean", "description": "Enable reranking for improved search relevance.\nReranking provides better results but adds latency.\nDefault: false", "x-presence": "implicit" }, "addMemoriesAsync": { "type": "boolean", "description": "When true, memory extraction happens asynchronously after generation completes.\nThis prevents extraction latency from affecting response time.\nDefault: true", "x-presence": "implicit" }, "customExtractionPrompt": { "type": "string", "description": "Custom prompt for memory/fact extraction.\nIf empty, the default extraction prompt is used.\nUse this to customize what types of facts are extracted.", "x-presence": "implicit" }, "enableGraph": { "type": "boolean", "description": "Enable relationship extraction and graph-based memory search when graph memory is configured.\nDefault: false.", "x-presence": "implicit" }, "agentIdOverride": { "type": "string", "description": "Override the agent_id used for memory scoping.\nBy default, the conversation_id is used as the agent_id.\nUse this to share memories across multiple conversations.", "x-presence": "implicit" }, "exposeAsMcpTool": { "type": "boolean", "description": "Expose memory search as an MCP tool during generation.\nWhen true, the LLM can explicitly search memories via tool calls.\nRate limited to 3 searches per generation turn.\nDefault: false", "x-presence": "implicit" }, "includeAssistantMessages": { "type": "boolean", "description": "Include assistant/agent-scoped memories in operations.\nWhen false, skips agent_id for both add and search operations,\nkeeping only user-scoped memories.\nDefault: false", "x-presence": "implicit" }, "injectMemoryTimestamps": { "type": "boolean", "description": "Include created_at/updated_at timestamps on injected memories.\nWhen true, each memory bullet includes a \"(remembered: )\" annotation\nand optionally \"(updated: )\" if the memory was modified after creation.\nDefault: true", "x-presence": "implicit" } }, "x-reference-model": { "title": "MemoryConfig", "url": "/api/models/memory-config#request" }, "x-protovalidate": { "cel": [ { "id": "mem0_config_valid_when_enabled", "message": "search_top_k and search_threshold must be valid when enabled is true", "expression": "!this.enabled || ((this.search_top_k >= 1 && this.search_top_k <= 50) && (this.search_threshold >= 0.0 && this.search_threshold <= 1.0))" } ] }, "x-validation-scope": "request" }, "FileResolutionConfigInput": { "type": "object", "description": "Configuration for resolving CONTENT_PART_TYPE_FILE_ID parts to fresh signed\nURLs before requests are sent to LLM providers. Keeps stable file references\nin message history while generating ephemeral URLs only when needed.\n\nOmitting 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.", "properties": { "failureMode": { "oneOf": [ { "type": "string", "enum": [ "FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION", "FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT" ], "x-enumDescriptions": { "FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION": "Fail generation when a file content part cannot be resolved.", "FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT": "Skip the unresolved content part and continue with the remaining content." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION", "number": 1, "canonical": true, "description": "Fail generation when a file content part cannot be resolved." }, { "name": "FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT", "number": 2, "canonical": true, "description": "Skip the unresolved content part and continue with the remaining content." } ], "x-enum-description": "How generation handles a content part whose file identifier cannot be resolved.", "description": "Action to take when a file cannot be resolved. If omitted, skip unresolved file content\nand use the remaining content.", "x-presence": "implicit" } }, "x-reference-model": { "title": "FileResolutionConfig", "url": "/api/models/file-resolution-config#request" } }, "PluginConfigInput": { "type": "object", "description": "Provider plugin identifier and its parser, search, or additional configuration.", "properties": { "id": { "type": "string", "description": "Provider plugin identifier, such as file-parser.", "x-presence": "implicit" }, "pdf": { "description": "PDF annotation or parser configuration selected by the enclosing message.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PluginPDFConfigInput" } ] }, "web": { "description": "Web-search configuration for the selected generation plugin.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PluginWebConfigInput" } ] }, "params": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional provider-specific plugin parameters.", "x-presence": "collection" } }, "x-reference-model": { "title": "PluginConfig", "url": "/api/models/plugin-config#request" } }, "PluginPDFConfigInput": { "type": "object", "description": "Plugins for pre/post-processing (generic representation)", "properties": { "engine": { "type": "string", "description": "PDF parsing engine selected for the provider plugin.", "x-presence": "implicit" } }, "x-reference-model": { "title": "PluginPDFConfig", "url": "/api/models/plugin-pdf-config#request" } }, "PluginWebConfigInput": { "type": "object", "description": "Provider web-search configuration used to augment a generation request.", "properties": { "engine": { "type": "string", "description": "Search engine selected for the provider’s web-search plugin.", "x-presence": "implicit" }, "maxResults": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum web-search result count requested by the plugin.", "x-presence": "implicit" }, "searchPrompt": { "type": "string", "description": "Instructions supplied to the web-search plugin.", "x-presence": "implicit" }, "webSearchOptions": { "description": "Options controlling the amount of web-search context requested.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/WebSearchOptionsInput" } ] } }, "x-reference-model": { "title": "PluginWebConfig", "url": "/api/models/plugin-web-config#request" } }, "WebSearchOptionsInput": { "type": "object", "description": "Amount of web-search context requested for generation.", "properties": { "searchContextSize": { "type": "string", "description": "Requested amount of web-search context: low, medium, or high.", "x-presence": "implicit" } }, "x-reference-model": { "title": "WebSearchOptions", "url": "/api/models/web-search-options#request" } }, "MCPServerReferenceInput": { "type": "object", "description": "MCP Server Reference\nLightweight reference to pre-configured MCP servers used by workflows", "properties": { "serverId": { "type": "string", "minLength": 1, "description": "ID of pre-configured MCP server (e.g., \"github\", \"filesystem\").", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "enabled": { "type": "boolean", "description": "Whether to use this MCP server. Omission means enabled; only an explicitly false value\nexcludes it from discovery.", "x-presence": "explicit" }, "priority": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Priority override for tool selection (higher = preferred).", "x-presence": "implicit" }, "allowlistToolPatterns": { "type": "array", "items": { "type": "string" }, "description": "Only include tools matching these patterns (e.g., \"github_get_*\", \"search_*\").", "x-presence": "collection" }, "blocklistToolPatterns": { "type": "array", "items": { "type": "string" }, "description": "Exclude tools matching these patterns (e.g., \"*_delete\", \"*_destroy\").", "x-presence": "collection" }, "serverOverrides": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Override server settings for this usage.", "x-presence": "collection" } }, "x-reference-model": { "title": "MCPServerReference", "url": "/api/models/mcp-server-reference#request" }, "x-request-required": [ "serverId" ], "required": [ "serverId" ] }, "PromptVariableSpecInput": { "type": "object", "description": "Declares a variable used by a profile's system-prompt template. Values are supplied\nthrough the conversation's prompt_variables.\n\nWhen creating a conversation with an explicitly selected profile, a\n[`variableSpecs`](/api/models/agent-profile#request-field-variablespecs) entry with\n`required: true` and no nonempty [`defaultValue`](/api/models/prompt-variable-spec#request-field-defaultvalue)\ncauses `MISSING_REQUIRED_PROMPT_VARIABLES` if the variable is missing. Supply the\nvalue at creation. This validation is not repeated for each send or queued turn.\n\nSet intended values explicitly even when the spec declares a default. A nonempty\n`defaultValue` suppresses the creation-time missing-required error but is not\nautomatically inserted into the rendered prompt.", "properties": { "name": { "type": "string", "description": "Variable name referenced by the profile’s system-prompt template.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Console hint + caller documentation.", "x-presence": "implicit" }, "required": { "type": "boolean", "description": "Whether a value is required for a profile explicitly selected at conversation creation.\nThe current validation does not run for every send or queued turn.", "x-presence": "implicit" }, "defaultValue": { "type": "string", "description": "A nonempty value suppresses the creation-time missing-required error. It is not\nautomatically inserted into the rendered prompt; supply intended values explicitly.", "x-presence": "implicit" }, "type": { "oneOf": [ { "type": "string", "enum": [ "VAR_TYPE_STRING", "VAR_TYPE_NUMBER", "VAR_TYPE_BOOL", "VAR_TYPE_LIST" ], "x-enumDescriptions": { "VAR_TYPE_STRING": "Treat the variable as text in the template context.", "VAR_TYPE_NUMBER": "Coerce the variable to a numeric value for arithmetic or numeric comparisons.", "VAR_TYPE_BOOL": "Coerce the variable to a boolean for template conditions.", "VAR_TYPE_LIST": "Provide a list that templates can iterate or join." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "VAR_TYPE_STRING", "number": 1, "canonical": true, "description": "Treat the variable as text in the template context." }, { "name": "VAR_TYPE_NUMBER", "number": 2, "canonical": true, "description": "Coerce the variable to a numeric value for arithmetic or numeric comparisons." }, { "name": "VAR_TYPE_BOOL", "number": 3, "canonical": true, "description": "Coerce the variable to a boolean for template conditions." }, { "name": "VAR_TYPE_LIST", "number": 4, "canonical": true, "description": "Provide a list that templates can iterate or join." } ], "x-enum-description": "Type used to coerce a prompt variable before placing it in the template context.", "description": "\"\" preserves the missing→empty behavior", "x-presence": "implicit" } }, "x-reference-model": { "title": "PromptVariableSpec", "url": "/api/models/prompt-variable-spec#request" } }, "CreateAgentProfileResponse": { "type": "object", "description": "Result payload for creating a project-scoped agent profile with prompt and generation settings.", "properties": { "profile": { "description": "Echoes the stored profile.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/AgentProfile" } ] } } }, "AgentProfile": { "type": "object", "description": "A reusable persona with model configuration, tools and metadata describing when it should be\nselected.\n\nSee [Profile selection and versioning](/api/agent-profiles/selection-and-versioning) for profile resolution and fragment versions.", "properties": { "profileId": { "type": "string", "description": "Stable id, unique within the project library.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Display name used when selecting an agent profile.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Human-facing summary.", "x-presence": "implicit" }, "whenToUse": { "type": "string", "description": "Routing hint, Skill-style \"use when…\"", "x-presence": "implicit" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords associated with discovery or selection of the agent profile.", "x-presence": "collection" }, "enabled": { "type": "boolean", "description": "Whether the profile is enabled for selection. Omission during creation defaults to true; an\nexplicitly false value creates a disabled profile.", "x-presence": "explicit" }, "generationConfig": { "description": "--- the bundle (reused as-is: model, system_prompt, temperature, …) ---\nModel, sampling, and tool configuration used for generation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GenerationConfig" } ] }, "mcpServers": { "type": "array", "items": { "$ref": "#/components/schemas/MCPServerReference" }, "description": "--- the tool bundle for this profile ---\nDrives per-profile MCP tool discovery; replaces the conversation-wide\nConversationSettings.mcp_servers for turns where this profile is active.", "x-presence": "collection" }, "variableSpecs": { "type": "array", "items": { "$ref": "#/components/schemas/PromptVariableSpec" }, "description": "Variables consumed by the profile’s system-prompt template, rendered from the conversation’s\nprompt_variables.", "x-presence": "collection" }, "version": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Output-only immutable revision of the profile. Versions start at one and increase on\nsuccessful mutations; values supplied on writes are ignored.", "x-presence": "implicit" }, "disableDefaultTools": { "type": "boolean", "description": "Exclude the default MCP tool catalog from this profile’s effective server set. When true, only\nthe profile’s configured MCP servers are used.", "x-presence": "implicit" } }, "x-reference-model": { "title": "AgentProfile", "url": "/api/models/agent-profile#response" } }, "GenerationConfig": { "type": "object", "description": "Canonical generation configuration\n\nSet 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.\n\nSee [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes.", "properties": { "temperature": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Sampling temperature. Omission inherits the base configuration or provider default; an\nexplicitly supplied zero remains an override.", "x-presence": "explicit" }, "topP": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Cumulative token-probability cutoff used for nucleus sampling.", "x-presence": "explicit" }, "maxOutputTokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum output-token count requested from the model provider.", "x-presence": "explicit" }, "frequencyPenalty": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Sampling penalty applied to tokens according to their prior frequency.", "x-presence": "explicit" }, "presencePenalty": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Sampling penalty applied to tokens already present in generated content.", "x-presence": "explicit" }, "stopSequences": { "type": "array", "items": { "type": "string" }, "description": "Stop tokens/sequences (unchanged).", "x-presence": "collection" }, "seed": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Deterministic control where supported.", "x-presence": "explicit" }, "responseFormat": { "description": "Structured-output format and schema requested for the model response.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ResponseFormat" } ] }, "allowParallelToolCalls": { "type": "boolean", "description": "Allow the model to issue multiple tool calls in parallel where supported", "x-presence": "explicit" }, "model": { "type": "string", "description": "Model selection\nPrimary model identifier requested for generation.", "x-presence": "implicit" }, "models": { "type": "array", "items": { "type": "string" }, "description": "Candidate models for routing.", "x-presence": "collection" }, "systemPrompt": { "type": "string", "description": "Optional system prompt prepended as a system message. An explicitly empty value in a per-call\noverride clears the base prompt.", "x-presence": "explicit" }, "modelRoutingFilter": { "description": "Optional metadata-based model routing filter.\nWhen set, candidate models are filtered by these criteria before routing.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ModelRoutingFilter" } ] }, "provider": { "description": "Provider/multi-provider routing preferences", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ProviderPreferences" } ] }, "reasoning": { "description": "Reasoning effort and output options passed to the model provider.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ReasoningOptions" } ] }, "usage": { "description": "Token and cost accounting associated with the operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/UsageOptions" } ] }, "transforms": { "type": "array", "items": { "type": "string" }, "description": "Provider transformations requested for the generation input.", "x-presence": "collection" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinition" }, "description": "Tools & tool policy\nTool definitions exposed to the model for server-side execution.", "x-presence": "collection" }, "toolChoice": { "description": "Policy controlling whether and which tool the model may call.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ToolChoice" } ] }, "clientTools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinition" }, "description": "Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)", "x-presence": "collection" }, "toolPolicy": { "description": "Per-run tool execution policy (approvals, ordering, limits, retries, timeouts)", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ToolExecutionPolicy" } ] }, "languagePreference": { "type": "string", "nullable": true, "description": "Language preference (BCP-47), e.g., \"en-US\", \"es-ES\" (presence-aware)", "x-presence": "message", "x-protovalidate": { "string": { "minLen": "2", "pattern": "^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$" } }, "x-validation-scope": "request" }, "timeAware": { "description": "Time-aware generation options (current time, message timestamps, file timestamps)", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/TimeAwareConfig" } ] }, "turnContext": { "description": "Turn context configuration for turn-aware generation", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/TurnContextConfig" } ] }, "mem0": { "description": "Configuration for semantic memory search, context injection and extraction during generation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/MemoryConfig" } ] }, "requestTimeoutSeconds": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Timeout for an individual model-provider request, in seconds. Zero selects the 30-second\ndefault; other values are clamped to the range 1–600.", "x-presence": "implicit" }, "fileResolution": { "description": "Configuration for resolving FILE_ID content parts to fresh signed URLs before calling a model\nprovider. When unset, unresolved content is skipped.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/FileResolutionConfig" } ] }, "clearTools": { "type": "boolean", "description": "Set to true with an empty tools list in an override to clear inherited tools. An empty list\nalone inherits the base tools. This directive applies only when merging an override.", "x-presence": "implicit" }, "clearClientTools": { "type": "boolean", "description": "Set to true with an empty client tools list in an override to clear inherited client tools for\nthat turn. An empty list alone inherits the base client tools, and a nonempty list replaces\nthem regardless of this directive. It applies only when merging an override and leaves server\ntool selection unchanged.", "x-presence": "implicit" }, "topK": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Additional provider knobs", "x-presence": "explicit" }, "repetitionPenalty": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Provider sampling penalty used to discourage repeated output.", "x-presence": "explicit" }, "logitBias": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ] }, "description": "Per-token adjustments applied to the provider’s token-selection logits.", "x-presence": "collection" }, "topLogprobs": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of top token log probabilities requested from the provider.", "x-presence": "explicit" }, "minP": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Minimum relative token probability used by supported sampling providers.", "x-presence": "explicit" }, "topA": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Adaptive probability cutoff used by supported sampling providers.", "x-presence": "explicit" }, "user": { "type": "string", "description": "User identifier forwarded for provider-side request attribution.", "x-presence": "explicit" }, "modalities": { "type": "array", "items": { "oneOf": [ { "type": "string", "enum": [ "MODALITY_TEXT", "MODALITY_IMAGE", "MODALITY_AUDIO" ], "x-enumDescriptions": { "MODALITY_TEXT": "Request generated text output.", "MODALITY_IMAGE": "Request generated image output where the model supports it.", "MODALITY_AUDIO": "Request generated audio output where the model supports it." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "MODALITY_TEXT", "number": 1, "canonical": true, "description": "Request generated text output." }, { "name": "MODALITY_IMAGE", "number": 2, "canonical": true, "description": "Request generated image output where the model supports it." }, { "name": "MODALITY_AUDIO", "number": 3, "canonical": true, "description": "Request generated audio output where the model supports it." } ], "x-enum-description": "Output media requested from a model that supports that modality.", "description": "Output media requested from a model that supports that modality." }, "description": "Output modalities (e.g., [TEXT, IMAGE])", "x-presence": "collection" }, "plugins": { "type": "array", "items": { "$ref": "#/components/schemas/PluginConfig" }, "description": "Provider plugins requested for pre-processing or post-processing.", "x-presence": "collection" } }, "x-reference-model": { "title": "GenerationConfig", "url": "/api/models/generation-config#response" } }, "ResponseFormat": { "type": "object", "description": "Structured response control\n\nWhen 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.", "properties": { "jsonObject": { "type": "boolean", "description": "Whether the model provider is requested to return a valid JSON object.", "x-presence": "implicit" }, "jsonSchema": { "type": "object", "additionalProperties": true, "description": "JSON Schema describing the requested structured model output.", "x-presence": "message" }, "schemaName": { "type": "string", "description": "Human-readable name of the structured-output schema, included in structured-message metadata\nand in the provider request’s json_schema.name.", "x-presence": "implicit" }, "validate": { "type": "boolean", "description": "Enable server-side validation of the response against json_schema.\nDefault: true when json_schema is set (applied in Go when not explicitly set).", "x-presence": "explicit" }, "maxValidationRetries": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum retries when server-side validation fails.\nDefault: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).", "x-presence": "explicit", "x-protovalidate": { "int32": { "lte": 3, "gte": 0 } }, "x-validation-scope": "request" }, "responseHealing": { "type": "boolean", "description": "Enable response healing for structured JSON output. Defaults to enabled for non-streaming\nrequests with json_schema unless explicitly disabled.", "x-presence": "explicit" } }, "x-reference-model": { "title": "ResponseFormat", "url": "/api/models/response-format#response" } }, "ModelRoutingFilter": { "type": "object", "description": "ModelRoutingFilter defines metadata-based criteria for filtering model candidates.\nAll filters are ANDed — a model must pass every specified filter.\nUnset/zero-value fields are ignored (no filtering on that dimension).\n\nUnset 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.\n\n[`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.", "properties": { "minContextLength": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Minimum context window (tokens). Models below this are excluded.", "x-presence": "implicit" }, "minMaxCompletionTokens": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Minimum max completion tokens. Models below this are excluded.\nModels reporting 0 (unknown) pass through (permissive).", "x-presence": "implicit" }, "requiredInputModalities": { "type": "array", "items": { "type": "string" }, "description": "Required input modalities (e.g., [\"image\", \"audio\"]). Model must support ALL listed.\nModels with empty input_modalities are filtered out (strict).", "x-presence": "collection" }, "requiredOutputModalities": { "type": "array", "items": { "type": "string" }, "description": "Required output modalities (e.g., [\"image\"]). Model must support ALL listed.\nModels with empty output_modalities are filtered out (strict).", "x-presence": "collection" }, "maxPromptCost": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Maximum cost per prompt token (e.g., 0.000003). 0 = no limit.\nUnparseable pricing strings pass through (permissive).", "x-presence": "implicit" }, "maxCompletionCost": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Maximum cost per completion token. 0 = no limit.\nUnparseable pricing strings pass through (permissive).", "x-presence": "implicit" }, "excludeModerated": { "type": "boolean", "description": "Exclude models with content moderation enabled.", "x-presence": "implicit" }, "requiredParameters": { "type": "array", "items": { "type": "string" }, "description": "Required supported parameters (e.g., [\"tools\", \"response_format\"]).\nModel must support ALL listed.", "x-presence": "collection" } }, "x-reference-model": { "title": "ModelRoutingFilter", "url": "/api/models/model-routing-filter#response" } }, "ProviderPreferences": { "type": "object", "description": "Routing preferences restricting and ordering the model providers eligible for a request.", "properties": { "order": { "type": "array", "items": { "type": "string" }, "description": "Preferred ordering of model providers for routing.", "x-presence": "collection" }, "allowFallbacks": { "type": "boolean", "description": "Whether provider routing may fall back beyond the preferred order.", "x-presence": "implicit" }, "requireParameters": { "type": "boolean", "description": "Whether routing requires providers to support the requested parameters.", "x-presence": "implicit" }, "dataCollection": { "oneOf": [ { "type": "string", "enum": [ "DATA_COLLECTION_MODE_ALLOW", "DATA_COLLECTION_MODE_DENY" ], "x-enumDescriptions": { "DATA_COLLECTION_MODE_ALLOW": "Allow routing to providers that may collect submitted data under their policies.", "DATA_COLLECTION_MODE_DENY": "Request routing only to providers that do not collect submitted data under the routing policy." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "DATA_COLLECTION_MODE_ALLOW", "number": 1, "canonical": true, "description": "Allow routing to providers that may collect submitted data under their policies." }, { "name": "DATA_COLLECTION_MODE_DENY", "number": 2, "canonical": true, "description": "Request routing only to providers that do not collect submitted data under the routing policy." } ], "x-enum-description": "Provider-routing preference for whether providers may collect submitted data.", "description": "Provider data-collection preference used when routing the request.", "x-presence": "implicit" }, "zdr": { "type": "boolean", "description": "Whether routing requests providers offering zero data retention.", "x-presence": "implicit" }, "only": { "type": "array", "items": { "type": "string" }, "description": "Provider identifiers allowed by the routing preference.", "x-presence": "collection" }, "ignore": { "type": "array", "items": { "type": "string" }, "description": "Provider identifiers excluded by the routing preference.", "x-presence": "collection" }, "quantizations": { "type": "array", "items": { "type": "string" }, "description": "Model quantization formats allowed by the routing preference.", "x-presence": "collection" }, "sort": { "oneOf": [ { "type": "string", "enum": [ "PROVIDER_SORT_PRICE", "PROVIDER_SORT_THROUGHPUT", "PROVIDER_SORT_LATENCY" ], "x-enumDescriptions": { "PROVIDER_SORT_PRICE": "Prefer providers with lower price.", "PROVIDER_SORT_THROUGHPUT": "Prefer providers with higher throughput.", "PROVIDER_SORT_LATENCY": "Prefer providers with lower latency." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "PROVIDER_SORT_PRICE", "number": 1, "canonical": true, "description": "Prefer providers with lower price." }, { "name": "PROVIDER_SORT_THROUGHPUT", "number": 2, "canonical": true, "description": "Prefer providers with higher throughput." }, { "name": "PROVIDER_SORT_LATENCY", "number": 3, "canonical": true, "description": "Prefer providers with lower latency." } ], "x-enum-description": "Metric used to order eligible model providers.", "description": "Metric used to order eligible model providers.", "x-presence": "implicit" }, "maxPrice": { "description": "Upper price bounds used when selecting a model provider.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ProviderMaxPrice" } ] }, "enforceDistillableText": { "type": "boolean", "description": "Embeddings: enforce distillable text.", "x-presence": "implicit" }, "preferredMinThroughput": { "description": "Deprioritize providers below this throughput (tokens/sec).\nDoes not exclude — just pushes to end of preference list.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PercentileThreshold" } ] }, "preferredMaxLatency": { "description": "Deprioritize providers above this latency (ms).", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PercentileThreshold" } ] } }, "x-reference-model": { "title": "ProviderPreferences", "url": "/api/models/provider-preferences#response" } }, "ProviderMaxPrice": { "type": "object", "description": "Routing / provider preferences (generic superset)", "properties": { "prompt": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "$/1M prompt tokens.", "x-presence": "implicit" }, "completion": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "$/1M completion tokens.", "x-presence": "implicit" }, "request": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Maximum provider cost allowed per request, in US dollars.", "x-presence": "implicit" }, "image": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Maximum provider cost allowed per image, in US dollars.", "x-presence": "implicit" }, "audio": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "$/1M audio tokens.", "x-presence": "implicit" } }, "x-reference-model": { "title": "ProviderMaxPrice", "url": "/api/models/provider-max-price#response" } }, "PercentileThreshold": { "type": "object", "description": "Percentile thresholds for provider performance metrics", "properties": { "p50": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Threshold applied to the provider metric’s 50th percentile.", "x-presence": "implicit" }, "p90": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Threshold applied to the provider metric’s 90th percentile.", "x-presence": "implicit" } }, "x-reference-model": { "title": "PercentileThreshold", "url": "/api/models/percentile-threshold#response" } }, "ReasoningOptions": { "type": "object", "description": "Reasoning options\n\nSupported 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.", "properties": { "effort": { "oneOf": [ { "type": "string", "enum": [ "EFFORT_HIGH", "EFFORT_MEDIUM", "EFFORT_LOW", "EFFORT_XHIGH", "EFFORT_MINIMAL", "EFFORT_NONE" ], "x-enumDescriptions": { "EFFORT_HIGH": "Request the provider's high reasoning-effort level.", "EFFORT_MEDIUM": "Request the provider's medium reasoning-effort level.", "EFFORT_LOW": "Request the provider's low reasoning-effort level.", "EFFORT_XHIGH": "Request the provider's extra-high reasoning-effort level where supported.", "EFFORT_MINIMAL": "Request the provider's minimal reasoning-effort level where supported.", "EFFORT_NONE": "Request no reasoning effort where the provider supports disabling it." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "EFFORT_HIGH", "number": 1, "canonical": true, "description": "Request the provider's high reasoning-effort level." }, { "name": "EFFORT_MEDIUM", "number": 2, "canonical": true, "description": "Request the provider's medium reasoning-effort level." }, { "name": "EFFORT_LOW", "number": 3, "canonical": true, "description": "Request the provider's low reasoning-effort level." }, { "name": "EFFORT_XHIGH", "number": 4, "canonical": true, "description": "Request the provider's extra-high reasoning-effort level where supported." }, { "name": "EFFORT_MINIMAL", "number": 5, "canonical": true, "description": "Request the provider's minimal reasoning-effort level where supported." }, { "name": "EFFORT_NONE", "number": 6, "canonical": true, "description": "Request no reasoning effort where the provider supports disabling it." } ], "x-enum-description": "Requested reasoning effort sent to the model provider; supported levels and their effect\ndepend on the chosen model.", "description": "Requested model reasoning effort.", "x-presence": "implicit" }, "maxTokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum reasoning-token count requested from the model provider.", "x-presence": "implicit" }, "exclude": { "type": "boolean", "description": "Whether the provider should omit reasoning content from its response.", "x-presence": "implicit" }, "includeReasoningHistory": { "type": "boolean", "description": "When true (default), reasoning content from previous turns is included\nin multi-turn requests to enable provider continuity.", "x-presence": "implicit" } }, "x-reference-model": { "title": "ReasoningOptions", "url": "/api/models/reasoning-options#response" } }, "UsageOptions": { "type": "object", "description": "Usage accounting preferences", "properties": { "include": { "type": "boolean", "description": "Whether usage accounting should be included in the provider response.", "x-presence": "implicit" } }, "x-reference-model": { "title": "UsageOptions", "url": "/api/models/usage-options#response" } }, "ToolDefinition": { "type": "object", "description": "Canonical tool/function definition used across all services\n\n**[`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.\n\n**[`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.", "properties": { "name": { "type": "string", "description": "Name used to select and invoke the tool.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "description": { "type": "string", "description": "Explanation of the tool’s purpose supplied to the model and callers.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "parametersJsonSchema": { "type": "object", "additionalProperties": true, "description": "JSON Schema object.", "x-presence": "message" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional tool metadata (version, category, etc.).", "x-presence": "collection" }, "serverId": { "type": "string", "description": "Which server provides this tool (for MCP tools).", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tool categorization tags.", "x-presence": "collection" }, "documentationUrl": { "type": "string", "description": "Link to detailed documentation.", "x-presence": "implicit" }, "outputJsonSchema": { "type": "object", "additionalProperties": true, "description": "Optional output schema (JSON Schema serialized as string) describing structured results", "x-presence": "message" } }, "x-reference-model": { "title": "ToolDefinition", "url": "/api/models/tool-definition#response" }, "x-request-required": [ "name", "description", "serverId" ] }, "ToolChoice": { "type": "object", "description": "Policy selecting automatic tool choice, no tool use, or a named tool.", "properties": { "kind": { "oneOf": [ { "type": "string", "enum": [ "TOOL_CHOICE_KIND_AUTO", "TOOL_CHOICE_KIND_NONE", "TOOL_CHOICE_KIND_SPECIFIC" ], "x-enumDescriptions": { "TOOL_CHOICE_KIND_AUTO": "Let the provider decide whether to call an available tool.", "TOOL_CHOICE_KIND_NONE": "Disable tool selection for this generation.", "TOOL_CHOICE_KIND_SPECIFIC": "Require the named tool specified by the enclosing tool-choice configuration." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "TOOL_CHOICE_KIND_AUTO", "number": 1, "canonical": true, "description": "Let the provider decide whether to call an available tool." }, { "name": "TOOL_CHOICE_KIND_NONE", "number": 2, "canonical": true, "description": "Disable tool selection for this generation." }, { "name": "TOOL_CHOICE_KIND_SPECIFIC", "number": 3, "canonical": true, "description": "Require the named tool specified by the enclosing tool-choice configuration." } ], "x-enum-description": "How the model provider should choose whether and which tool to call.", "description": "Discriminator selecting the representation or policy used by this message.", "x-presence": "implicit" }, "specificToolName": { "type": "string", "description": "Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.", "x-presence": "implicit" } }, "x-reference-model": { "title": "ToolChoice", "url": "/api/models/tool-choice#response" } }, "ToolExecutionPolicy": { "type": "object", "description": "Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget\nand answer windows. Some stored controls are not enforced by the current workflow.\n\nIf an expected approval does not appear, inspect the tool/server require rules and\nauto-approve exceptions. Auto-approve takes precedence; server IDs are compared\ncase-insensitively after trimming whitespace. An exception does not establish that\nthe user reviewed the action.\n\nAn omitted or zero [`approvalTimeoutMs`](/api/models/tool-execution-policy#request-field-approvaltimeoutms)\nwaits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#request-field-failonapprovaltimeouttoolnamepatterns)\nyields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes\nevery expiry `FAILED`.\n\nThe retry controls [`retriableToolNamePatterns`](/api/models/tool-execution-policy#request-field-retriabletoolnamepatterns),\n[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),\n[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),\n[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and\n[`retryBackoff`](/api/models/tool-execution-policy#request-field-retrybackoff) are\nstored but do not schedule retries. Ordering rules, tie-breaking, the per-loop\ncall cap, client-tool scheduling mode, failure mode and stop-on-failure rules are\nalso not enforced; do not rely on them as execution or safety controls.\n\n[`maxTotalToolCalls`](/api/models/tool-execution-policy#request-field-maxtotaltoolcalls)\nlimits admitted calls across the run; zero or omission leaves the cap unset. A\nclient call consumes budget when armed. A routable MCP call consumes budget before\napproval, including when held for approval or later rejected. Unknown tools and\ncalls refused because the cap is already exhausted do not consume budget. Further\ncalls at the limit receive `FAILED` tool results naming the limit, which the model\ncan use when continuing the run.\n\n[`maxParallelToolCalls`](/api/models/tool-execution-policy#request-field-maxparalleltoolcalls)\nlimits concurrent MCP execution. Zero or one runs MCP calls sequentially; values\ngreater than one permit concurrency. Client calls are armed separately, and your\napplication controls their execution concurrency.\n\nChoose [`clientToolTimeoutMs`](/api/models/tool-execution-policy#request-field-clienttooltimeoutms)\nfor your application's validation and action. Zero or omission gives a five-minute\nanswer window; there is no unbounded setting. Each call returns its resolved\n[`clientToolDeadlineAt`](/api/models/tool-call#response-field-clienttooldeadlineat).\n\nSee [Tool execution policies](/api/tool-execution/policies) for policy selection and\ncaller reconciliation.", "properties": { "requireApprovalToolNamePatterns": { "type": "array", "items": { "type": "string" }, "description": "Approvals\nTool-name patterns selecting calls that require an approval decision.", "x-presence": "collection" }, "requireApprovalServerIds": { "type": "array", "items": { "type": "string" }, "description": "MCP server identifiers whose calls require approval. IDs are compared case-insensitively\nafter trimming whitespace.", "x-presence": "collection" }, "autoApproveToolNamePatterns": { "type": "array", "items": { "type": "string" }, "description": "Tool-name patterns whose matching calls may be approved automatically.", "x-presence": "collection" }, "autoApproveServerIds": { "type": "array", "items": { "type": "string" }, "description": "MCP server identifiers exempted from approval require rules. IDs are compared\ncase-insensitively after trimming whitespace.", "x-presence": "collection" }, "approvalMode": { "oneOf": [ { "type": "string", "enum": [ "APPROVAL_MODE_MIXED", "APPROVAL_MODE_BLOCK_ALL" ], "x-enumDescriptions": { "APPROVAL_MODE_MIXED": "Run automatically approved calls immediately and hold only calls that require approval.", "APPROVAL_MODE_BLOCK_ALL": "Hold execution of all tool calls in the loop until the approval-required calls are approved or\nrejected." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "APPROVAL_MODE_MIXED", "number": 1, "canonical": true, "description": "Run automatically approved calls immediately and hold only calls that require approval." }, { "name": "APPROVAL_MODE_BLOCK_ALL", "number": 2, "canonical": true, "description": "Hold execution of all tool calls in the loop until the approval-required calls are approved or\nrejected." } ], "x-enum-description": "How approval-required tool calls affect other tool calls in the same execution loop.", "description": "How to schedule execution when approvals are required for some tools", "x-presence": "implicit" }, "clientToolMode": { "oneOf": [ { "type": "string", "enum": [ "CLIENT_TOOL_MODE_MIXED", "CLIENT_TOOL_MODE_BLOCK_ALL" ], "x-enumDescriptions": { "CLIENT_TOOL_MODE_MIXED": "Record pending client tools and continue with server-executed MCP tools and the loop.", "CLIENT_TOOL_MODE_BLOCK_ALL": "Hold loop advancement until the caller submits results for all pending client tools." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "CLIENT_TOOL_MODE_MIXED", "number": 1, "canonical": true, "description": "Record pending client tools and continue with server-executed MCP tools and the loop." }, { "name": "CLIENT_TOOL_MODE_BLOCK_ALL", "number": 2, "canonical": true, "description": "Hold loop advancement until the caller submits results for all pending client tools." } ], "x-enum-description": "How unresolved caller-executed tools affect progression of the tool loop.", "description": "Stored requested client-tool scheduling mode; not enforced by the current workflow.", "x-presence": "implicit" }, "approvalTimeoutMs": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Time allowed for an approval decision, in milliseconds. Zero or omission selects the\nfive-minute default; a positive value overrides it. There is no unbounded wait setting.\nAt expiry, matching fail_on_approval_timeout_tool_name_patterns produces FAILED;\nother calls become TIMED_OUT. An empty pattern list makes every expiry FAILED.", "x-presence": "implicit" }, "failOnApprovalTimeoutToolNamePatterns": { "type": "array", "items": { "type": "string" }, "description": "Selects approval timeouts reported as FAILED; nonmatching calls become TIMED_OUT.\nAn empty list makes every approval expiry FAILED. Global failure_mode is not enforced.", "x-presence": "collection" }, "orderRules": { "type": "array", "items": { "$ref": "#/components/schemas/ToolExecutionOrderRule" }, "description": "Stored requested ordering rules; not applied by the current generation workflow.", "x-presence": "collection" }, "stableSortByCallIndexOnTie": { "type": "boolean", "description": "Stored requested ordering tie-breaker; not applied by the current generation workflow.", "x-presence": "implicit" }, "maxParallelToolCalls": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls\nsequentially; larger values permit concurrency. Client calls are armed separately,\nand their execution concurrency is controlled by the caller application.", "x-presence": "implicit" }, "maxToolCallsPerLoop": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Stored requested per-loop tool-call cap; not enforced by the current generation workflow.", "x-presence": "implicit" }, "maxTotalToolCalls": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum admitted tool calls across the run; zero or omission leaves the cap unset.\nClient calls count when armed. Routable MCP calls count before approval, including\ncalls later rejected. Unknown tools and calls refused by an exhausted cap do not count.", "x-presence": "implicit" }, "retriableToolNamePatterns": { "type": "array", "items": { "type": "string" }, "description": "Stored requested retry selection; does not enable retries in the current workflow.", "x-presence": "collection" }, "maxRetries": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Stored requested retry count; does not enable retries in the current workflow.", "x-presence": "implicit" }, "retryBackoff": { "description": "Stored requested retry delays; not applied by the current generation workflow.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/Backoff" } ] }, "retryableErrorSubstrings": { "type": "array", "items": { "type": "string" }, "description": "Stored requested retryable-error selection; not evaluated by the current workflow.", "x-presence": "collection" }, "nonRetryableErrorSubstrings": { "type": "array", "items": { "type": "string" }, "description": "Stored requested retry exclusions; not evaluated by the current generation workflow.", "x-presence": "collection" }, "timeouts": { "description": "Timeouts\nOverall execution time budget for the generation run.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/TimeoutPolicy" } ] }, "clientToolTimeoutMs": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Time allowed for a client-side tool result, in milliseconds. Zero or omission selects\nthe five-minute default; a positive value overrides it. There is no unbounded wait.\nThe resolved answer deadline is returned as clientToolDeadlineAt on each call.\nA result arriving after the deadline is rejected. At expiry, an empty or matching\nfail_on_approval_timeout_tool_name_patterns list yields FAILED; other calls become TIMED_OUT.\nExpiry closes the answer window and does not cancel a client action already in progress.", "x-presence": "implicit" }, "failureMode": { "oneOf": [ { "type": "string", "enum": [ "FAILURE_MODE_CONTINUE", "FAILURE_MODE_STOP_LOOP", "FAILURE_MODE_STOP_RUN" ], "x-enumDescriptions": { "FAILURE_MODE_CONTINUE": "Request continued processing after the failed tool call.", "FAILURE_MODE_STOP_LOOP": "Request stopping the current tool-execution loop after the failure.", "FAILURE_MODE_STOP_RUN": "Request stopping the generation run after the failure." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "FAILURE_MODE_CONTINUE", "number": 1, "canonical": true, "description": "Request continued processing after the failed tool call." }, { "name": "FAILURE_MODE_STOP_LOOP", "number": 2, "canonical": true, "description": "Request stopping the current tool-execution loop after the failure." }, { "name": "FAILURE_MODE_STOP_RUN", "number": 3, "canonical": true, "description": "Request stopping the generation run after the failure." } ], "x-enum-description": "Requested scope of stopping after a tool execution failure.", "description": "Stored requested failure action; not enforced by the current generation workflow.", "x-presence": "implicit" }, "stopOnFailureRules": { "type": "array", "items": { "$ref": "#/components/schemas/StopOnFailureRule" }, "description": "Stored requested stop rules; not evaluated by the current generation workflow.", "x-presence": "collection" } }, "x-reference-model": { "title": "ToolExecutionPolicy", "url": "/api/models/tool-execution-policy#response" } }, "ToolExecutionOrderRule": { "type": "object", "description": "Requested ordering rule for tool execution. The current generation workflow stores\nthese rules but does not apply their patterns, server filters or weights.", "properties": { "toolNamePatterns": { "type": "array", "items": { "type": "string" }, "description": "Requested tool-name patterns; not evaluated by the current generation workflow.", "x-presence": "collection" }, "serverIds": { "type": "array", "items": { "type": "string" }, "description": "Requested MCP server filter; not evaluated by the current generation workflow.", "x-presence": "collection" }, "weight": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Requested ordering weight; not applied by the current generation workflow.", "x-presence": "implicit" } }, "x-reference-model": { "title": "ToolExecutionOrderRule", "url": "/api/models/tool-execution-order-rule#response" } }, "Backoff": { "type": "object", "description": "Requested initial delay, growth factor and upper bound for tool-call retries.\nThe current generation workflow stores this configuration but does not schedule\nretries from it.", "properties": { "initialMs": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Requested initial retry delay in milliseconds; not applied by the current generation workflow.", "x-presence": "implicit" }, "multiplier": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Requested retry-delay multiplier; not applied by the current generation workflow.", "x-presence": "implicit" }, "maxMs": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Requested maximum retry delay in milliseconds; not applied by the current generation workflow.", "x-presence": "implicit" } }, "x-reference-model": { "title": "Backoff", "url": "/api/models/backoff#response" } }, "TimeoutPolicy": { "type": "object", "description": "Bounds the run as a whole. This message has no per-tool or per-loop execution\ntimeout. Approval and client-result answer windows are configured separately on\nToolExecutionPolicy; those waits do not cancel an already dispatched remote action.\n\nSet a finite [`timeouts.overallMs`](/api/models/timeout-policy#request-field-overallms)\nwhen the task needs a duration limit. It is measured from run start; zero or\nomission leaves the run-level duration unbounded.\n\nWhen Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and\npending calls can be closed with `endReason: \"run_timed_out\"`. A call still awaiting\napproval has not been dispatched. The timeout does not guarantee a remote action\nstops at that instant, establish whether it took effect, or roll it back.\n\nUse [`endReason`](/api/models/tool-call#response-field-endreason) to distinguish a\nrun deadline from a call's own answer window: an unanswered approval reads\n`approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the\nactual tool status too; approval and client-tool expiry can produce `FAILED` or\n`TIMED_OUT`. Run and individual tool outcomes are different fields.", "properties": { "overallMs": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Overall run budget in milliseconds, measured from run start. Zero or omission\nleaves this run-level bound unset. The workflow checks the deadline and can end\nwith AGENT_STATUS_TIMED_OUT; it cannot cancel or undo a remote action already\ndispatched. Approval and client-result waits retain their separate finite limits.", "x-presence": "implicit" } }, "x-reference-model": { "title": "TimeoutPolicy", "url": "/api/models/timeout-policy#response" } }, "StopOnFailureRule": { "type": "object", "description": "Requested tool-selection rule for handling an execution failure. The current\ngeneration workflow stores these rules but does not evaluate them or stop a loop\nor run because of them.\n\nThe conditions in [`stopOnFailureRules`](/api/models/tool-execution-policy#request-field-stoponfailurerules),\nincluding [`priority`](/api/models/stop-on-failure-rule#request-field-priority),\ntimeout inclusion and error matching, are not enforced. Do not rely on these\nfields as a stop control.", "properties": { "toolNamePatterns": { "type": "array", "items": { "type": "string" }, "description": "Requested tool-name selection; not evaluated by the current generation workflow.", "x-presence": "collection" }, "serverIds": { "type": "array", "items": { "type": "string" }, "description": "Requested MCP server selection; not evaluated by the current generation workflow.", "x-presence": "collection" }, "onFailure": { "oneOf": [ { "type": "string", "enum": [ "FAILURE_MODE_CONTINUE", "FAILURE_MODE_STOP_LOOP", "FAILURE_MODE_STOP_RUN" ], "x-enumDescriptions": { "FAILURE_MODE_CONTINUE": "Request continued processing after the failed tool call.", "FAILURE_MODE_STOP_LOOP": "Request stopping the current tool-execution loop after the failure.", "FAILURE_MODE_STOP_RUN": "Request stopping the generation run after the failure." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "FAILURE_MODE_CONTINUE", "number": 1, "canonical": true, "description": "Request continued processing after the failed tool call." }, { "name": "FAILURE_MODE_STOP_LOOP", "number": 2, "canonical": true, "description": "Request stopping the current tool-execution loop after the failure." }, { "name": "FAILURE_MODE_STOP_RUN", "number": 3, "canonical": true, "description": "Request stopping the generation run after the failure." } ], "x-enum-description": "Requested scope of stopping after a tool execution failure.", "description": "Requested failure action; not evaluated by the current generation workflow.", "x-presence": "implicit" }, "includeTimeouts": { "type": "boolean", "description": "Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.", "x-presence": "implicit" }, "errorSubstrings": { "type": "array", "items": { "type": "string" }, "description": "Requested error-text selection; not evaluated by the current generation workflow.", "x-presence": "collection" }, "priority": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Requested rule priority; not evaluated by the current generation workflow.", "x-presence": "implicit" } }, "x-reference-model": { "title": "StopOnFailureRule", "url": "/api/models/stop-on-failure-rule#response" } }, "TimeAwareConfig": { "type": "object", "description": "Configuration for time-aware LLM generation.\nControls injection of temporal context (current time, message timestamps,\nfile timestamps) into the LLM context during generation.", "properties": { "includeCurrentTime": { "type": "boolean", "description": "Append the current date and time to the system prompt as temporal context. Default: true.", "x-presence": "implicit" }, "includeMessageTimestamps": { "type": "boolean", "description": "Include timestamps on messages in the model context. Requires the message timestamp to be\npopulated. Default: false.", "x-presence": "implicit" }, "includeFileTimestamps": { "type": "boolean", "description": "Include upload/modification timestamps when resolving FILE_ID content.\nWhen true, resolved file references include \"[Uploaded: ]\" annotations.\nDefault: false", "x-presence": "implicit" }, "timezone": { "type": "string", "description": "Timezone for formatting (IANA format, e.g., \"America/Los_Angeles\").\nDefault: \"UTC\"", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "50" } }, "x-validation-scope": "request" }, "timestampFormat": { "type": "string", "description": "Format pattern for timestamps.\n\"friendly\" (default): \"Jan 2, 2026 at 3:04 PM MST\"\n\"iso8601\": \"2026-01-02T15:04:00-08:00\"\n\"date_only\": \"2026-01-02\"", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "50", "in": [ "", "friendly", "iso8601", "date_only" ] } }, "x-validation-scope": "request" } }, "x-reference-model": { "title": "TimeAwareConfig", "url": "/api/models/time-aware-config#response" } }, "TurnContextConfig": { "type": "object", "description": "Configuration for turn-aware LLM generation\n\nTurn 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.", "properties": { "enabled": { "type": "boolean", "description": "Enable turn context injection into system prompt\nDefault: true", "x-presence": "implicit" }, "includeToolGuidance": { "type": "boolean", "description": "Include tool usage guidance based on remaining turns\nDefault: false (can enable for agentic workflows)", "x-presence": "implicit" }, "format": { "type": "string", "description": "Format for turn context\n\"minimal\": \"[Turn 2/5]\"\n\"standard\": \"[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]\"\n\"verbose\": Includes detailed behavioral guidance\nDefault: \"standard\"", "x-presence": "implicit", "x-protovalidate": { "string": { "in": [ "minimal", "standard", "verbose" ] } }, "x-validation-scope": "request" } }, "x-reference-model": { "title": "TurnContextConfig", "url": "/api/models/turn-context-config#response" }, "x-request-required": [ "format" ] }, "MemoryConfig": { "type": "object", "description": "Configuration for searching, injecting and storing semantic memories during generation.\n\nMemory 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)\n(set at thread creation or via `update-default-generation-config`) or per turn via\n[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).\n\nEnabled 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.\n\nReranking 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.\n\n[`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.", "properties": { "enabled": { "type": "boolean", "description": "Enable searching for relevant memories, adding them to generation context and extracting new\nmemories after generation. Default: false.", "x-presence": "implicit" }, "searchTopK": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of memories to retrieve during search.\nHigher values provide more context but increase token usage.\n\nRange: 1-50 (validated only when enabled = true)\nDefault: 5", "x-presence": "implicit" }, "searchThreshold": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Minimum relevance score threshold for memory search results.\nMemories below this threshold are filtered out.\nRange: 0.0-1.0 (validated only when enabled = true)\nDefault: 0.3", "x-presence": "implicit" }, "injectAsSystemContext": { "type": "boolean", "description": "When true, inject found memories into the system prompt context.\nMemories are formatted as a bullet list under a \"[Relevant memories:]\" header.\nDefault: true", "x-presence": "implicit" }, "searchQueryOverride": { "type": "string", "description": "Custom search query to use instead of the last user message.\nIf empty, the last user message content is used as the search query.", "x-presence": "implicit" }, "enableRerank": { "type": "boolean", "description": "Enable reranking for improved search relevance.\nReranking provides better results but adds latency.\nDefault: false", "x-presence": "implicit" }, "addMemoriesAsync": { "type": "boolean", "description": "When true, memory extraction happens asynchronously after generation completes.\nThis prevents extraction latency from affecting response time.\nDefault: true", "x-presence": "implicit" }, "customExtractionPrompt": { "type": "string", "description": "Custom prompt for memory/fact extraction.\nIf empty, the default extraction prompt is used.\nUse this to customize what types of facts are extracted.", "x-presence": "implicit" }, "enableGraph": { "type": "boolean", "description": "Enable relationship extraction and graph-based memory search when graph memory is configured.\nDefault: false.", "x-presence": "implicit" }, "agentIdOverride": { "type": "string", "description": "Override the agent_id used for memory scoping.\nBy default, the conversation_id is used as the agent_id.\nUse this to share memories across multiple conversations.", "x-presence": "implicit" }, "exposeAsMcpTool": { "type": "boolean", "description": "Expose memory search as an MCP tool during generation.\nWhen true, the LLM can explicitly search memories via tool calls.\nRate limited to 3 searches per generation turn.\nDefault: false", "x-presence": "implicit" }, "includeAssistantMessages": { "type": "boolean", "description": "Include assistant/agent-scoped memories in operations.\nWhen false, skips agent_id for both add and search operations,\nkeeping only user-scoped memories.\nDefault: false", "x-presence": "implicit" }, "injectMemoryTimestamps": { "type": "boolean", "description": "Include created_at/updated_at timestamps on injected memories.\nWhen true, each memory bullet includes a \"(remembered: )\" annotation\nand optionally \"(updated: )\" if the memory was modified after creation.\nDefault: true", "x-presence": "implicit" } }, "x-reference-model": { "title": "MemoryConfig", "url": "/api/models/memory-config#response" }, "x-protovalidate": { "cel": [ { "id": "mem0_config_valid_when_enabled", "message": "search_top_k and search_threshold must be valid when enabled is true", "expression": "!this.enabled || ((this.search_top_k >= 1 && this.search_top_k <= 50) && (this.search_threshold >= 0.0 && this.search_threshold <= 1.0))" } ] }, "x-validation-scope": "request" }, "FileResolutionConfig": { "type": "object", "description": "Configuration for resolving CONTENT_PART_TYPE_FILE_ID parts to fresh signed\nURLs before requests are sent to LLM providers. Keeps stable file references\nin message history while generating ephemeral URLs only when needed.\n\nOmitting 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.", "properties": { "failureMode": { "oneOf": [ { "type": "string", "enum": [ "FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION", "FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT" ], "x-enumDescriptions": { "FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION": "Fail generation when a file content part cannot be resolved.", "FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT": "Skip the unresolved content part and continue with the remaining content." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION", "number": 1, "canonical": true, "description": "Fail generation when a file content part cannot be resolved." }, { "name": "FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT", "number": 2, "canonical": true, "description": "Skip the unresolved content part and continue with the remaining content." } ], "x-enum-description": "How generation handles a content part whose file identifier cannot be resolved.", "description": "Action to take when a file cannot be resolved. If omitted, skip unresolved file content\nand use the remaining content.", "x-presence": "implicit" } }, "x-reference-model": { "title": "FileResolutionConfig", "url": "/api/models/file-resolution-config#response" } }, "PluginConfig": { "type": "object", "description": "Provider plugin identifier and its parser, search, or additional configuration.", "properties": { "id": { "type": "string", "description": "Provider plugin identifier, such as file-parser.", "x-presence": "implicit" }, "pdf": { "description": "PDF annotation or parser configuration selected by the enclosing message.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PluginPDFConfig" } ] }, "web": { "description": "Web-search configuration for the selected generation plugin.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PluginWebConfig" } ] }, "params": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional provider-specific plugin parameters.", "x-presence": "collection" } }, "x-reference-model": { "title": "PluginConfig", "url": "/api/models/plugin-config#response" } }, "PluginPDFConfig": { "type": "object", "description": "Plugins for pre/post-processing (generic representation)", "properties": { "engine": { "type": "string", "description": "PDF parsing engine selected for the provider plugin.", "x-presence": "implicit" } }, "x-reference-model": { "title": "PluginPDFConfig", "url": "/api/models/plugin-pdf-config#response" } }, "PluginWebConfig": { "type": "object", "description": "Provider web-search configuration used to augment a generation request.", "properties": { "engine": { "type": "string", "description": "Search engine selected for the provider’s web-search plugin.", "x-presence": "implicit" }, "maxResults": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum web-search result count requested by the plugin.", "x-presence": "implicit" }, "searchPrompt": { "type": "string", "description": "Instructions supplied to the web-search plugin.", "x-presence": "implicit" }, "webSearchOptions": { "description": "Options controlling the amount of web-search context requested.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/WebSearchOptions" } ] } }, "x-reference-model": { "title": "PluginWebConfig", "url": "/api/models/plugin-web-config#response" } }, "WebSearchOptions": { "type": "object", "description": "Amount of web-search context requested for generation.", "properties": { "searchContextSize": { "type": "string", "description": "Requested amount of web-search context: low, medium, or high.", "x-presence": "implicit" } }, "x-reference-model": { "title": "WebSearchOptions", "url": "/api/models/web-search-options#response" } }, "MCPServerReference": { "type": "object", "description": "MCP Server Reference\nLightweight reference to pre-configured MCP servers used by workflows", "properties": { "serverId": { "type": "string", "description": "ID of pre-configured MCP server (e.g., \"github\", \"filesystem\").", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "enabled": { "type": "boolean", "description": "Whether to use this MCP server. Omission means enabled; only an explicitly false value\nexcludes it from discovery.", "x-presence": "explicit" }, "priority": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Priority override for tool selection (higher = preferred).", "x-presence": "implicit" }, "allowlistToolPatterns": { "type": "array", "items": { "type": "string" }, "description": "Only include tools matching these patterns (e.g., \"github_get_*\", \"search_*\").", "x-presence": "collection" }, "blocklistToolPatterns": { "type": "array", "items": { "type": "string" }, "description": "Exclude tools matching these patterns (e.g., \"*_delete\", \"*_destroy\").", "x-presence": "collection" }, "serverOverrides": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Override server settings for this usage.", "x-presence": "collection" } }, "x-reference-model": { "title": "MCPServerReference", "url": "/api/models/mcp-server-reference#response" }, "x-request-required": [ "serverId" ] }, "PromptVariableSpec": { "type": "object", "description": "Declares a variable used by a profile's system-prompt template. Values are supplied\nthrough the conversation's prompt_variables.\n\nWhen creating a conversation with an explicitly selected profile, a\n[`variableSpecs`](/api/models/agent-profile#request-field-variablespecs) entry with\n`required: true` and no nonempty [`defaultValue`](/api/models/prompt-variable-spec#request-field-defaultvalue)\ncauses `MISSING_REQUIRED_PROMPT_VARIABLES` if the variable is missing. Supply the\nvalue at creation. This validation is not repeated for each send or queued turn.\n\nSet intended values explicitly even when the spec declares a default. A nonempty\n`defaultValue` suppresses the creation-time missing-required error but is not\nautomatically inserted into the rendered prompt.", "properties": { "name": { "type": "string", "description": "Variable name referenced by the profile’s system-prompt template.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Console hint + caller documentation.", "x-presence": "implicit" }, "required": { "type": "boolean", "description": "Whether a value is required for a profile explicitly selected at conversation creation.\nThe current validation does not run for every send or queued turn.", "x-presence": "implicit" }, "defaultValue": { "type": "string", "description": "A nonempty value suppresses the creation-time missing-required error. It is not\nautomatically inserted into the rendered prompt; supply intended values explicitly.", "x-presence": "implicit" }, "type": { "oneOf": [ { "type": "string", "enum": [ "VAR_TYPE_STRING", "VAR_TYPE_NUMBER", "VAR_TYPE_BOOL", "VAR_TYPE_LIST" ], "x-enumDescriptions": { "VAR_TYPE_STRING": "Treat the variable as text in the template context.", "VAR_TYPE_NUMBER": "Coerce the variable to a numeric value for arithmetic or numeric comparisons.", "VAR_TYPE_BOOL": "Coerce the variable to a boolean for template conditions.", "VAR_TYPE_LIST": "Provide a list that templates can iterate or join." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "VAR_TYPE_STRING", "number": 1, "canonical": true, "description": "Treat the variable as text in the template context." }, { "name": "VAR_TYPE_NUMBER", "number": 2, "canonical": true, "description": "Coerce the variable to a numeric value for arithmetic or numeric comparisons." }, { "name": "VAR_TYPE_BOOL", "number": 3, "canonical": true, "description": "Coerce the variable to a boolean for template conditions." }, { "name": "VAR_TYPE_LIST", "number": 4, "canonical": true, "description": "Provide a list that templates can iterate or join." } ], "x-enum-description": "Type used to coerce a prompt variable before placing it in the template context.", "description": "\"\" preserves the missing→empty behavior", "x-presence": "implicit" } }, "x-reference-model": { "title": "PromptVariableSpec", "url": "/api/models/prompt-variable-spec#response" } }, "GetAgentProfileRequest": { "type": "object", "description": "=== Get ===\nInputs for retrieving a selected agent profile and its configuration.", "properties": { "projectId": { "type": "string", "description": "Identifier of the project associated with the operation.", "x-presence": "implicit" }, "profileId": { "type": "string", "minLength": 1, "description": "Identifier of the agent profile associated with the operation or generation.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "version": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 2147483647, "description": "Immutable profile version to retrieve. Zero or omission selects the latest version.", "x-presence": "implicit", "x-protovalidate": { "int32": { "gte": 0 } }, "x-validation-scope": "request" } }, "x-request-required": [ "profileId" ], "required": [ "profileId" ] }, "GetAgentProfileResponse": { "type": "object", "description": "Result payload for retrieving a selected agent profile and its configuration.", "properties": { "profile": { "description": "Agent profile returned by the operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/AgentProfile" } ] } } }, "ListAgentProfilesRequest": { "type": "object", "description": "=== List ===\nInputs for paging through agent profiles available in the project library.", "properties": { "projectId": { "type": "string", "description": "Identifier of the project associated with the operation.", "x-presence": "implicit" }, "page": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 2147483647, "description": "Page number used by this listing operation.", "x-presence": "implicit", "x-protovalidate": { "int32": { "gte": 0 } }, "x-validation-scope": "request" }, "pageSize": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100, "description": "Number of entries requested per page. Zero or omission lets the server choose its default.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 100, "gte": 0 } }, "x-validation-scope": "request" }, "includeDisabled": { "type": "boolean", "description": "Include disabled profiles in addition to the enabled selection; otherwise only enabled\nprofiles are returned.", "x-presence": "implicit" } } }, "ListAgentProfilesResponse": { "type": "object", "description": "Result payload for paging through agent profiles available in the project library.", "properties": { "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/AgentProfile" }, "description": "Agent profiles returned by the listing or import.", "x-presence": "collection" }, "totalCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Total number of matching entries reported by the operation.", "x-presence": "implicit" }, "hasMore": { "type": "boolean", "description": "Whether the listing reports additional entries beyond this page.", "x-presence": "implicit" } } }, "UpdateAgentProfileRequest": { "type": "object", "description": "=== Update ===\nInputs for changing selected agent-profile fields and producing an updated revision.", "properties": { "projectId": { "type": "string", "description": "Identifier of the project associated with the operation.", "x-presence": "implicit" }, "profileId": { "type": "string", "minLength": 1, "description": "Identifier of the agent profile associated with the operation or generation.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "profile": { "description": "Carries the new field values.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/AgentProfileInput" } ] }, "updateMask": { "type": "string", "description": "Field paths selecting which values to modify. Omitted or empty: only the fields the\nprofile sets change, at every depth.", "x-presence": "message" } }, "x-request-required": [ "profileId" ], "required": [ "profileId" ] }, "UpdateAgentProfileResponse": { "type": "object", "description": "Result payload for changing selected agent-profile fields and producing an updated revision.", "properties": { "profile": { "description": "Agent profile returned by the operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/AgentProfile" } ] } } }, "DeleteAgentProfileRequest": { "type": "object", "description": "=== Delete ===\nInputs for removing an agent profile from the project library.", "properties": { "projectId": { "type": "string", "description": "Identifier of the project associated with the operation.", "x-presence": "implicit" }, "profileId": { "type": "string", "minLength": 1, "description": "Identifier of the agent profile associated with the operation or generation.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "profileId" ], "required": [ "profileId" ] }, "DeleteAgentProfileResponse": { "type": "object", "description": "Response schema for removing an agent profile from the project library; no response fields are declared.", "properties": {} }, "GetAgentProfileLibraryRequest": { "type": "object", "description": "=== Library (metadata only) ===\nInputs for reading profile metadata available for discovery in the project library.", "properties": { "projectId": { "type": "string", "description": "Identifier of the project associated with the operation.", "x-presence": "implicit" } } }, "GetAgentProfileLibraryResponse": { "type": "object", "description": "Result payload for reading profile metadata available for discovery in the project library.", "properties": { "library": { "description": "Profile identity and selection metadata for the project.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/AgentProfileLibrary" } ] } } }, "AgentProfileLibrary": { "type": "object", "description": "Selection metadata for the project’s agent profiles. Retrieve an individual profile to read its\ncomplete model and tool configuration.", "properties": { "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/AgentProfileMetadata" }, "description": "Profile identity and selection metadata. Full configurations are retrieved individually with\nGetAgentProfile.", "x-presence": "collection" }, "defaultProfileId": { "type": "string", "description": "Project's nominated default profile. Native conversations do not automatically apply it\nwhen active_profile_id is empty; the client must explicitly select its intended profile.", "x-presence": "implicit" } }, "x-reference-model": { "title": "AgentProfileLibrary", "url": "/api/models/agent-profile-library#response" } }, "AgentProfileMetadata": { "type": "object", "description": "Profile identity and selection hints for a picker or router. This projection excludes the\nsystem prompt, generation settings, tools and MCP configuration; retrieve AgentProfile to\ninspect the runtime configuration. These hints do not establish that routing is active.", "properties": { "profileId": { "type": "string", "description": "Identifier of the agent profile associated with the operation or generation.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Display name used when presenting an agent profile in the library.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Human-readable description of the resource.", "x-presence": "implicit" }, "whenToUse": { "type": "string", "description": "Instructions describing when this agent profile should be selected.", "x-presence": "implicit" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords associated with discovery or selection of the agent profile.", "x-presence": "collection" }, "enabled": { "type": "boolean", "description": "Whether this configuration is enabled.", "x-presence": "implicit" } }, "x-reference-model": { "title": "AgentProfileMetadata", "url": "/api/models/agent-profile-metadata#response" } }, "ListAgentProfileVersionsRequest": { "type": "object", "description": "Inputs for listing immutable revisions of an agent profile.", "properties": { "projectId": { "type": "string", "description": "Identifier of the project associated with the operation.", "x-presence": "implicit" }, "profileId": { "type": "string", "minLength": 1, "description": "Identifier of the agent profile associated with the operation or generation.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "profileId" ], "required": [ "profileId" ] }, "ListAgentProfileVersionsResponse": { "type": "object", "description": "Result payload for listing immutable revisions of an agent profile.", "properties": { "versions": { "type": "array", "items": { "$ref": "#/components/schemas/AgentProfileVersionInfo" }, "description": "Descending (newest first). Empty when the profile has never existed.", "x-presence": "collection" } } }, "AgentProfileVersionInfo": { "type": "object", "description": "Version identifier and creation time for an immutable agent-profile revision.", "properties": { "version": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Version of the resource represented by this message.", "x-presence": "implicit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when this record was created.", "x-presence": "message" } }, "x-reference-model": { "title": "AgentProfileVersionInfo", "url": "/api/models/agent-profile-version-info#response" } }, "GetPromptFragmentSetRequest": { "type": "object", "description": "Inputs for reading an immutable version of the project’s prompt-fragment set.", "properties": { "projectId": { "type": "string", "description": "Identifier of the project associated with the operation.", "x-presence": "implicit" }, "setVersion": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 2147483647, "description": "Version identifying the immutable prompt-fragment set.", "x-presence": "implicit", "x-protovalidate": { "int32": { "gte": 1 } }, "x-validation-scope": "request" } }, "x-request-required": [ "setVersion" ], "required": [ "setVersion" ] }, "GetPromptFragmentSetResponse": { "type": "object", "description": "Result payload for reading an immutable version of the project’s prompt-fragment set.", "properties": { "setVersion": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Version identifying the immutable prompt-fragment set.", "x-presence": "implicit" }, "fragments": { "type": "array", "items": { "$ref": "#/components/schemas/PromptFragment" }, "description": "Ordered by fragment_id.", "x-presence": "collection" } } }, "PromptFragment": { "type": "object", "description": "Project-scoped reusable prompt-template text. Profiles and other fragments include it with\n`{{template \"fragment_id\" .}}`; variables come from the conversation’s prompt_variables.", "properties": { "fragmentId": { "type": "string", "description": "Stable template name, unique within the project library and used by include actions.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Display name for the reusable prompt fragment.", "x-presence": "implicit" }, "content": { "type": "string", "description": "Raw template text, supporting `{{.variable}}` placeholders and nested `{{template \"id\" .}}` includes.", "x-presence": "implicit" } }, "x-reference-model": { "title": "PromptFragment", "url": "/api/models/prompt-fragment#response" } }, "CreatePromptFragmentRequest": { "type": "object", "description": "=== Create fragment ===\nInputs for creating a reusable block of prompt-template text in the project library.", "properties": { "projectId": { "type": "string", "description": "Identifier of the project associated with the operation.", "x-presence": "implicit" }, "fragment": { "description": "Reusable prompt fragment definition to add to the project library.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PromptFragmentInput" } ], "x-protovalidate": { "required": true }, "x-validation-scope": "request" } }, "x-request-required": [ "fragment" ], "required": [ "fragment" ] }, "PromptFragmentInput": { "type": "object", "description": "Project-scoped reusable prompt-template text. Profiles and other fragments include it with\n`{{template \"fragment_id\" .}}`; variables come from the conversation’s prompt_variables.", "properties": { "fragmentId": { "type": "string", "description": "Stable template name, unique within the project library and used by include actions.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Display name for the reusable prompt fragment.", "x-presence": "implicit" }, "content": { "type": "string", "description": "Raw template text, supporting `{{.variable}}` placeholders and nested `{{template \"id\" .}}` includes.", "x-presence": "implicit" } }, "x-reference-model": { "title": "PromptFragment", "url": "/api/models/prompt-fragment#request" } }, "CreatePromptFragmentResponse": { "type": "object", "description": "Result payload for creating a reusable block of prompt-template text in the project library.", "properties": { "fragment": { "description": "Echoes the stored fragment.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PromptFragment" } ] } } }, "GetPromptFragmentRequest": { "type": "object", "description": "=== Get fragment ===\nInputs for retrieving a reusable prompt fragment by its identifier.", "properties": { "projectId": { "type": "string", "description": "Identifier of the project associated with the operation.", "x-presence": "implicit" }, "fragmentId": { "type": "string", "minLength": 1, "description": "Identifier of the reusable prompt fragment.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "fragmentId" ], "required": [ "fragmentId" ] }, "GetPromptFragmentResponse": { "type": "object", "description": "Result payload for retrieving a reusable prompt fragment by its identifier.", "properties": { "fragment": { "description": "Reusable prompt fragment returned by the operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PromptFragment" } ] } } }, "ListPromptFragmentsRequest": { "type": "object", "description": "=== List fragments ===\nInputs for paging through reusable prompt fragments in the project library.", "properties": { "projectId": { "type": "string", "description": "Identifier of the project associated with the operation.", "x-presence": "implicit" }, "page": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 2147483647, "description": "Page number used by this listing operation.", "x-presence": "implicit", "x-protovalidate": { "int32": { "gte": 0 } }, "x-validation-scope": "request" }, "pageSize": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100, "description": "Number of entries requested per page. Zero or omission lets the server choose its default.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 100, "gte": 0 } }, "x-validation-scope": "request" } } }, "ListPromptFragmentsResponse": { "type": "object", "description": "Result payload for paging through reusable prompt fragments in the project library.", "properties": { "fragments": { "type": "array", "items": { "$ref": "#/components/schemas/PromptFragment" }, "description": "Reusable prompt fragments returned by the operation.", "x-presence": "collection" }, "totalCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Total number of matching entries reported by the operation.", "x-presence": "implicit" }, "hasMore": { "type": "boolean", "description": "Whether the listing reports additional entries beyond this page.", "x-presence": "implicit" }, "setVersion": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Current version of the project’s prompt-fragment set. Zero means no fragments have been\nwritten.", "x-presence": "implicit" } } }, "UpdatePromptFragmentRequest": { "type": "object", "description": "=== Update fragment ===\nInputs for changing selected fields of a reusable prompt fragment.", "properties": { "projectId": { "type": "string", "description": "Identifier of the project associated with the operation.", "x-presence": "implicit" }, "fragmentId": { "type": "string", "minLength": 1, "description": "Identifier of the reusable prompt fragment.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "fragment": { "description": "Carries the new field values.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PromptFragmentInput" } ] }, "updateMask": { "type": "string", "description": "Field paths selecting which values to modify.", "x-presence": "message" } }, "x-request-required": [ "fragmentId" ], "required": [ "fragmentId" ] }, "UpdatePromptFragmentResponse": { "type": "object", "description": "Result payload for changing selected fields of a reusable prompt fragment.", "properties": { "fragment": { "description": "Reusable prompt fragment returned by the operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PromptFragment" } ] } } }, "DeletePromptFragmentRequest": { "type": "object", "description": "=== Delete fragment ===\nInputs for removing a reusable prompt fragment from the project library.", "properties": { "projectId": { "type": "string", "description": "Identifier of the project associated with the operation.", "x-presence": "implicit" }, "fragmentId": { "type": "string", "minLength": 1, "description": "Identifier of the reusable prompt fragment.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "fragmentId" ], "required": [ "fragmentId" ] }, "DeletePromptFragmentResponse": { "type": "object", "description": "Response schema for removing a reusable prompt fragment from the project library; no response fields are declared.", "properties": {} }, "ImportAgentProfilesRequest": { "type": "object", "description": "Inputs for converting a source prompt library into project profiles. Every shared block\nreferenced by an include must be supplied in fragments so the importer can resolve the library.", "properties": { "projectId": { "type": "string", "description": "Identifier of the project associated with the operation.", "x-presence": "implicit" }, "templates": { "type": "array", "items": { "$ref": "#/components/schemas/SourcePromptTemplate" }, "description": "Source persona templates to convert into conversational agent profiles.", "x-presence": "collection" }, "fragments": { "type": "array", "items": { "$ref": "#/components/schemas/SourcePromptFragment" }, "description": "Shared @include blocks.", "x-presence": "collection" }, "variableTypes": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string", "enum": [ "VAR_TYPE_STRING", "VAR_TYPE_NUMBER", "VAR_TYPE_BOOL", "VAR_TYPE_LIST" ], "x-enumDescriptions": { "VAR_TYPE_STRING": "Treat the variable as text in the template context.", "VAR_TYPE_NUMBER": "Coerce the variable to a numeric value for arithmetic or numeric comparisons.", "VAR_TYPE_BOOL": "Coerce the variable to a boolean for template conditions.", "VAR_TYPE_LIST": "Provide a list that templates can iterate or join." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "VAR_TYPE_STRING", "number": 1, "canonical": true, "description": "Treat the variable as text in the template context." }, { "name": "VAR_TYPE_NUMBER", "number": 2, "canonical": true, "description": "Coerce the variable to a numeric value for arithmetic or numeric comparisons." }, { "name": "VAR_TYPE_BOOL", "number": 3, "canonical": true, "description": "Coerce the variable to a boolean for template conditions." }, { "name": "VAR_TYPE_LIST", "number": 4, "canonical": true, "description": "Provide a list that templates can iterate or join." } ], "x-enum-description": "Type used to coerce a prompt variable before placing it in the template context.", "description": "Type used to coerce a prompt variable before placing it in the template context." }, "description": "Optional variable type hints that override types inferred from template usage.", "x-presence": "collection" }, "overwrite": { "type": "boolean", "description": "Update existing profiles and fragments instead of failing ALREADY_EXISTS. An existing\nprofile takes the imported prompt, variable specs, name, when_to_use, keywords and the\ngeneration settings the template sets; its model, MCP servers, description, enabled state\nand disable_default_tools are kept.", "x-presence": "implicit" }, "emitFragments": { "type": "boolean", "description": "When false, resolve source includes inline into each profile’s system prompt. When true, emit\nsupplied shared blocks as prompt fragments and reference them through template actions; every\nreferenced shared block must be supplied.", "x-presence": "implicit" } } }, "SourcePromptTemplate": { "type": "object", "description": "Source persona template to convert into an agent profile during import. Its source_dsl contains\nthe original template syntax from which the importer derives the profile template and variable\nspecifications.", "properties": { "profileId": { "type": "string", "description": "Identifier of the agent profile associated with the operation or generation.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Display name for the imported agent profile.", "x-presence": "implicit" }, "whenToUse": { "type": "string", "description": "Instructions describing when the imported agent profile should be selected.", "x-presence": "implicit" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords associated with selection of the imported agent profile.", "x-presence": "collection" }, "sourceDsl": { "type": "string", "description": "Raw source-DSL system prompt.", "x-presence": "implicit" }, "generationConfig": { "description": "Generation settings other than the prompt, such as temperature. Must not set model or\nmodels: import refuses a template that does, and the model is set afterwards with\nUpdateAgentProfile.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GenerationConfigInput" } ] } }, "x-reference-model": { "title": "SourcePromptTemplate", "url": "/api/models/source-prompt-template#request" } }, "SourcePromptFragment": { "type": "object", "description": "Shared template block supplied for import. Its path resolves source include directives;\nfragment_id supplies the stable output identity when shared fragments are emitted, or is derived\nfrom the path when omitted.", "properties": { "fragmentId": { "type": "string", "description": "Identifier of the reusable prompt fragment.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Display name for the imported reusable prompt fragment.", "x-presence": "implicit" }, "sourceDsl": { "type": "string", "description": "Raw source text (may itself contain @include / metadata comments).", "x-presence": "implicit" }, "path": { "type": "string", "description": "Include path, e.g. \"_shared/safety-module.txt\"", "x-presence": "implicit" } }, "x-reference-model": { "title": "SourcePromptFragment", "url": "/api/models/source-prompt-fragment#request" } }, "ImportAgentProfilesResponse": { "type": "object", "description": "Result payload for converting and importing source prompt templates into project agent profiles.", "properties": { "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/AgentProfile" }, "description": "Converted + stored (echo).", "x-presence": "collection" }, "fragments": { "type": "array", "items": { "$ref": "#/components/schemas/PromptFragment" }, "description": "Reusable prompt fragments returned by the operation.", "x-presence": "collection" } } }, "PipedreamListAppsRequest": { "type": "object", "description": "Inputs for searching the Pipedream app catalog with pagination and sorting.", "properties": { "after": { "type": "string", "description": "Cursor selecting entries after the specified position in the provider listing.", "x-presence": "implicit" }, "before": { "type": "string", "description": "Cursor selecting entries before the specified position in the provider listing.", "x-presence": "implicit" }, "limit": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum number of entries requested from the listing.", "x-presence": "implicit" }, "q": { "type": "string", "description": "Free-text search over app names in the integration catalog.", "x-presence": "implicit" }, "categoryIds": { "type": "array", "items": { "type": "string" }, "description": "Integration app category identifiers used to restrict the listing.", "x-presence": "collection" }, "sortKey": { "oneOf": [ { "type": "string", "enum": [ "APP_SORT_KEY_NAME", "APP_SORT_KEY_NAME_SLUG", "APP_SORT_KEY_FEATURED_WEIGHT" ], "x-enumDescriptions": { "APP_SORT_KEY_NAME": "Sort by the app's display name.", "APP_SORT_KEY_NAME_SLUG": "Sort by the app's stable name slug.", "APP_SORT_KEY_FEATURED_WEIGHT": "Sort by the catalog's featured-app ranking weight." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "APP_SORT_KEY_NAME", "number": 1, "canonical": true, "description": "Sort by the app's display name." }, { "name": "APP_SORT_KEY_NAME_SLUG", "number": 2, "canonical": true, "description": "Sort by the app's stable name slug." }, { "name": "APP_SORT_KEY_FEATURED_WEIGHT", "number": 3, "canonical": true, "description": "Sort by the catalog's featured-app ranking weight." } ], "x-enum-description": "Integration-app catalog property used to order list results.", "description": "Provider field used to order catalog results.", "x-presence": "implicit" }, "sortDirection": { "oneOf": [ { "type": "string", "enum": [ "SORT_DIRECTION_ASC", "SORT_DIRECTION_DESC" ], "x-enumDescriptions": { "SORT_DIRECTION_ASC": "Order results from lower to higher values of the selected sort key.", "SORT_DIRECTION_DESC": "Order results from higher to lower values of the selected sort key." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "SORT_DIRECTION_ASC", "number": 1, "canonical": true, "description": "Order results from lower to higher values of the selected sort key." }, { "name": "SORT_DIRECTION_DESC", "number": 2, "canonical": true, "description": "Order results from higher to lower values of the selected sort key." } ], "x-enum-description": "Direction applied to the selected integration-app sort key.", "description": "Direction in which the provider should order catalog results.", "x-presence": "implicit" } } }, "PipedreamListAppsResponse": { "type": "object", "description": "Result payload for searching the Pipedream app catalog with pagination and sorting.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/App" }, "description": "Pipedream app catalog entries returned for this page.", "x-presence": "collection" }, "pageInfo": { "description": "Cursor and count information returned with the provider listing.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PipedreamPageInfo" } ] } } }, "App": { "type": "object", "description": "App metadata", "properties": { "id": { "type": "string", "description": "Identifier of the app record.", "x-presence": "implicit" }, "nameSlug": { "type": "string", "description": "Unique slug identifier (e.g., \"slack\", \"github\").", "x-presence": "implicit" }, "name": { "type": "string", "description": "Display name of the integration app in the Pipedream catalog.", "x-presence": "implicit" }, "authType": { "oneOf": [ { "type": "string", "enum": [ "AUTH_TYPE_KEYS", "AUTH_TYPE_OAUTH", "AUTH_TYPE_NONE" ], "x-enumDescriptions": { "AUTH_TYPE_KEYS": "The app uses API-key credentials.", "AUTH_TYPE_OAUTH": "The app uses an OAuth authorization flow.", "AUTH_TYPE_NONE": "The app does not require authentication credentials." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "AUTH_TYPE_KEYS", "number": 1, "canonical": true, "description": "The app uses API-key credentials." }, { "name": "AUTH_TYPE_OAUTH", "number": 2, "canonical": true, "description": "The app uses an OAuth authorization flow." }, { "name": "AUTH_TYPE_NONE", "number": 3, "canonical": true, "description": "The app does not require authentication credentials." } ], "x-enum-description": "Credential mechanism an integration app uses when connecting an account.", "description": "Authentication mechanism reported for the connected account or app.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Human-readable description of the resource.", "x-presence": "implicit" }, "imgSrc": { "type": "string", "description": "Image URL supplied for the integration app.", "x-presence": "implicit" }, "customFieldsJson": { "type": "string", "description": "JSON string for custom fields.", "x-presence": "implicit" }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Categories assigned to the integration app.", "x-presence": "collection" }, "featuredWeight": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Provider weight used to order featured apps.", "x-presence": "implicit" } }, "x-reference-model": { "title": "App", "url": "/api/models/app#response" } }, "PipedreamPageInfo": { "type": "object", "description": "Pagination information returned in list responses", "properties": { "count": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Items in current page.", "x-presence": "implicit" }, "totalCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Total items matching query.", "x-presence": "implicit" }, "startCursor": { "type": "string", "description": "Cursor for start of page.", "x-presence": "implicit" }, "endCursor": { "type": "string", "description": "Cursor for end of page.", "x-presence": "implicit" } }, "x-reference-model": { "title": "PipedreamPageInfo", "url": "/api/models/pipedream-page-info#response" } }, "PipedreamRetrieveAppRequest": { "type": "object", "description": "Inputs for retrieving app catalog metadata by its Pipedream slug.", "properties": { "nameSlug": { "type": "string", "minLength": 1, "description": "Pipedream app slug identifying the catalog entry.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "nameSlug" ], "required": [ "nameSlug" ] }, "PipedreamRetrieveAppResponse": { "type": "object", "description": "Result payload for retrieving app catalog metadata by its Pipedream slug.", "properties": { "app": { "description": "Catalog metadata returned for the selected Pipedream app.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/App" } ] } } }, "PipedreamListAppCategoriesRequest": { "type": "object", "description": "Inputs for discovering the categories used by the Pipedream app catalog.", "properties": { "after": { "type": "string", "description": "Cursor selecting entries after the specified position in the provider listing.", "x-presence": "implicit" }, "before": { "type": "string", "description": "Cursor selecting entries before the specified position in the provider listing.", "x-presence": "implicit" }, "limit": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum number of entries requested from the listing.", "x-presence": "implicit" } } }, "PipedreamListAppCategoriesResponse": { "type": "object", "description": "Result payload for discovering the categories used by the Pipedream app catalog.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AppCategory" }, "description": "Pipedream app categories returned for this page.", "x-presence": "collection" }, "pageInfo": { "description": "Cursor and count information returned with the provider listing.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PipedreamPageInfo" } ] } } }, "AppCategory": { "type": "object", "description": "App category", "properties": { "id": { "type": "string", "description": "Identifier of the app category record.", "x-presence": "implicit" }, "nameSlug": { "type": "string", "description": "Pipedream app slug identifying the catalog entry.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Display label of the app category in the Pipedream catalog.", "x-presence": "implicit" } }, "x-reference-model": { "title": "AppCategory", "url": "/api/models/app-category#response" } }, "PipedreamCreateConnectTokenRequest": { "type": "object", "description": "Inputs for issuing a token and hosted link for connecting an end-user account.", "properties": { "state": { "type": "string", "description": "Optional opaque state to round-trip in redirect", "x-presence": "implicit" }, "redirectUri": { "type": "string", "description": "Optional universal redirect (success) URI override", "x-presence": "implicit" }, "allowedOrigins": { "type": "array", "items": { "type": "string" }, "description": "CORS allowed origins for hosted Connect (iframe)", "x-presence": "collection" }, "successRedirectUrl": { "type": "string", "description": "Optional explicit success/error redirects", "x-presence": "implicit" }, "errorRedirectUrl": { "type": "string", "description": "URL to which the account-connection flow redirects on error.", "x-presence": "implicit" }, "webhookUrl": { "type": "string", "description": "Optional webhook for Connect notifications", "x-presence": "implicit" }, "appSlug": { "type": "string", "description": "App slug the end user should connect (e.g. \"github\", \"strava\").", "x-presence": "implicit" } } }, "PipedreamCreateConnectTokenResponse": { "type": "object", "description": "Result payload for issuing a token and hosted link for connecting an end-user account.", "properties": { "token": { "type": "string", "description": "Short-lived Pipedream Connect token returned by the provider.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "connectLinkUrl": { "type": "string", "description": "Pipedream Connect URL used to authorize an account connection.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Time when the credential or resource expires.", "x-presence": "message" } }, "x-request-required": [ "token", "connectLinkUrl" ] }, "PipedreamListAccountsForCurrentUserRequest": { "type": "object", "description": "Inputs for listing Pipedream account connections belonging to the calling user.", "properties": { "after": { "type": "string", "description": "Cursor selecting entries after the specified position in the provider listing.", "x-presence": "implicit" }, "before": { "type": "string", "description": "Cursor selecting entries before the specified position in the provider listing.", "x-presence": "implicit" }, "limit": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum number of entries requested from the listing.", "x-presence": "implicit" }, "oauthAppId": { "type": "string", "description": "OAuth application identifier used to select connected accounts.", "x-presence": "implicit" }, "app": { "type": "string", "description": "Pipedream app slug used to restrict the operation to one connected app.", "x-presence": "implicit" }, "includeCredentials": { "type": "boolean", "description": "Whether the provider should include account credentials in its response.", "x-presence": "implicit" } } }, "PipedreamListAccountsForCurrentUserResponse": { "type": "object", "description": "Result payload for listing Pipedream account connections belonging to the calling user.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Account" }, "description": "Pipedream connected accounts returned for this page.", "x-presence": "collection" }, "pageInfo": { "description": "Cursor and count information returned with the provider listing.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PipedreamPageInfo" } ] } } }, "Account": { "type": "object", "description": "Connected account (external user's OAuth connection to an app)", "properties": { "id": { "type": "string", "description": "Unique account ID.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Display name (e.g., user's email or handle).", "x-presence": "implicit" }, "externalUserId": { "type": "string", "description": "Your application's user ID.", "x-presence": "implicit" }, "healthy": { "type": "boolean", "description": "Whether the account credentials are valid.", "x-presence": "implicit" }, "app": { "type": "string", "description": "Pipedream application selected by the request or returned by the provider.", "x-presence": "implicit" }, "oauthAppId": { "type": "string", "description": "OAuth app identifier (if applicable).", "x-presence": "implicit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when this record was created.", "x-presence": "message" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time when this record was last updated.", "x-presence": "message" }, "credentialsLastRefreshedAt": { "type": "string", "format": "date-time", "description": "Time when the connected account credentials were last refreshed.", "x-presence": "message" }, "credentialsExpiresAt": { "type": "string", "format": "date-time", "description": "Expiration time reported for the connected account credentials.", "x-presence": "message" }, "error": { "type": "string", "description": "Error message if unhealthy.", "x-presence": "implicit" }, "lastRefreshedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 when credentials were last refreshed.", "x-presence": "message" }, "nextRefreshAt": { "type": "string", "format": "date-time", "description": "ISO 8601 when credentials will next be refreshed.", "x-presence": "message" } }, "x-reference-model": { "title": "Account", "url": "/api/models/account#response" } }, "PipedreamDeleteAccountForCurrentUserRequest": { "type": "object", "description": "Inputs for removing a Pipedream account connection for the calling user.", "properties": { "accountId": { "type": "string", "minLength": 1, "description": "Which connected account to disconnect. Ownership is enforced downstream\nagainst the caller's own accounts — an id belonging to anyone else reads\nback as not found.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "accountId" ], "required": [ "accountId" ] }, "PipedreamDeleteAccountForCurrentUserResponse": { "type": "object", "description": "Result payload for removing a Pipedream account connection for the calling user.", "properties": { "deleted": { "type": "boolean", "description": "Whether the deletion operation reports the resource removed.", "x-presence": "implicit" } } }, "PipedreamDeleteExternalUserForCurrentUserRequest": { "type": "object", "description": "Inputs for removing the calling user’s Pipedream identity and connected accounts.", "properties": {} }, "PipedreamDeleteExternalUserForCurrentUserResponse": { "type": "object", "description": "Result payload for removing the calling user’s Pipedream identity and connected accounts.", "properties": { "deleted": { "type": "boolean", "description": "Whether the deletion operation reports the resource removed.", "x-presence": "implicit" }, "accountsDeleted": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "How many connected accounts went with the user. Counted from a read taken\njust before the delete, since Pipedream answers 204 with no body — a\nconnection added between the two calls is still deleted, just not counted.", "x-presence": "implicit" } } }, "PipedreamProxyForCurrentUserRequest": { "type": "object", "description": "Inputs for making an authenticated app API request through the calling user’s connected account.", "properties": { "accountId": { "type": "string", "minLength": 1, "description": "One of the caller's own connected accounts (id from list-accounts).\nAny other id reads back as not found.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "method": { "type": "string", "enum": [ "GET", "HEAD", "POST", "PUT", "PATCH", "DELETE" ], "description": "HTTP method used for the proxied or signed request.", "x-presence": "implicit", "x-protovalidate": { "string": { "in": [ "GET", "HEAD", "POST", "PUT", "PATCH", "DELETE" ] } }, "x-validation-scope": "request" }, "url": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "URL associated with the resource or outbound request.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1", "maxLen": "4096" } }, "x-validation-scope": "request" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Forwarded upstream (sent as x-pd-proxy-).", "x-presence": "collection" }, "body": { "type": "string", "format": "byte", "description": "Raw request body (base64 on the wire). Empty for GET/HEAD.", "x-presence": "implicit" } }, "x-request-required": [ "accountId", "method", "url" ], "required": [ "accountId", "method", "url" ] }, "PipedreamProxyForCurrentUserResponse": { "type": "object", "description": "Result payload for making an authenticated app API request through the calling user’s connected account.", "properties": { "status": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "HTTP status code returned by the connected app’s API.", "x-presence": "implicit" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "HTTP response headers returned by the connected app’s API.", "x-presence": "collection" }, "body": { "type": "string", "format": "byte", "description": "Raw upstream body (base64 on the wire), capped at 4 MiB. Larger bodies are rejected rather\nthan truncated, with OUT_OF_RANGE and reason RESPONSE_TOO_LARGE.", "x-presence": "implicit" } } }, "CreateThreadRequest": { "type": "object", "description": "Input for creating a conversation thread with its initial configuration.", "properties": { "title": { "type": "string", "description": "Display title of the conversation thread.", "x-presence": "implicit" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Labels associated with the conversation thread.", "x-presence": "collection" }, "activeProfileId": { "type": "string", "description": "Agent profile selected as the conversation’s active profile at creation.", "x-presence": "implicit" }, "activeProfileVersion": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Immutable version of the active profile to use. Zero selects its latest version.", "x-presence": "implicit" }, "externalId": { "type": "string", "maxLength": 255, "description": "Caller-supplied identifier associated with the conversation thread.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "255" } }, "x-validation-scope": "request" }, "defaultGenerationConfig": { "description": "Base model and tool configuration for turns in this conversation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GenerationConfigInput" } ] }, "conversationSettings": { "description": "Initial conversation settings, including prompt and integration configuration.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ConversationSettingsInput" } ] }, "contextManagementSettings": { "description": "Optional context-management settings for the new conversation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ContextManagementSettingsInput" } ] } } }, "ConversationSettingsInput": { "type": "object", "description": "Conversation-level settings controlling behavior across sends\n\n[`maxLoops`](/api/models/conversation-settings#request-field-maxloops) caps the **total number of generations** in a run — not the number of\ntool round trips. Default is **2**, which is what one round trip costs: a first\ngeneration to emit the tool call, a second to synthesize its result.\n\nOn the final generation the model is sent **no tools at all** (the request omits the\n[`tools`](/api/models/generation-config#request-field-tools) array), so it cannot emit a call there. `maxLoops: 1` therefore means a\nsingle tool-free reply — a valid way to ask for one, but not a way to get one tool\nround trip.", "properties": { "interruptPolicy": { "oneOf": [ { "type": "string", "enum": [ "INTERRUPT_POLICY_REJECT_NEW", "INTERRUPT_POLICY_CANCEL_ONGOING", "INTERRUPT_POLICY_QUEUE", "INTERRUPT_POLICY_IGNORE" ], "x-enumDescriptions": { "INTERRUPT_POLICY_REJECT_NEW": "Reject the new send with an error while a run is active; do not append its user message.", "INTERRUPT_POLICY_CANCEL_ONGOING": "Cancel the ongoing run and start a new run for the incoming message.", "INTERRUPT_POLICY_QUEUE": "Queue the incoming message to run after the current run completes.", "INTERRUPT_POLICY_IGNORE": "Accept the send without persisting its message or starting a new run; let the ongoing run\ncontinue." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "INTERRUPT_POLICY_REJECT_NEW", "number": 1, "canonical": true, "description": "Reject the new send with an error while a run is active; do not append its user message." }, { "name": "INTERRUPT_POLICY_CANCEL_ONGOING", "number": 2, "canonical": true, "description": "Cancel the ongoing run and start a new run for the incoming message." }, { "name": "INTERRUPT_POLICY_QUEUE", "number": 3, "canonical": true, "description": "Queue the incoming message to run after the current run completes." }, { "name": "INTERRUPT_POLICY_IGNORE", "number": 4, "canonical": true, "description": "Accept the send without persisting its message or starting a new run; let the ongoing run\ncontinue." } ], "x-enum-description": "How a conversation handles a new send while another generation run is active.", "description": "Policy for an incoming message while another generation run is active.", "x-presence": "implicit" }, "maxLoops": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Default limit on agentic generation loops for the conversation.", "x-presence": "implicit" }, "maxParallelTools": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum number of tool executions allowed concurrently by this configuration.", "x-presence": "implicit" }, "mcpServers": { "type": "array", "items": { "$ref": "#/components/schemas/MCPServerReferenceInput" }, "description": "MCP servers available to this conversation; used for tool discovery/filtering", "x-presence": "collection" }, "toolPolicy": { "description": "Optional per-conversation tool execution policy applied to AgentConfig", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ToolExecutionPolicyInput" } ] }, "promptVariables": { "type": "object", "additionalProperties": true, "description": "Typed values used when rendering profile prompt templates. They are shared by profiles in the\nconversation and can be refreshed with UpdatePromptVariables. Switching profiles renders the\nnew template with the same values.", "x-presence": "message" } }, "x-reference-model": { "title": "ConversationSettings", "url": "/api/models/conversation-settings#request" } }, "ContextManagementSettingsInput": { "type": "object", "description": "Configuration for context management", "properties": { "strategy": { "oneOf": [ { "type": "string", "enum": [ "CONTEXT_STRATEGY_COMPACTION", "CONTEXT_STRATEGY_WINDOWING", "CONTEXT_STRATEGY_NONE" ], "x-enumDescriptions": { "CONTEXT_STRATEGY_COMPACTION": "Use completed compaction summaries and remaining history; fall back to windowing when no\ncompleted summary is available.", "CONTEXT_STRATEGY_WINDOWING": "Keep a bounded window of recent conversation messages according to the windowing\nconfiguration.", "CONTEXT_STRATEGY_NONE": "Pass the conversation history without applying compaction or windowing." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "CONTEXT_STRATEGY_COMPACTION", "number": 1, "canonical": true, "description": "Use completed compaction summaries and remaining history; fall back to windowing when no\ncompleted summary is available." }, { "name": "CONTEXT_STRATEGY_WINDOWING", "number": 2, "canonical": true, "description": "Keep a bounded window of recent conversation messages according to the windowing\nconfiguration." }, { "name": "CONTEXT_STRATEGY_NONE", "number": 3, "canonical": true, "description": "Pass the conversation history without applying compaction or windowing." } ], "x-enum-description": "How stored conversation history is selected or summarized for model context.", "description": "Context management strategy selected for the conversation.", "x-presence": "implicit" }, "compactionConfig": { "description": "Configuration applied when summarizing the conversation context.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/CompactionConfigInput" } ] }, "windowingConfig": { "description": "Rules selecting the message window retained in model context.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/WindowingConfigInput" } ] }, "selectiveExclusionConfig": { "description": "Rules selecting content to omit from the model context.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/SelectiveExclusionConfigInput" } ] } }, "x-reference-model": { "title": "ContextManagementSettings", "url": "/api/models/context-management-settings#request" } }, "CompactionConfigInput": { "type": "object", "description": "Configuration for compaction strategy", "properties": { "mode": { "oneOf": [ { "type": "string", "enum": [ "COMPACTION_MODE_SYNC", "COMPACTION_MODE_ASYNC" ], "x-enumDescriptions": { "COMPACTION_MODE_SYNC": "Wait for compaction to finish before continuing the dependent operation.", "COMPACTION_MODE_ASYNC": "Start compaction asynchronously and apply its result when it becomes available." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "COMPACTION_MODE_SYNC", "number": 1, "canonical": true, "description": "Wait for compaction to finish before continuing the dependent operation." }, { "name": "COMPACTION_MODE_ASYNC", "number": 2, "canonical": true, "description": "Start compaction asynchronously and apply its result when it becomes available." } ], "x-enum-description": "Whether context compaction blocks the triggering operation or proceeds asynchronously.", "description": "Context compaction mode selected by the operation.", "x-presence": "implicit" }, "threshold": { "description": "Token-count or context-window-percentage threshold that triggers compaction.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ThresholdConfigInput" } ] }, "generationConfig": { "description": "Separate config for compaction LLM calls.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GenerationConfigInput" } ] }, "preserveRecent": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Messages to keep uncompacted.", "x-presence": "implicit" } }, "x-reference-model": { "title": "CompactionConfig", "url": "/api/models/compaction-config#request" } }, "ThresholdConfigInput": { "type": "object", "description": "Threshold configuration for triggering compaction", "properties": { "tokenCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Absolute token limit.", "x-presence": "explicit" }, "percentage": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "% of model's context window.", "x-presence": "explicit" } }, "x-reference-model": { "title": "ThresholdConfig", "url": "/api/models/threshold-config#request" }, "allOf": [ { "not": { "required": [ "tokenCount", "percentage" ] } } ] }, "WindowingConfigInput": { "type": "object", "description": "Configuration for windowing strategy", "properties": { "maxMessages": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum number of conversation messages to retain in the context window.", "x-presence": "implicit" } }, "x-reference-model": { "title": "WindowingConfig", "url": "/api/models/windowing-config#request" } }, "SelectiveExclusionConfigInput": { "type": "object", "description": "Configuration for selective exclusion", "properties": { "excludeToolResults": { "type": "boolean", "description": "Whether tool-result content is excluded from model context.", "x-presence": "implicit" }, "excludeImages": { "type": "boolean", "description": "Whether image content is excluded from model context.", "x-presence": "implicit" }, "excludeFiles": { "type": "boolean", "description": "Whether file content is excluded from model context.", "x-presence": "implicit" }, "excludeReasoning": { "type": "boolean", "description": "When true, reasoning/thinking content parts are excluded from context", "x-presence": "implicit" } }, "x-reference-model": { "title": "SelectiveExclusionConfig", "url": "/api/models/selective-exclusion-config#request" } }, "CreateThreadResponse": { "type": "object", "description": "Result of creating a conversation thread with its initial configuration.", "properties": { "thread": { "description": "Conversation thread returned by creation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ConversationThread" } ] } } }, "ConversationThread": { "type": "object", "description": "Lightweight thread registry record for multi-thread management", "properties": { "threadId": { "type": "string", "description": "Identifier of the conversation thread.", "x-presence": "implicit" }, "title": { "type": "string", "description": "Display title of the conversation thread.", "x-presence": "implicit" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Labels associated with the resource for organization or filtering.", "x-presence": "collection" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when this record was created.", "x-presence": "message" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time when this record was last updated.", "x-presence": "message" }, "externalId": { "type": "string", "description": "Caller-supplied identifier associated with the conversation thread.", "x-presence": "implicit" } }, "x-reference-model": { "title": "ConversationThread", "url": "/api/models/conversation-thread#response" } }, "ListThreadsRequest": { "type": "object", "description": "Input for listing conversation threads visible to the caller.", "properties": { "limit": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 2147483647, "description": "Max rows per page. 0 -> service default (50). Values >200 are clamped\nto 200 downstream. Negative values are rejected by proto validation.", "x-presence": "implicit", "x-protovalidate": { "int32": { "gte": 0 } }, "x-validation-scope": "request" }, "pageToken": { "type": "string", "description": "Opaque base64 cursor returned by prior call. Empty for first page.", "x-presence": "implicit" } } }, "ListThreadsResponse": { "type": "object", "description": "Result of listing conversation threads visible to the caller.", "properties": { "threads": { "type": "array", "items": { "$ref": "#/components/schemas/ThreadSummary" }, "description": "Conversation summaries returned for this page. An absent JSON list means this page is empty.", "x-presence": "collection" }, "nextPageToken": { "type": "string", "description": "Opaque continuation token for requesting the next page.", "x-presence": "implicit" } } }, "ThreadSummary": { "type": "object", "description": "Conversation summary returned by thread listing and detail operations.", "properties": { "threadId": { "type": "string", "description": "Identifier of the conversation thread.", "x-presence": "implicit" }, "userId": { "type": "string", "description": "Identifier of the user associated with the conversation thread.", "x-presence": "implicit" }, "title": { "type": "string", "description": "Display title of the conversation thread.", "x-presence": "implicit" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Labels associated with the conversation thread.", "x-presence": "collection" }, "status": { "oneOf": [ { "type": "string", "enum": [ "CONVERSATION_STATUS_ACTIVE", "CONVERSATION_STATUS_ARCHIVED" ], "x-enumDescriptions": { "CONVERSATION_STATUS_ACTIVE": "The conversation is in its active lifecycle state.", "CONVERSATION_STATUS_ARCHIVED": "The conversation has been archived; this is a stored lifecycle condition, not a generation\noutcome." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "CONVERSATION_STATUS_ACTIVE", "number": 1, "canonical": true, "description": "The conversation is in its active lifecycle state." }, { "name": "CONVERSATION_STATUS_ARCHIVED", "number": 2, "canonical": true, "description": "The conversation has been archived; this is a stored lifecycle condition, not a generation\noutcome." } ], "x-enum-description": "Lifecycle condition of a stored conversation.", "description": "Lifecycle status recorded for the conversation thread.", "x-presence": "implicit" }, "messageCount": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Number of messages recorded in the thread summary.", "x-presence": "implicit" }, "lastMessagePreview": { "type": "string", "description": "Text preview of the most recently projected message.", "x-presence": "implicit" }, "lastMessageAt": { "type": "string", "format": "date-time", "description": "Timestamp of the most recently projected message.", "x-presence": "message" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the conversation thread was created.", "x-presence": "message" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the conversation thread summary was last updated.", "x-presence": "message" }, "externalId": { "type": "string", "description": "Caller-supplied identifier associated with the conversation thread.", "x-presence": "implicit" } }, "x-reference-model": { "title": "ThreadSummary", "url": "/api/models/thread-summary#response" } }, "SendMessageRequest": { "type": "object", "description": "Input for starting an asynchronous generation from a user message.", "properties": { "conversationKey": { "type": "string", "minLength": 1, "description": "Identifier of the conversation thread.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "userMessage": { "description": "User message that starts the conversation turn. Required; its role is expected to be\nROLE_USER.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/MessageInput" } ], "x-protovalidate": { "required": true }, "x-validation-scope": "request" }, "overrideGenerationConfig": { "description": "Per-call configuration overrides applied to the active profile’s configuration, or otherwise\nthe conversation default. Supplied scalar values, including zero, empty or false, replace the\nbase value; omitted values inherit. Empty repeated/map values inherit, so clear_tools is used\nto clear inherited tools.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GenerationConfigInput" } ] }, "setActiveProfileId": { "type": "string", "description": "Set the active agent profile for this and subsequent conversation turns.", "x-presence": "implicit" }, "setActiveProfileVersion": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Version of the active agent profile forwarded with this turn.", "x-presence": "implicit" }, "overrideMcpServers": { "type": "array", "items": { "$ref": "#/components/schemas/MCPServerReferenceInput" }, "description": "MCP servers for this turn only. A nonempty list replaces the active profile’s or\nconversation’s list for tool discovery and execution; an empty list inherits the resolved\nconfiguration.", "x-presence": "collection" }, "experiment": { "description": "Dataset-run attribution for a scripted evaluation turn. Leave unset for ordinary conversation\ntraffic.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ExperimentContext" } ] } }, "x-request-required": [ "conversationKey", "userMessage" ], "required": [ "conversationKey", "userMessage" ] }, "MessageInput": { "type": "object", "description": "Chat message", "properties": { "role": { "oneOf": [ { "type": "string", "enum": [ "ROLE_SYSTEM", "ROLE_USER", "ROLE_ASSISTANT", "ROLE_TOOL" ], "x-enumDescriptions": { "ROLE_SYSTEM": "Instructions or context provided as a system message.", "ROLE_USER": "Input supplied by the user or customer application.", "ROLE_ASSISTANT": "Content produced by the assistant, including its tool-call requests.", "ROLE_TOOL": "A tool result supplied back to the assistant." } }, { "type": "integer", "format": "int32", "enum": [ 1, 2, 3, 4 ], "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "ROLE_SYSTEM", "number": 1, "canonical": true, "description": "Instructions or context provided as a system message." }, { "name": "ROLE_USER", "number": 2, "canonical": true, "description": "Input supplied by the user or customer application." }, { "name": "ROLE_ASSISTANT", "number": 3, "canonical": true, "description": "Content produced by the assistant, including its tool-call requests." }, { "name": "ROLE_TOOL", "number": 4, "canonical": true, "description": "A tool result supplied back to the assistant." } ], "x-enum-description": "Participant role attached to a conversation message and forwarded in model context.", "description": "Role of the participant that produced the chat message.", "x-presence": "implicit", "x-protovalidate": { "enum": { "definedOnly": true, "notIn": [ 0 ] } }, "x-validation-scope": "request" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/ContentPartInput" }, "description": "Content parts composing the chat message.", "x-presence": "collection" }, "toolCalls": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCallInput" }, "description": "Assistant-to-tool invocations.", "x-presence": "collection" }, "name": { "type": "string", "description": "Name identifying the sender of the chat message.", "x-presence": "implicit" }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp associated with the conversation message or event.", "x-presence": "message" }, "messageId": { "type": "string", "description": "Unique message identifier.", "x-presence": "implicit" }, "annotations": { "type": "array", "items": { "$ref": "#/components/schemas/AnnotationInput" }, "description": "Structured annotations (e.g., standardized web search URL citations, PDF reuse tokens)", "x-presence": "collection" }, "sequence": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Monotonic, per-conversation sequence number for stable ordering (1-based)", "x-presence": "implicit" }, "generatedBy": { "type": "string", "description": "Workflow run id or generator key that produced this message (e.g., workflow run key)", "x-presence": "implicit" }, "usage": { "description": "Token usage for this generation (populated for assistant messages)", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/UsageInput" } ] }, "model": { "type": "string", "description": "Model that generated this message (e.g., \"anthropic/claude-sonnet-4\")", "x-presence": "implicit" }, "generationContext": { "description": "Dynamic context that shaped this generation (memories, search params, turn info)", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GenerationContextInput" } ] }, "clientContext": { "description": "Arbitrary client-supplied context attached by the client for this message", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ClientContextInput" } ] }, "feedback": { "type": "array", "items": { "$ref": "#/components/schemas/MessageFeedbackInput" }, "description": "Feedback on an assistant message, with one entry per rater identified by rated_by. A later\nrating by the same rater replaces their earlier entry.", "x-presence": "collection" }, "sourceUserMessageId": { "type": "string", "description": "Identifier of the user message that opened this conversation turn. Generated messages in the\nsame turn share this value; a user message carries its own message_id. Empty on historical\nmessages that predate turn attribution.", "x-presence": "implicit" }, "finishReason": { "type": "string", "description": "Why the model stopped, verbatim from the provider: \"stop\",\n\"tool_calls\", \"length\", \"error\". Empty for historical messages.", "x-presence": "implicit" } }, "x-reference-model": { "title": "Message", "url": "/api/models/message#request" }, "x-protovalidate": { "cel": [ { "id": "message_content_or_tool_calls", "message": "content or tool_calls required", "expression": "size(this.content) > 0 || size(this.tool_calls) > 0" } ] }, "x-validation-scope": "request", "x-request-required": [ "role" ], "required": [ "role" ] }, "ContentPartInput": { "type": "object", "description": "Content parts composing a message (flattened structure for JSON compatibility)", "properties": { "type": { "oneOf": [ { "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" ], "x-enumDescriptions": { "CONTENT_PART_TYPE_TEXT": "Plain text carried by the content part.", "CONTENT_PART_TYPE_IMAGE_URL": "An image supplied through a remote URL.", "CONTENT_PART_TYPE_IMAGE_BASE64": "An image supplied as base64-encoded bytes.", "CONTENT_PART_TYPE_FILE_ID": "A provider file identifier or internal storage identifier resolved before generation.", "CONTENT_PART_TYPE_FILE_PATH": "A reference to a local file path.", "CONTENT_PART_TYPE_FILE_URL": "A file supplied through a public or signed URL.", "CONTENT_PART_TYPE_FILE_DATA_URL": "A file embedded in a data URL, including its media type and encoded data.", "CONTENT_PART_TYPE_AUDIO_BASE64": "Base64-encoded audio; the part metadata identifies its audio format.", "CONTENT_PART_TYPE_REASONING": "A reasoning segment returned by a model provider, when available." } }, { "type": "integer", "format": "int32", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ], "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "CONTENT_PART_TYPE_TEXT", "number": 1, "canonical": true, "description": "Plain text carried by the content part." }, { "name": "CONTENT_PART_TYPE_IMAGE_URL", "number": 2, "canonical": true, "description": "An image supplied through a remote URL." }, { "name": "CONTENT_PART_TYPE_IMAGE_BASE64", "number": 3, "canonical": true, "description": "An image supplied as base64-encoded bytes." }, { "name": "CONTENT_PART_TYPE_FILE_ID", "number": 4, "canonical": true, "description": "A provider file identifier or internal storage identifier resolved before generation." }, { "name": "CONTENT_PART_TYPE_FILE_PATH", "number": 5, "canonical": true, "description": "A reference to a local file path." }, { "name": "CONTENT_PART_TYPE_FILE_URL", "number": 6, "canonical": true, "description": "A file supplied through a public or signed URL." }, { "name": "CONTENT_PART_TYPE_FILE_DATA_URL", "number": 7, "canonical": true, "description": "A file embedded in a data URL, including its media type and encoded data." }, { "name": "CONTENT_PART_TYPE_AUDIO_BASE64", "number": 8, "canonical": true, "description": "Base64-encoded audio; the part metadata identifies its audio format." }, { "name": "CONTENT_PART_TYPE_REASONING", "number": 9, "canonical": true, "description": "A reasoning segment returned by a model provider, when available." } ], "x-enum-description": "Discriminator identifying which content representation a message part carries.", "description": "Kind of content carried by this message part.", "x-presence": "implicit", "x-protovalidate": { "enum": { "definedOnly": true } }, "x-validation-scope": "request" }, "content": { "type": "string", "description": "Text content, image URL, file ID, or base64-encoded data.", "x-presence": "implicit" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional type-specific metadata (dimensions, mime_type, etc.).", "x-presence": "collection" }, "cachePreferred": { "type": "boolean", "description": "Hint that this part is eligible for provider prompt caching.", "x-presence": "implicit" }, "structuredMessage": { "description": "Populated on TEXT parts for structured output responses.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/StructuredMessageInput" } ] } }, "x-reference-model": { "title": "ContentPart", "url": "/api/models/content-part#request" } }, "StructuredMessageInput": { "type": "object", "description": "A structured message whose JSON payload has been validated against\na declared schema. Consumers can trust that json_payload conforms\nto the schema identified by schema_name.\n\nInspect 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.", "properties": { "jsonPayload": { "type": "object", "additionalProperties": true, "description": "The validated JSON payload as a Struct (preserves types)", "x-presence": "message" }, "schemaName": { "type": "string", "description": "Schema identifier (from ResponseFormat.schema_name)", "x-presence": "implicit" }, "healed": { "type": "boolean", "description": "Whether response healing is reported for this structured message. Currently returned as false.", "x-presence": "implicit" } }, "x-reference-model": { "title": "StructuredMessage", "url": "/api/models/structured-message#request" } }, "ToolCallInput": { "type": "object", "description": "A single structured tool call emitted by the model\n\n[`clientToolDeadlineAt`](/api/models/tool-call#response-field-clienttooldeadlineat) is the client answer\nwindow. Expiry ends that wait and rejects late results; the timeout policy determines the outcome.", "properties": { "id": { "type": "string", "description": "Provider-supplied call id.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Name of the tool or function being invoked.", "x-presence": "implicit" }, "argumentsJson": { "type": "object", "additionalProperties": true, "description": "JSON object payload.", "x-presence": "message" }, "status": { "oneOf": [ { "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" ], "x-enumDescriptions": { "TOOL_EXECUTION_STATUS_PENDING": "The tool call is waiting to begin execution.", "TOOL_EXECUTION_STATUS_EXECUTING": "The tool call is currently executing.", "TOOL_EXECUTION_STATUS_COMPLETED": "The tool call completed successfully. Responses use this canonical spelling for numeric value\n3.", "TOOL_EXECUTION_STATUS_SUCCESS": "Legacy alias of TOOL_EXECUTION_STATUS_COMPLETED with the same numeric value; use COMPLETED for\nnew writes.", "TOOL_EXECUTION_STATUS_FAILED": "Tool execution ended unsuccessfully; inspect the tool error or end reason.", "TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION": "The tool call is waiting for approval before it can execute.", "TOOL_EXECUTION_STATUS_CANCELLED": "The tool call was cancelled before normal completion.", "TOOL_EXECUTION_STATUS_TIMED_OUT": "Tool execution ended because its time limit elapsed." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "TOOL_EXECUTION_STATUS_PENDING", "number": 1, "canonical": true, "description": "The tool call is waiting to begin execution." }, { "name": "TOOL_EXECUTION_STATUS_EXECUTING", "number": 2, "canonical": true, "description": "The tool call is currently executing." }, { "name": "TOOL_EXECUTION_STATUS_COMPLETED", "number": 3, "canonical": true, "description": "The tool call completed successfully. Responses use this canonical spelling for numeric value\n3." }, { "name": "TOOL_EXECUTION_STATUS_SUCCESS", "number": 3, "canonical": false, "description": "Legacy alias of TOOL_EXECUTION_STATUS_COMPLETED with the same numeric value; use COMPLETED for\nnew writes." }, { "name": "TOOL_EXECUTION_STATUS_FAILED", "number": 4, "canonical": true, "description": "Tool execution ended unsuccessfully; inspect the tool error or end reason." }, { "name": "TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION", "number": 5, "canonical": true, "description": "The tool call is waiting for approval before it can execute." }, { "name": "TOOL_EXECUTION_STATUS_CANCELLED", "number": 6, "canonical": true, "description": "The tool call was cancelled before normal completion." }, { "name": "TOOL_EXECUTION_STATUS_TIMED_OUT", "number": 7, "canonical": true, "description": "Tool execution ended because its time limit elapsed." } ], "x-enum-description": "Execution state of one tool call, including approval waiting and terminal outcomes.", "description": "Execution status recorded for the tool call.", "x-presence": "implicit" }, "resultJson": { "type": "object", "additionalProperties": true, "description": "Tool execution result (object).", "x-presence": "message" }, "executedAt": { "type": "string", "format": "date-time", "description": "Time when the tool execution was recorded.", "x-presence": "message" }, "serverId": { "type": "string", "description": "Which server provides this tool (for MCP tools).", "x-presence": "implicit" }, "isClientTool": { "type": "boolean", "description": "True if this is a client-side tool handled by client.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Tool description captured when the call is emitted, preserving the definition used for\nhistorical calls even if the tool configuration later changes.", "x-presence": "implicit" }, "parametersJsonSchema": { "type": "object", "additionalProperties": true, "description": "JSON Schema describing the tool’s input arguments.", "x-presence": "message" }, "requiresApprovalAt": { "type": "string", "format": "date-time", "description": "Deadline for an approval decision, calculated from the effective approval timeout. This is not\nthe time the call began waiting. An approval received after the deadline is rejected.", "x-presence": "message" }, "approvedAt": { "type": "string", "format": "date-time", "description": "Timestamp when approval decision was recorded (if approved/rejected)", "x-presence": "message" }, "approvedBy": { "type": "string", "description": "Identifier of the approver (user id, email, or actor key)", "x-presence": "implicit" }, "executionDuration": { "type": "string", "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]{1,9})?s$", "description": "End-to-end execution duration once terminal (includes tool server latency or client-side time)", "x-presence": "message" }, "endReason": { "type": "string", "description": "Why this call ended, in one short phrase — \"approval rejected\",\n\"approval timeout\", the underlying error. Set only once `status` is\nterminal, and empty on a clean COMPLETED.", "x-presence": "implicit" }, "clientToolDeadlineAt": { "type": "string", "format": "date-time", "description": "Deadline by which the client must submit a result for this call, stamped\nwhen the call is dispatched to a caller. Mirrors requires_approval_at.", "x-presence": "message" } }, "x-reference-model": { "title": "ToolCall", "url": "/api/models/tool-call#request" } }, "AnnotationInput": { "type": "object", "description": "Tagged provider annotation attached to generated content, such as a citation or PDF reference.", "properties": { "urlCitation": { "description": "Submessage fields (optional); populate the one matching kind", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/UrlCitationInput" } ] }, "pdf": { "description": "PDF annotation or parser configuration selected by the enclosing message.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PdfAnnotationInput" } ] }, "kind": { "oneOf": [ { "type": "string", "enum": [ "ANNOTATION_KIND_URL_CITATION", "ANNOTATION_KIND_PDF" ], "x-enumDescriptions": { "ANNOTATION_KIND_URL_CITATION": "A citation to a source identified by its URL.", "ANNOTATION_KIND_PDF": "An annotation identifying source content in a PDF document." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "ANNOTATION_KIND_URL_CITATION", "number": 1, "canonical": true, "description": "A citation to a source identified by its URL." }, { "name": "ANNOTATION_KIND_PDF", "number": 2, "canonical": true, "description": "An annotation identifying source content in a PDF document." } ], "x-enum-description": "Kind of source annotation associated with generated content.", "description": "Selected kind; determines which submessage is populated", "x-presence": "implicit" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Provider-specific extras.", "x-presence": "collection" } }, "x-reference-model": { "title": "Annotation", "url": "/api/models/annotation#request" } }, "UrlCitationInput": { "type": "object", "description": "=== Annotations ===\nWeb source and character range cited in generated message content.", "properties": { "url": { "type": "string", "description": "URL associated with the resource or outbound request.", "x-presence": "implicit" }, "title": { "type": "string", "description": "Title of the web page cited by this annotation.", "x-presence": "implicit" }, "content": { "type": "string", "description": "Excerpt or snippet of the cited web page.", "x-presence": "implicit" }, "startIndex": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Character index in message content.", "x-presence": "implicit" }, "endIndex": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Character index in message content.", "x-presence": "implicit" } }, "x-reference-model": { "title": "UrlCitation", "url": "/api/models/url-citation#request" } }, "PdfAnnotationInput": { "type": "object", "description": "Provider annotation identifying a parsed PDF and reusable parsing output.", "properties": { "filename": { "type": "string", "description": "Optional identifying information about the original file", "x-presence": "implicit" }, "engine": { "type": "string", "description": "PDF parsing engine used by provider (e.g., \"pdf-text\", \"mistral-ocr\", \"native\")", "x-presence": "implicit" }, "token": { "type": "string", "description": "Opaque provider token or handle allowing reuse without re-parsing", "x-presence": "implicit" }, "sourceUrl": { "type": "string", "description": "Optional: original source reference (public URL or data: URL)", "x-presence": "implicit" }, "hash": { "type": "string", "description": "Provider-supplied hash identifying the parsed file.", "x-presence": "implicit" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/ContentPartInput" }, "description": "Optional structured content returned by provider annotations (text, image URLs, etc.)\nNote: This can be large; include only if you need to round-trip provider annotations.", "x-presence": "collection" } }, "x-reference-model": { "title": "PdfAnnotation", "url": "/api/models/pdf-annotation#request" } }, "UsageInput": { "type": "object", "description": "Usage accounting", "properties": { "promptTokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Prompt-token usage reported by the model provider.", "x-presence": "implicit" }, "completionTokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Completion-token usage reported by the model provider.", "x-presence": "implicit" }, "totalTokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Total token usage reported by the model provider.", "x-presence": "implicit" }, "costEstimate": { "oneOf": [ { "type": "number", "format": "float" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Estimated cost in USD.", "x-presence": "implicit" }, "completionTokensDetails": { "description": "Breakdown of completion tokens.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/CompletionTokensDetailsInput" } ] }, "promptTokensDetails": { "description": "Breakdown of prompt tokens (cache).", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PromptTokensDetailsInput" } ] }, "costDetails": { "description": "Breakdown of upstream provider cost (BYOK routes).", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/CostDetailsInput" } ] }, "isByok": { "type": "boolean", "description": "Whether this generation used the customer's own model-provider key.", "x-presence": "implicit" } }, "x-reference-model": { "title": "Usage", "url": "/api/models/usage#request" } }, "CompletionTokensDetailsInput": { "type": "object", "description": "Breakdown of completion-token usage. Categories are measured by different upstream tokenizers\nand need not sum to completion_tokens; one category must not be derived by subtracting the\nothers.", "properties": { "reasoningTokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Tokens used for reasoning/thinking.", "x-presence": "implicit" }, "imageTokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Completion tokens emitted as image output.", "x-presence": "implicit" }, "audioTokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Completion tokens emitted as audio output.", "x-presence": "implicit" } }, "x-reference-model": { "title": "CompletionTokensDetails", "url": "/api/models/completion-tokens-details#request" } }, "PromptTokensDetailsInput": { "type": "object", "description": "Breakdown of prompt token usage by category (input-side cache accounting)", "properties": { "cachedTokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Prompt tokens served from cache (cache READ).", "x-presence": "implicit" }, "cacheWriteTokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Prompt tokens written to cache this call (cache WRITE).", "x-presence": "implicit" }, "audioTokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Prompt tokens from audio input (multimodal).", "x-presence": "implicit" }, "videoTokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Prompt tokens from video input (multimodal).", "x-presence": "implicit" } }, "x-reference-model": { "title": "PromptTokensDetails", "url": "/api/models/prompt-tokens-details#request" } }, "CostDetailsInput": { "type": "object", "description": "Breakdown of model-provider cost. When the customer supplies the provider key, usage.cost is\nzero and upstream_inference_cost reports the provider spend, split into prompt and completion\ncomponents.", "properties": { "upstreamInferenceCost": { "oneOf": [ { "type": "number", "format": "float" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Total upstream provider cost (USD) on BYOK routes.", "x-presence": "implicit" }, "upstreamInferencePromptCost": { "oneOf": [ { "type": "number", "format": "float" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Upstream cost attributed to prompt tokens (USD).", "x-presence": "implicit" }, "upstreamInferenceCompletionCost": { "oneOf": [ { "type": "number", "format": "float" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Upstream cost attributed to completion tokens (USD).", "x-presence": "implicit" } }, "x-reference-model": { "title": "CostDetails", "url": "/api/models/cost-details#request" } }, "GenerationContextInput": { "type": "object", "description": "Snapshot of retrieval inputs, prompt provenance, and turn position that shaped a generated message.", "properties": { "memories": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryReferenceInput" }, "description": "Memory records captured in the generation context.", "x-presence": "collection" }, "relations": { "type": "array", "items": { "$ref": "#/components/schemas/RelationReferenceInput" }, "description": "Graph relationships captured in the generation context.", "x-presence": "collection" }, "memorySearch": { "description": "Memory-query parameters and counts recorded for this generation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/MemorySearchParamsInput" } ] }, "turn": { "description": "Turn position and limit within the generation run.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/TurnInfoInput" } ] }, "languagePreference": { "type": "string", "description": "Language preference associated with the generation context.", "x-presence": "implicit" }, "resolvedSystemPrompt": { "type": "string", "description": "System prompt selected for this generation after prompt precedence is resolved. This field is\nretained in the schema but is not populated; use resolved_prompt_hash for recorded prompt\nidentity.", "x-presence": "implicit" }, "profileId": { "type": "string", "description": "Agent profile that produced this message (\"\" if none active).", "x-presence": "implicit" }, "model": { "type": "string", "description": "Model actually used for this generation.", "x-presence": "implicit" }, "promptSource": { "oneOf": [ { "type": "string", "enum": [ "PROMPT_SOURCE_CLIENT_OVERRIDE", "PROMPT_SOURCE_PROFILE_TEMPLATE", "PROMPT_SOURCE_DEFAULT_CONFIG" ], "x-enumDescriptions": { "PROMPT_SOURCE_CLIENT_OVERRIDE": "The caller supplied the prompt through the send request's generation-configuration override.", "PROMPT_SOURCE_PROFILE_TEMPLATE": "The prompt was rendered from the active agent profile template.", "PROMPT_SOURCE_DEFAULT_CONFIG": "The prompt came from the conversation or project default generation configuration." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "PROMPT_SOURCE_CLIENT_OVERRIDE", "number": 1, "canonical": true, "description": "The caller supplied the prompt through the send request's generation-configuration override." }, { "name": "PROMPT_SOURCE_PROFILE_TEMPLATE", "number": 2, "canonical": true, "description": "The prompt was rendered from the active agent profile template." }, { "name": "PROMPT_SOURCE_DEFAULT_CONFIG", "number": 3, "canonical": true, "description": "The prompt came from the conversation or project default generation configuration." } ], "x-enum-description": "Source that supplied the effective prompt for a generation turn.", "description": "Which precedence tier supplied the prompt.", "x-presence": "implicit" }, "baseConfig": { "description": "Generation configuration resolved before per-call overrides and timeout adjustments, with\nsystem_prompt omitted. The active profile supplies the base when selected; otherwise the\nconversation default does. May be absent on older turns or when neither supplies a\nconfiguration.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GenerationConfigInput" } ] }, "overrideConfig": { "description": "Per-call generation configuration supplied before the override merge.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GenerationConfigInput" } ] }, "profileVersion": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Immutable version of the active agent profile used to render this turn’s prompt. Absent on\nolder turns and turns without a profile template.", "x-presence": "implicit" }, "fragmentsVersion": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Version of the prompt-fragment set used to render the profile prompt.", "x-presence": "implicit" }, "promptVariables": { "type": "object", "additionalProperties": true, "description": "Values bound to the prompt template for this generation.", "x-presence": "message" }, "profileRenderFailed": { "type": "boolean", "description": "Whether rendering the profile prompt failed for this generation.", "x-presence": "implicit" }, "resolvedPromptHash": { "type": "string", "description": "SHA-256 hash, as 64 hexadecimal characters, of the resolved system prompt before the\ncurrent-time instruction is appended. Identifies prompt content only, excluding model and\nsampling parameters. Absent on older turns without prompt capture.", "x-presence": "implicit" }, "resolvedUserContext": { "type": "string", "description": "The [User Context] block as rendered into this turn's prompt: the user's\nname, locale, and location conditions (weather/AQI/UV/sun times). This is\nthe literal text the model received, not a reconstruction.\n\nEmpty when the user has no stored location, when enrichment degraded, or\non turns predating capture.", "x-presence": "implicit" }, "resolvedMcpServers": { "type": "array", "items": { "$ref": "#/components/schemas/MCPServerReferenceInput" }, "description": "The MCP server list that governed this turn — the tier actually resolved\n(conversation settings -> active profile -> per-turn override_mcp_servers),\nwhich is simultaneously the tool-discovery source and the CallTool\nallow/block basis.\n\nEmpty on turns predating capture and on threads with no MCP servers.", "x-presence": "collection" } }, "x-reference-model": { "title": "GenerationContext", "url": "/api/models/generation-context#request" } }, "MemoryReferenceInput": { "type": "object", "description": "A memory record retrieved and included in generation context.", "properties": { "memoryId": { "type": "string", "description": "Identifier of the retrieved memory record.", "x-presence": "implicit" }, "score": { "oneOf": [ { "type": "number", "format": "float" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Relevance score reported by the memory provider for this match.", "x-presence": "implicit" }, "memoryText": { "type": "string", "description": "Text of the retrieved memory record.", "x-presence": "implicit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when this record was created.", "x-presence": "message" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time when this record was last updated.", "x-presence": "message" } }, "x-reference-model": { "title": "MemoryReference", "url": "/api/models/memory-reference#request" } }, "RelationReferenceInput": { "type": "object", "description": "A graph relationship retrieved and included in generation context.", "properties": { "source": { "type": "string", "description": "Source entity of the memory graph relationship.", "x-presence": "implicit" }, "relationship": { "type": "string", "description": "Relationship label connecting the source and destination entities.", "x-presence": "implicit" }, "destination": { "type": "string", "description": "Destination entity of the memory graph relationship.", "x-presence": "implicit" } }, "x-reference-model": { "title": "RelationReference", "url": "/api/models/relation-reference#request" } }, "MemorySearchParamsInput": { "type": "object", "description": "Parameters used to retrieve relevant memories during generation.", "properties": { "query": { "type": "string", "description": "Text submitted to memory retrieval for this generation.", "x-presence": "implicit" }, "topK": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum memory matches requested during generation-context retrieval.", "x-presence": "implicit" }, "threshold": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Minimum relevance threshold requested for the memory query.", "x-presence": "implicit" }, "rerank": { "type": "boolean", "description": "Whether reranking was requested for the memory search.", "x-presence": "implicit" }, "resultsReturned": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of memory records returned by the search.", "x-presence": "implicit" }, "relationsReturned": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of graph relationships returned by the search.", "x-presence": "implicit" } }, "x-reference-model": { "title": "MemorySearchParams", "url": "/api/models/memory-search-params#request" } }, "TurnInfoInput": { "type": "object", "description": "Turn position within an agentic generation run", "properties": { "currentTurn": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Current turn position within the generation run.", "x-presence": "implicit" }, "maxTurns": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum turns configured for the generation run.", "x-presence": "implicit" } }, "x-reference-model": { "title": "TurnInfo", "url": "/api/models/turn-info#request" } }, "ClientContextInput": { "type": "object", "description": "Opaque caller-supplied attributes attached to a conversation message.\n\nValues 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.", "properties": { "values": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 1024 }, "maxProperties": 32, "description": "Arbitrary client-supplied context for this message (e.g. page, referrer,\ndevice, in-app flow). Keys/values are opaque strings.", "x-presence": "collection", "x-protovalidate": { "map": { "maxPairs": "32", "keys": { "string": { "maxLen": "64" } }, "values": { "string": { "maxLen": "1024" } } } }, "x-validation-scope": "request" } }, "x-reference-model": { "title": "ClientContext", "url": "/api/models/client-context#request" } }, "MessageFeedbackInput": { "type": "object", "description": "One user's feedback on an assistant-generated message.", "properties": { "kind": { "oneOf": [ { "type": "string", "enum": [ "FEEDBACK_KIND_THUMB", "FEEDBACK_KIND_SCALE" ], "x-enumDescriptions": { "FEEDBACK_KIND_THUMB": "Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice.", "FEEDBACK_KIND_SCALE": "Feedback expressed as an integer rating from 1 through 10." } }, { "type": "integer", "format": "int32", "enum": [ 1, 2 ], "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "FEEDBACK_KIND_THUMB", "number": 1, "canonical": true, "description": "Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice." }, { "name": "FEEDBACK_KIND_SCALE", "number": 2, "canonical": true, "description": "Feedback expressed as an integer rating from 1 through 10." } ], "x-enum-description": "Value scale used to interpret recorded feedback.", "description": "Rating representation used to interpret the feedback value.", "x-presence": "implicit", "x-protovalidate": { "enum": { "definedOnly": true, "notIn": [ 0 ] } }, "x-validation-scope": "request" }, "thumbUp": { "type": "boolean", "description": "Positive when true and negative when false; used for THUMB feedback.", "x-presence": "implicit" }, "rating": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 10, "description": "Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 10, "gte": 0 } }, "x-validation-scope": "request" }, "reason": { "type": "string", "maxLength": 1000, "description": "Optional explanation for the rating.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "1000" } }, "x-validation-scope": "request" }, "ratedAt": { "type": "string", "format": "date-time", "description": "Timestamp when feedback was submitted (server-set)", "x-presence": "message" }, "ratedBy": { "type": "string", "description": "Identifier of the user who submitted this feedback. Set by the server\nfrom the authenticated user identity; never client-supplied. Each user\nhas one feedback entry per message.", "x-presence": "implicit" } }, "x-reference-model": { "title": "MessageFeedback", "url": "/api/models/message-feedback#request" }, "x-request-required": [ "kind" ], "required": [ "kind" ] }, "ExperimentContext": { "type": "object", "description": "Dataset-run attribution attached when a scripted evaluation turn is sent. Supported on\nSendMessageRequest and SendMessageSyncRequest; ordinary conversation traffic leaves it unset.", "properties": { "datasetId": { "type": "string", "minLength": 1, "description": "Identifier of the dataset to which this run belongs. Required whenever experiment context is\nsupplied.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "runName": { "type": "string", "minLength": 1, "description": "Names the run. Repeating a run_name for the same dataset appends to that\nrun rather than starting a new one, because the derived experiment id is\ndeterministic — the same property that lets a retried turn land in the run\nit belongs to.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "datasetItemId": { "type": "string", "description": "Which dataset item this turn exercises. Optional: a run can be scored on\nits traces alone, and a harness that does not model items per-turn can\nleave it empty.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Free-text description displayed with the dataset run.", "x-presence": "implicit" }, "metadataJson": { "type": "string", "description": "Additional run metadata serialized as a JSON object string and carried through unchanged.", "x-presence": "implicit" }, "profileRevisionHash": { "type": "string", "description": "Profile revision fingerprint attached to the dataset run for comparison and attribution.", "x-presence": "implicit" } }, "x-reference-model": { "title": "ExperimentContext", "url": "/api/models/experiment-context#request" }, "x-request-required": [ "datasetId", "runName" ], "required": [ "datasetId", "runName" ] }, "SendMessageResponse": { "type": "object", "description": "Result of starting an asynchronous generation from a user message.", "properties": { "runId": { "type": "string", "description": "Identifier of the generation run associated with the operation.", "x-presence": "implicit" }, "interruptedPriorRun": { "type": "boolean", "description": "Whether submitting this turn interrupted a preceding generation run.", "x-presence": "implicit" } } }, "AppendMessageRequest": { "type": "object", "description": "Input for adding a message to conversation history without starting generation.", "properties": { "conversationKey": { "type": "string", "minLength": 1, "description": "Identifier of the conversation thread.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "message": { "description": "Required, for the same reason as SendMessageRequest.user_message and via\nthe same hole: this field's name is \"message\", the sends call theirs\n\"user_message\", and the lenient codec discards whichever one the caller did\nnot pick. Appending nothing costs no tokens, but applyAppendMessage returns\nnil for a nil message and the endpoint answers 200 regardless — so a\nCONTEXT UPDATE feed writes nothing and the TRIGGER that later reads the\nthread is missing the context it was told had landed.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/MessageInput" } ], "x-protovalidate": { "required": true }, "x-validation-scope": "request" } }, "x-request-required": [ "conversationKey", "message" ], "required": [ "conversationKey", "message" ] }, "AppendMessageResponse": { "type": "object", "description": "Result of adding a message to conversation history without starting generation. This message declares no response fields.", "properties": {} }, "SendMessageSyncRequest": { "type": "object", "description": "Input for submitting a user message and waiting for generation output.", "properties": { "conversationKey": { "type": "string", "minLength": 1, "description": "Identifier of the conversation thread.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "userMessage": { "description": "Required — see the note on SendMessageRequest.user_message. The sync path\nis where the defect was actually observed: it holds the connection open,\nwaits out a real generation, and hands back messages and a COMPLETED\nstatus, so a dropped turn field looks exactly like a working call.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/MessageInput" } ], "x-protovalidate": { "required": true }, "x-validation-scope": "request" }, "overrideGenerationConfig": { "description": "Per-call configuration overrides applied to the active profile’s configuration, or otherwise\nthe conversation default. Supplied scalar values, including zero, empty or false, replace the\nbase value; omitted values inherit. Empty repeated/map values inherit, so clear_tools is used\nto clear inherited tools.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GenerationConfigInput" } ] }, "setActiveProfileId": { "type": "string", "description": "Set the active agent profile for this and subsequent conversation turns.", "x-presence": "implicit" }, "setActiveProfileVersion": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Version of the active agent profile forwarded with this turn.", "x-presence": "implicit" }, "overrideMcpServers": { "type": "array", "items": { "$ref": "#/components/schemas/MCPServerReferenceInput" }, "description": "MCP servers for this turn only. A nonempty list replaces the active profile’s or\nconversation’s list for tool discovery and execution; an empty list inherits the resolved\nconfiguration.", "x-presence": "collection" }, "experiment": { "description": "Dataset-run attribution for a scripted evaluation turn. Leave unset for ordinary conversation\ntraffic.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ExperimentContext" } ] } }, "x-request-required": [ "conversationKey", "userMessage" ], "required": [ "conversationKey", "userMessage" ] }, "SendMessageSyncResponse": { "type": "object", "description": "Result of submitting a user message and waiting for generation output.", "properties": { "runId": { "type": "string", "description": "Identifier of the generation run associated with the operation.", "x-presence": "implicit" }, "interruptedPriorRun": { "type": "boolean", "description": "Whether submitting this turn interrupted a preceding generation run.", "x-presence": "implicit" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "description": "Conversation messages returned by the generation segment.", "x-presence": "collection" }, "status": { "oneOf": [ { "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" ], "x-enumDescriptions": { "AGENT_STATUS_ACTIVE": "The run is active and has not yet reached a more specific execution phase or terminal outcome.", "AGENT_STATUS_GENERATING": "The run is generating a model response.", "AGENT_STATUS_EXECUTING_TOOLS": "The run is executing server-side tools.", "AGENT_STATUS_COMPLETED": "The run finished successfully.", "AGENT_STATUS_FAILED": "The run ended with a failure; inspect its error or end reason.", "AGENT_STATUS_QUEUED": "The incoming message is queued behind an ongoing run under the queue interruption policy.", "AGENT_STATUS_AWAITING_CLIENT_TOOLS": "The run is waiting for the caller to execute client-side tools and submit their results.", "AGENT_STATUS_CANCELLED": "The run ended because a client or its invocation cancelled it.", "AGENT_STATUS_TIMED_OUT": "The run ended because a run-level time limit elapsed." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "AGENT_STATUS_ACTIVE", "number": 1, "canonical": true, "description": "The run is active and has not yet reached a more specific execution phase or terminal outcome." }, { "name": "AGENT_STATUS_GENERATING", "number": 2, "canonical": true, "description": "The run is generating a model response." }, { "name": "AGENT_STATUS_EXECUTING_TOOLS", "number": 3, "canonical": true, "description": "The run is executing server-side tools." }, { "name": "AGENT_STATUS_COMPLETED", "number": 4, "canonical": true, "description": "The run finished successfully." }, { "name": "AGENT_STATUS_FAILED", "number": 5, "canonical": true, "description": "The run ended with a failure; inspect its error or end reason." }, { "name": "AGENT_STATUS_QUEUED", "number": 6, "canonical": true, "description": "The incoming message is queued behind an ongoing run under the queue interruption policy." }, { "name": "AGENT_STATUS_AWAITING_CLIENT_TOOLS", "number": 7, "canonical": true, "description": "The run is waiting for the caller to execute client-side tools and submit their results." }, { "name": "AGENT_STATUS_CANCELLED", "number": 8, "canonical": true, "description": "The run ended because a client or its invocation cancelled it." }, { "name": "AGENT_STATUS_TIMED_OUT", "number": 9, "canonical": true, "description": "The run ended because a run-level time limit elapsed." } ], "x-enum-description": "Execution state of an agent generation run, separate from the reason a terminal run ended.", "description": "Generation status reported when the synchronous wait returns.", "x-presence": "implicit" }, "aggregateUsage": { "description": "Aggregated model usage reported for the generation run.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/Usage" } ] }, "error": { "description": "Structured error for partial success scenarios (some messages generated before failure).\nFull failures propagate as TerminalError → HTTP error status + RpcError JSON body.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/RpcError" } ] }, "pendingClientTools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCall" }, "description": "Tool calls dispatched for execution by the client.", "x-presence": "collection" }, "clientToolCursor": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Latest client-tool dispatch sequence represented by this response.", "x-presence": "implicit" } } }, "Message": { "type": "object", "description": "Chat message", "properties": { "role": { "oneOf": [ { "type": "string", "enum": [ "ROLE_SYSTEM", "ROLE_USER", "ROLE_ASSISTANT", "ROLE_TOOL" ], "x-enumDescriptions": { "ROLE_SYSTEM": "Instructions or context provided as a system message.", "ROLE_USER": "Input supplied by the user or customer application.", "ROLE_ASSISTANT": "Content produced by the assistant, including its tool-call requests.", "ROLE_TOOL": "A tool result supplied back to the assistant." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "ROLE_SYSTEM", "number": 1, "canonical": true, "description": "Instructions or context provided as a system message." }, { "name": "ROLE_USER", "number": 2, "canonical": true, "description": "Input supplied by the user or customer application." }, { "name": "ROLE_ASSISTANT", "number": 3, "canonical": true, "description": "Content produced by the assistant, including its tool-call requests." }, { "name": "ROLE_TOOL", "number": 4, "canonical": true, "description": "A tool result supplied back to the assistant." } ], "x-enum-description": "Participant role attached to a conversation message and forwarded in model context.", "description": "Role of the participant that produced the chat message.", "x-presence": "implicit", "x-protovalidate": { "enum": { "definedOnly": true, "notIn": [ 0 ] } }, "x-validation-scope": "request" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/ContentPart" }, "description": "Content parts composing the chat message.", "x-presence": "collection" }, "toolCalls": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCall" }, "description": "Assistant-to-tool invocations.", "x-presence": "collection" }, "name": { "type": "string", "description": "Name identifying the sender of the chat message.", "x-presence": "implicit" }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp associated with the conversation message or event.", "x-presence": "message" }, "messageId": { "type": "string", "description": "Unique message identifier.", "x-presence": "implicit" }, "annotations": { "type": "array", "items": { "$ref": "#/components/schemas/Annotation" }, "description": "Structured annotations (e.g., standardized web search URL citations, PDF reuse tokens)", "x-presence": "collection" }, "sequence": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Monotonic, per-conversation sequence number for stable ordering (1-based)", "x-presence": "implicit" }, "generatedBy": { "type": "string", "description": "Workflow run id or generator key that produced this message (e.g., workflow run key)", "x-presence": "implicit" }, "usage": { "description": "Token usage for this generation (populated for assistant messages)", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/Usage" } ] }, "model": { "type": "string", "description": "Model that generated this message (e.g., \"anthropic/claude-sonnet-4\")", "x-presence": "implicit" }, "generationContext": { "description": "Dynamic context that shaped this generation (memories, search params, turn info)", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GenerationContext" } ] }, "clientContext": { "description": "Arbitrary client-supplied context attached by the client for this message", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ClientContext" } ] }, "feedback": { "type": "array", "items": { "$ref": "#/components/schemas/MessageFeedback" }, "description": "Feedback on an assistant message, with one entry per rater identified by rated_by. A later\nrating by the same rater replaces their earlier entry.", "x-presence": "collection" }, "sourceUserMessageId": { "type": "string", "description": "Identifier of the user message that opened this conversation turn. Generated messages in the\nsame turn share this value; a user message carries its own message_id. Empty on historical\nmessages that predate turn attribution.", "x-presence": "implicit" }, "finishReason": { "type": "string", "description": "Why the model stopped, verbatim from the provider: \"stop\",\n\"tool_calls\", \"length\", \"error\". Empty for historical messages.", "x-presence": "implicit" } }, "x-reference-model": { "title": "Message", "url": "/api/models/message#response" }, "x-protovalidate": { "cel": [ { "id": "message_content_or_tool_calls", "message": "content or tool_calls required", "expression": "size(this.content) > 0 || size(this.tool_calls) > 0" } ] }, "x-validation-scope": "request", "x-request-required": [ "role" ] }, "ContentPart": { "type": "object", "description": "Content parts composing a message (flattened structure for JSON compatibility)", "properties": { "type": { "oneOf": [ { "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" ], "x-enumDescriptions": { "CONTENT_PART_TYPE_TEXT": "Plain text carried by the content part.", "CONTENT_PART_TYPE_IMAGE_URL": "An image supplied through a remote URL.", "CONTENT_PART_TYPE_IMAGE_BASE64": "An image supplied as base64-encoded bytes.", "CONTENT_PART_TYPE_FILE_ID": "A provider file identifier or internal storage identifier resolved before generation.", "CONTENT_PART_TYPE_FILE_PATH": "A reference to a local file path.", "CONTENT_PART_TYPE_FILE_URL": "A file supplied through a public or signed URL.", "CONTENT_PART_TYPE_FILE_DATA_URL": "A file embedded in a data URL, including its media type and encoded data.", "CONTENT_PART_TYPE_AUDIO_BASE64": "Base64-encoded audio; the part metadata identifies its audio format.", "CONTENT_PART_TYPE_REASONING": "A reasoning segment returned by a model provider, when available." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "CONTENT_PART_TYPE_TEXT", "number": 1, "canonical": true, "description": "Plain text carried by the content part." }, { "name": "CONTENT_PART_TYPE_IMAGE_URL", "number": 2, "canonical": true, "description": "An image supplied through a remote URL." }, { "name": "CONTENT_PART_TYPE_IMAGE_BASE64", "number": 3, "canonical": true, "description": "An image supplied as base64-encoded bytes." }, { "name": "CONTENT_PART_TYPE_FILE_ID", "number": 4, "canonical": true, "description": "A provider file identifier or internal storage identifier resolved before generation." }, { "name": "CONTENT_PART_TYPE_FILE_PATH", "number": 5, "canonical": true, "description": "A reference to a local file path." }, { "name": "CONTENT_PART_TYPE_FILE_URL", "number": 6, "canonical": true, "description": "A file supplied through a public or signed URL." }, { "name": "CONTENT_PART_TYPE_FILE_DATA_URL", "number": 7, "canonical": true, "description": "A file embedded in a data URL, including its media type and encoded data." }, { "name": "CONTENT_PART_TYPE_AUDIO_BASE64", "number": 8, "canonical": true, "description": "Base64-encoded audio; the part metadata identifies its audio format." }, { "name": "CONTENT_PART_TYPE_REASONING", "number": 9, "canonical": true, "description": "A reasoning segment returned by a model provider, when available." } ], "x-enum-description": "Discriminator identifying which content representation a message part carries.", "description": "Kind of content carried by this message part.", "x-presence": "implicit", "x-protovalidate": { "enum": { "definedOnly": true } }, "x-validation-scope": "request" }, "content": { "type": "string", "description": "Text content, image URL, file ID, or base64-encoded data.", "x-presence": "implicit" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional type-specific metadata (dimensions, mime_type, etc.).", "x-presence": "collection" }, "cachePreferred": { "type": "boolean", "description": "Hint that this part is eligible for provider prompt caching.", "x-presence": "implicit" }, "structuredMessage": { "description": "Populated on TEXT parts for structured output responses.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/StructuredMessage" } ] } }, "x-reference-model": { "title": "ContentPart", "url": "/api/models/content-part#response" } }, "StructuredMessage": { "type": "object", "description": "A structured message whose JSON payload has been validated against\na declared schema. Consumers can trust that json_payload conforms\nto the schema identified by schema_name.\n\nInspect 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.", "properties": { "jsonPayload": { "type": "object", "additionalProperties": true, "description": "The validated JSON payload as a Struct (preserves types)", "x-presence": "message" }, "schemaName": { "type": "string", "description": "Schema identifier (from ResponseFormat.schema_name)", "x-presence": "implicit" }, "healed": { "type": "boolean", "description": "Whether response healing is reported for this structured message. Currently returned as false.", "x-presence": "implicit" } }, "x-reference-model": { "title": "StructuredMessage", "url": "/api/models/structured-message#response" } }, "ToolCall": { "type": "object", "description": "A single structured tool call emitted by the model\n\n[`clientToolDeadlineAt`](/api/models/tool-call#response-field-clienttooldeadlineat) is the client answer\nwindow. Expiry ends that wait and rejects late results; the timeout policy determines the outcome.", "properties": { "id": { "type": "string", "description": "Provider-supplied call id.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Name of the tool or function being invoked.", "x-presence": "implicit" }, "argumentsJson": { "type": "object", "additionalProperties": true, "description": "JSON object payload.", "x-presence": "message" }, "status": { "oneOf": [ { "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" ], "x-enumDescriptions": { "TOOL_EXECUTION_STATUS_PENDING": "The tool call is waiting to begin execution.", "TOOL_EXECUTION_STATUS_EXECUTING": "The tool call is currently executing.", "TOOL_EXECUTION_STATUS_COMPLETED": "The tool call completed successfully. Responses use this canonical spelling for numeric value\n3.", "TOOL_EXECUTION_STATUS_FAILED": "Tool execution ended unsuccessfully; inspect the tool error or end reason.", "TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION": "The tool call is waiting for approval before it can execute.", "TOOL_EXECUTION_STATUS_CANCELLED": "The tool call was cancelled before normal completion.", "TOOL_EXECUTION_STATUS_TIMED_OUT": "Tool execution ended because its time limit elapsed." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "TOOL_EXECUTION_STATUS_PENDING", "number": 1, "canonical": true, "description": "The tool call is waiting to begin execution." }, { "name": "TOOL_EXECUTION_STATUS_EXECUTING", "number": 2, "canonical": true, "description": "The tool call is currently executing." }, { "name": "TOOL_EXECUTION_STATUS_COMPLETED", "number": 3, "canonical": true, "description": "The tool call completed successfully. Responses use this canonical spelling for numeric value\n3." }, { "name": "TOOL_EXECUTION_STATUS_SUCCESS", "number": 3, "canonical": false, "description": "Legacy alias of TOOL_EXECUTION_STATUS_COMPLETED with the same numeric value; use COMPLETED for\nnew writes." }, { "name": "TOOL_EXECUTION_STATUS_FAILED", "number": 4, "canonical": true, "description": "Tool execution ended unsuccessfully; inspect the tool error or end reason." }, { "name": "TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION", "number": 5, "canonical": true, "description": "The tool call is waiting for approval before it can execute." }, { "name": "TOOL_EXECUTION_STATUS_CANCELLED", "number": 6, "canonical": true, "description": "The tool call was cancelled before normal completion." }, { "name": "TOOL_EXECUTION_STATUS_TIMED_OUT", "number": 7, "canonical": true, "description": "Tool execution ended because its time limit elapsed." } ], "x-enum-description": "Execution state of one tool call, including approval waiting and terminal outcomes.", "description": "Execution status recorded for the tool call.", "x-presence": "implicit" }, "resultJson": { "type": "object", "additionalProperties": true, "description": "Tool execution result (object).", "x-presence": "message" }, "executedAt": { "type": "string", "format": "date-time", "description": "Time when the tool execution was recorded.", "x-presence": "message" }, "serverId": { "type": "string", "description": "Which server provides this tool (for MCP tools).", "x-presence": "implicit" }, "isClientTool": { "type": "boolean", "description": "True if this is a client-side tool handled by client.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Tool description captured when the call is emitted, preserving the definition used for\nhistorical calls even if the tool configuration later changes.", "x-presence": "implicit" }, "parametersJsonSchema": { "type": "object", "additionalProperties": true, "description": "JSON Schema describing the tool’s input arguments.", "x-presence": "message" }, "requiresApprovalAt": { "type": "string", "format": "date-time", "description": "Deadline for an approval decision, calculated from the effective approval timeout. This is not\nthe time the call began waiting. An approval received after the deadline is rejected.", "x-presence": "message" }, "approvedAt": { "type": "string", "format": "date-time", "description": "Timestamp when approval decision was recorded (if approved/rejected)", "x-presence": "message" }, "approvedBy": { "type": "string", "description": "Identifier of the approver (user id, email, or actor key)", "x-presence": "implicit" }, "executionDuration": { "type": "string", "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]{1,9})?s$", "description": "End-to-end execution duration once terminal (includes tool server latency or client-side time)", "x-presence": "message" }, "endReason": { "type": "string", "description": "Why this call ended, in one short phrase — \"approval rejected\",\n\"approval timeout\", the underlying error. Set only once `status` is\nterminal, and empty on a clean COMPLETED.", "x-presence": "implicit" }, "clientToolDeadlineAt": { "type": "string", "format": "date-time", "description": "Deadline by which the client must submit a result for this call, stamped\nwhen the call is dispatched to a caller. Mirrors requires_approval_at.", "x-presence": "message" } }, "x-reference-model": { "title": "ToolCall", "url": "/api/models/tool-call#response" } }, "Annotation": { "type": "object", "description": "Tagged provider annotation attached to generated content, such as a citation or PDF reference.", "properties": { "urlCitation": { "description": "Submessage fields (optional); populate the one matching kind", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/UrlCitation" } ] }, "pdf": { "description": "PDF annotation or parser configuration selected by the enclosing message.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PdfAnnotation" } ] }, "kind": { "oneOf": [ { "type": "string", "enum": [ "ANNOTATION_KIND_URL_CITATION", "ANNOTATION_KIND_PDF" ], "x-enumDescriptions": { "ANNOTATION_KIND_URL_CITATION": "A citation to a source identified by its URL.", "ANNOTATION_KIND_PDF": "An annotation identifying source content in a PDF document." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "ANNOTATION_KIND_URL_CITATION", "number": 1, "canonical": true, "description": "A citation to a source identified by its URL." }, { "name": "ANNOTATION_KIND_PDF", "number": 2, "canonical": true, "description": "An annotation identifying source content in a PDF document." } ], "x-enum-description": "Kind of source annotation associated with generated content.", "description": "Selected kind; determines which submessage is populated", "x-presence": "implicit" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Provider-specific extras.", "x-presence": "collection" } }, "x-reference-model": { "title": "Annotation", "url": "/api/models/annotation#response" } }, "UrlCitation": { "type": "object", "description": "=== Annotations ===\nWeb source and character range cited in generated message content.", "properties": { "url": { "type": "string", "description": "URL associated with the resource or outbound request.", "x-presence": "implicit" }, "title": { "type": "string", "description": "Title of the web page cited by this annotation.", "x-presence": "implicit" }, "content": { "type": "string", "description": "Excerpt or snippet of the cited web page.", "x-presence": "implicit" }, "startIndex": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Character index in message content.", "x-presence": "implicit" }, "endIndex": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Character index in message content.", "x-presence": "implicit" } }, "x-reference-model": { "title": "UrlCitation", "url": "/api/models/url-citation#response" } }, "PdfAnnotation": { "type": "object", "description": "Provider annotation identifying a parsed PDF and reusable parsing output.", "properties": { "filename": { "type": "string", "description": "Optional identifying information about the original file", "x-presence": "implicit" }, "engine": { "type": "string", "description": "PDF parsing engine used by provider (e.g., \"pdf-text\", \"mistral-ocr\", \"native\")", "x-presence": "implicit" }, "token": { "type": "string", "description": "Opaque provider token or handle allowing reuse without re-parsing", "x-presence": "implicit" }, "sourceUrl": { "type": "string", "description": "Optional: original source reference (public URL or data: URL)", "x-presence": "implicit" }, "hash": { "type": "string", "description": "Provider-supplied hash identifying the parsed file.", "x-presence": "implicit" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/ContentPart" }, "description": "Optional structured content returned by provider annotations (text, image URLs, etc.)\nNote: This can be large; include only if you need to round-trip provider annotations.", "x-presence": "collection" } }, "x-reference-model": { "title": "PdfAnnotation", "url": "/api/models/pdf-annotation#response" } }, "Usage": { "type": "object", "description": "Usage accounting", "properties": { "promptTokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Prompt-token usage reported by the model provider.", "x-presence": "implicit" }, "completionTokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Completion-token usage reported by the model provider.", "x-presence": "implicit" }, "totalTokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Total token usage reported by the model provider.", "x-presence": "implicit" }, "costEstimate": { "oneOf": [ { "type": "number", "format": "float" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Estimated cost in USD.", "x-presence": "implicit" }, "completionTokensDetails": { "description": "Breakdown of completion tokens.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/CompletionTokensDetails" } ] }, "promptTokensDetails": { "description": "Breakdown of prompt tokens (cache).", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PromptTokensDetails" } ] }, "costDetails": { "description": "Breakdown of upstream provider cost (BYOK routes).", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/CostDetails" } ] }, "isByok": { "type": "boolean", "description": "Whether this generation used the customer's own model-provider key.", "x-presence": "implicit" } }, "x-reference-model": { "title": "Usage", "url": "/api/models/usage#response" } }, "CompletionTokensDetails": { "type": "object", "description": "Breakdown of completion-token usage. Categories are measured by different upstream tokenizers\nand need not sum to completion_tokens; one category must not be derived by subtracting the\nothers.", "properties": { "reasoningTokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Tokens used for reasoning/thinking.", "x-presence": "implicit" }, "imageTokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Completion tokens emitted as image output.", "x-presence": "implicit" }, "audioTokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Completion tokens emitted as audio output.", "x-presence": "implicit" } }, "x-reference-model": { "title": "CompletionTokensDetails", "url": "/api/models/completion-tokens-details#response" } }, "PromptTokensDetails": { "type": "object", "description": "Breakdown of prompt token usage by category (input-side cache accounting)", "properties": { "cachedTokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Prompt tokens served from cache (cache READ).", "x-presence": "implicit" }, "cacheWriteTokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Prompt tokens written to cache this call (cache WRITE).", "x-presence": "implicit" }, "audioTokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Prompt tokens from audio input (multimodal).", "x-presence": "implicit" }, "videoTokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Prompt tokens from video input (multimodal).", "x-presence": "implicit" } }, "x-reference-model": { "title": "PromptTokensDetails", "url": "/api/models/prompt-tokens-details#response" } }, "CostDetails": { "type": "object", "description": "Breakdown of model-provider cost. When the customer supplies the provider key, usage.cost is\nzero and upstream_inference_cost reports the provider spend, split into prompt and completion\ncomponents.", "properties": { "upstreamInferenceCost": { "oneOf": [ { "type": "number", "format": "float" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Total upstream provider cost (USD) on BYOK routes.", "x-presence": "implicit" }, "upstreamInferencePromptCost": { "oneOf": [ { "type": "number", "format": "float" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Upstream cost attributed to prompt tokens (USD).", "x-presence": "implicit" }, "upstreamInferenceCompletionCost": { "oneOf": [ { "type": "number", "format": "float" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Upstream cost attributed to completion tokens (USD).", "x-presence": "implicit" } }, "x-reference-model": { "title": "CostDetails", "url": "/api/models/cost-details#response" } }, "GenerationContext": { "type": "object", "description": "Snapshot of retrieval inputs, prompt provenance, and turn position that shaped a generated message.", "properties": { "memories": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryReference" }, "description": "Memory records captured in the generation context.", "x-presence": "collection" }, "relations": { "type": "array", "items": { "$ref": "#/components/schemas/RelationReference" }, "description": "Graph relationships captured in the generation context.", "x-presence": "collection" }, "memorySearch": { "description": "Memory-query parameters and counts recorded for this generation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/MemorySearchParams" } ] }, "turn": { "description": "Turn position and limit within the generation run.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/TurnInfo" } ] }, "languagePreference": { "type": "string", "description": "Language preference associated with the generation context.", "x-presence": "implicit" }, "resolvedSystemPrompt": { "type": "string", "description": "System prompt selected for this generation after prompt precedence is resolved. This field is\nretained in the schema but is not populated; use resolved_prompt_hash for recorded prompt\nidentity.", "x-presence": "implicit" }, "profileId": { "type": "string", "description": "Agent profile that produced this message (\"\" if none active).", "x-presence": "implicit" }, "model": { "type": "string", "description": "Model actually used for this generation.", "x-presence": "implicit" }, "promptSource": { "oneOf": [ { "type": "string", "enum": [ "PROMPT_SOURCE_CLIENT_OVERRIDE", "PROMPT_SOURCE_PROFILE_TEMPLATE", "PROMPT_SOURCE_DEFAULT_CONFIG" ], "x-enumDescriptions": { "PROMPT_SOURCE_CLIENT_OVERRIDE": "The caller supplied the prompt through the send request's generation-configuration override.", "PROMPT_SOURCE_PROFILE_TEMPLATE": "The prompt was rendered from the active agent profile template.", "PROMPT_SOURCE_DEFAULT_CONFIG": "The prompt came from the conversation or project default generation configuration." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "PROMPT_SOURCE_CLIENT_OVERRIDE", "number": 1, "canonical": true, "description": "The caller supplied the prompt through the send request's generation-configuration override." }, { "name": "PROMPT_SOURCE_PROFILE_TEMPLATE", "number": 2, "canonical": true, "description": "The prompt was rendered from the active agent profile template." }, { "name": "PROMPT_SOURCE_DEFAULT_CONFIG", "number": 3, "canonical": true, "description": "The prompt came from the conversation or project default generation configuration." } ], "x-enum-description": "Source that supplied the effective prompt for a generation turn.", "description": "Which precedence tier supplied the prompt.", "x-presence": "implicit" }, "baseConfig": { "description": "Generation configuration resolved before per-call overrides and timeout adjustments, with\nsystem_prompt omitted. The active profile supplies the base when selected; otherwise the\nconversation default does. May be absent on older turns or when neither supplies a\nconfiguration.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GenerationConfig" } ] }, "overrideConfig": { "description": "Per-call generation configuration supplied before the override merge.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GenerationConfig" } ] }, "profileVersion": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Immutable version of the active agent profile used to render this turn’s prompt. Absent on\nolder turns and turns without a profile template.", "x-presence": "implicit" }, "fragmentsVersion": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Version of the prompt-fragment set used to render the profile prompt.", "x-presence": "implicit" }, "promptVariables": { "type": "object", "additionalProperties": true, "description": "Values bound to the prompt template for this generation.", "x-presence": "message" }, "profileRenderFailed": { "type": "boolean", "description": "Whether rendering the profile prompt failed for this generation.", "x-presence": "implicit" }, "resolvedPromptHash": { "type": "string", "description": "SHA-256 hash, as 64 hexadecimal characters, of the resolved system prompt before the\ncurrent-time instruction is appended. Identifies prompt content only, excluding model and\nsampling parameters. Absent on older turns without prompt capture.", "x-presence": "implicit" }, "resolvedUserContext": { "type": "string", "description": "The [User Context] block as rendered into this turn's prompt: the user's\nname, locale, and location conditions (weather/AQI/UV/sun times). This is\nthe literal text the model received, not a reconstruction.\n\nEmpty when the user has no stored location, when enrichment degraded, or\non turns predating capture.", "x-presence": "implicit" }, "resolvedMcpServers": { "type": "array", "items": { "$ref": "#/components/schemas/MCPServerReference" }, "description": "The MCP server list that governed this turn — the tier actually resolved\n(conversation settings -> active profile -> per-turn override_mcp_servers),\nwhich is simultaneously the tool-discovery source and the CallTool\nallow/block basis.\n\nEmpty on turns predating capture and on threads with no MCP servers.", "x-presence": "collection" } }, "x-reference-model": { "title": "GenerationContext", "url": "/api/models/generation-context#response" } }, "MemoryReference": { "type": "object", "description": "A memory record retrieved and included in generation context.", "properties": { "memoryId": { "type": "string", "description": "Identifier of the retrieved memory record.", "x-presence": "implicit" }, "score": { "oneOf": [ { "type": "number", "format": "float" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Relevance score reported by the memory provider for this match.", "x-presence": "implicit" }, "memoryText": { "type": "string", "description": "Text of the retrieved memory record.", "x-presence": "implicit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when this record was created.", "x-presence": "message" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time when this record was last updated.", "x-presence": "message" } }, "x-reference-model": { "title": "MemoryReference", "url": "/api/models/memory-reference#response" } }, "RelationReference": { "type": "object", "description": "A graph relationship retrieved and included in generation context.", "properties": { "source": { "type": "string", "description": "Source entity of the memory graph relationship.", "x-presence": "implicit" }, "relationship": { "type": "string", "description": "Relationship label connecting the source and destination entities.", "x-presence": "implicit" }, "destination": { "type": "string", "description": "Destination entity of the memory graph relationship.", "x-presence": "implicit" } }, "x-reference-model": { "title": "RelationReference", "url": "/api/models/relation-reference#response" } }, "MemorySearchParams": { "type": "object", "description": "Parameters used to retrieve relevant memories during generation.", "properties": { "query": { "type": "string", "description": "Text submitted to memory retrieval for this generation.", "x-presence": "implicit" }, "topK": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum memory matches requested during generation-context retrieval.", "x-presence": "implicit" }, "threshold": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Minimum relevance threshold requested for the memory query.", "x-presence": "implicit" }, "rerank": { "type": "boolean", "description": "Whether reranking was requested for the memory search.", "x-presence": "implicit" }, "resultsReturned": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of memory records returned by the search.", "x-presence": "implicit" }, "relationsReturned": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of graph relationships returned by the search.", "x-presence": "implicit" } }, "x-reference-model": { "title": "MemorySearchParams", "url": "/api/models/memory-search-params#response" } }, "TurnInfo": { "type": "object", "description": "Turn position within an agentic generation run", "properties": { "currentTurn": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Current turn position within the generation run.", "x-presence": "implicit" }, "maxTurns": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum turns configured for the generation run.", "x-presence": "implicit" } }, "x-reference-model": { "title": "TurnInfo", "url": "/api/models/turn-info#response" } }, "ClientContext": { "type": "object", "description": "Opaque caller-supplied attributes attached to a conversation message.\n\nValues 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.", "properties": { "values": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Arbitrary client-supplied context for this message (e.g. page, referrer,\ndevice, in-app flow). Keys/values are opaque strings.", "x-presence": "collection", "x-protovalidate": { "map": { "maxPairs": "32", "keys": { "string": { "maxLen": "64" } }, "values": { "string": { "maxLen": "1024" } } } }, "x-validation-scope": "request" } }, "x-reference-model": { "title": "ClientContext", "url": "/api/models/client-context#response" } }, "MessageFeedback": { "type": "object", "description": "One user's feedback on an assistant-generated message.", "properties": { "kind": { "oneOf": [ { "type": "string", "enum": [ "FEEDBACK_KIND_THUMB", "FEEDBACK_KIND_SCALE" ], "x-enumDescriptions": { "FEEDBACK_KIND_THUMB": "Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice.", "FEEDBACK_KIND_SCALE": "Feedback expressed as an integer rating from 1 through 10." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "FEEDBACK_KIND_THUMB", "number": 1, "canonical": true, "description": "Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice." }, { "name": "FEEDBACK_KIND_SCALE", "number": 2, "canonical": true, "description": "Feedback expressed as an integer rating from 1 through 10." } ], "x-enum-description": "Value scale used to interpret recorded feedback.", "description": "Rating representation used to interpret the feedback value.", "x-presence": "implicit", "x-protovalidate": { "enum": { "definedOnly": true, "notIn": [ 0 ] } }, "x-validation-scope": "request" }, "thumbUp": { "type": "boolean", "description": "Positive when true and negative when false; used for THUMB feedback.", "x-presence": "implicit" }, "rating": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 10, "gte": 0 } }, "x-validation-scope": "request" }, "reason": { "type": "string", "description": "Optional explanation for the rating.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "1000" } }, "x-validation-scope": "request" }, "ratedAt": { "type": "string", "format": "date-time", "description": "Timestamp when feedback was submitted (server-set)", "x-presence": "message" }, "ratedBy": { "type": "string", "description": "Identifier of the user who submitted this feedback. Set by the server\nfrom the authenticated user identity; never client-supplied. Each user\nhas one feedback entry per message.", "x-presence": "implicit" } }, "x-reference-model": { "title": "MessageFeedback", "url": "/api/models/message-feedback#response" }, "x-request-required": [ "kind" ] }, "RpcError": { "type": "object", "description": "Standardized error payload following google.rpc.Status (AIP-193).\nUsed across all response messages and event payloads.", "properties": { "code": { "oneOf": [ { "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" ], "x-enumDescriptions": { "ERROR_CODE_CANCELLED": "The caller cancelled the operation before it completed.", "ERROR_CODE_UNKNOWN": "The operation failed without a more specific error classification.", "ERROR_CODE_INVALID_ARGUMENT": "The request contains an invalid argument or field value.", "ERROR_CODE_DEADLINE_EXCEEDED": "The operation did not complete before its deadline.", "ERROR_CODE_NOT_FOUND": "The requested resource does not exist or could not be found.", "ERROR_CODE_ALREADY_EXISTS": "The requested creation conflicts with a resource that already exists.", "ERROR_CODE_PERMISSION_DENIED": "The authenticated caller is not permitted to perform the operation.", "ERROR_CODE_RESOURCE_EXHAUSTED": "A quota, rate limit or other capacity limit prevented the operation.", "ERROR_CODE_FAILED_PRECONDITION": "The operation requires a system or resource state that is not currently satisfied.", "ERROR_CODE_ABORTED": "The operation was aborted, for example by a concurrent modification conflict.", "ERROR_CODE_OUT_OF_RANGE": "An argument is outside the range supported by this operation.", "ERROR_CODE_UNIMPLEMENTED": "The requested operation is not implemented.", "ERROR_CODE_INTERNAL": "An internal failure prevented the operation from completing.", "ERROR_CODE_UNAVAILABLE": "The service or a required dependency is temporarily unavailable.", "ERROR_CODE_DATA_LOSS": "The operation encountered unrecoverable loss or corruption of data.", "ERROR_CODE_UNAUTHENTICATED": "Authentication credentials are missing or invalid.", "ERROR_CODE_MODEL_INVALID": "The requested model identifier is absent from the model catalog.", "ERROR_CODE_MODEL_UNAVAILABLE": "The model exists, but no provider is currently available to serve it.", "ERROR_CODE_MODERATION_FLAGGED": "Content moderation flagged the submitted content.", "ERROR_CODE_GENERATION_FAILED": "Model generation failed after its configured attempts.", "ERROR_CODE_TOOL_EXECUTION_FAILED": "Execution of a requested tool failed.", "ERROR_CODE_UPSTREAM_PROVIDER": "An upstream model provider returned an error.", "ERROR_CODE_VALIDATION_EXHAUSTED": "Structured-output validation still failed after the configured attempts.", "ERROR_CODE_PAYMENT_REQUIRED": "The account lacks the credits required for the operation." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "ERROR_CODE_CANCELLED", "number": 1, "canonical": true, "description": "The caller cancelled the operation before it completed." }, { "name": "ERROR_CODE_UNKNOWN", "number": 2, "canonical": true, "description": "The operation failed without a more specific error classification." }, { "name": "ERROR_CODE_INVALID_ARGUMENT", "number": 3, "canonical": true, "description": "The request contains an invalid argument or field value." }, { "name": "ERROR_CODE_DEADLINE_EXCEEDED", "number": 4, "canonical": true, "description": "The operation did not complete before its deadline." }, { "name": "ERROR_CODE_NOT_FOUND", "number": 5, "canonical": true, "description": "The requested resource does not exist or could not be found." }, { "name": "ERROR_CODE_ALREADY_EXISTS", "number": 6, "canonical": true, "description": "The requested creation conflicts with a resource that already exists." }, { "name": "ERROR_CODE_PERMISSION_DENIED", "number": 7, "canonical": true, "description": "The authenticated caller is not permitted to perform the operation." }, { "name": "ERROR_CODE_RESOURCE_EXHAUSTED", "number": 8, "canonical": true, "description": "A quota, rate limit or other capacity limit prevented the operation." }, { "name": "ERROR_CODE_FAILED_PRECONDITION", "number": 9, "canonical": true, "description": "The operation requires a system or resource state that is not currently satisfied." }, { "name": "ERROR_CODE_ABORTED", "number": 10, "canonical": true, "description": "The operation was aborted, for example by a concurrent modification conflict." }, { "name": "ERROR_CODE_OUT_OF_RANGE", "number": 11, "canonical": true, "description": "An argument is outside the range supported by this operation." }, { "name": "ERROR_CODE_UNIMPLEMENTED", "number": 12, "canonical": true, "description": "The requested operation is not implemented." }, { "name": "ERROR_CODE_INTERNAL", "number": 13, "canonical": true, "description": "An internal failure prevented the operation from completing." }, { "name": "ERROR_CODE_UNAVAILABLE", "number": 14, "canonical": true, "description": "The service or a required dependency is temporarily unavailable." }, { "name": "ERROR_CODE_DATA_LOSS", "number": 15, "canonical": true, "description": "The operation encountered unrecoverable loss or corruption of data." }, { "name": "ERROR_CODE_UNAUTHENTICATED", "number": 16, "canonical": true, "description": "Authentication credentials are missing or invalid." }, { "name": "ERROR_CODE_MODEL_INVALID", "number": 600, "canonical": true, "description": "The requested model identifier is absent from the model catalog." }, { "name": "ERROR_CODE_MODEL_UNAVAILABLE", "number": 601, "canonical": true, "description": "The model exists, but no provider is currently available to serve it." }, { "name": "ERROR_CODE_MODERATION_FLAGGED", "number": 602, "canonical": true, "description": "Content moderation flagged the submitted content." }, { "name": "ERROR_CODE_GENERATION_FAILED", "number": 603, "canonical": true, "description": "Model generation failed after its configured attempts." }, { "name": "ERROR_CODE_TOOL_EXECUTION_FAILED", "number": 604, "canonical": true, "description": "Execution of a requested tool failed." }, { "name": "ERROR_CODE_UPSTREAM_PROVIDER", "number": 605, "canonical": true, "description": "An upstream model provider returned an error." }, { "name": "ERROR_CODE_VALIDATION_EXHAUSTED", "number": 606, "canonical": true, "description": "Structured-output validation still failed after the configured attempts." }, { "name": "ERROR_CODE_PAYMENT_REQUIRED", "number": 607, "canonical": true, "description": "The account lacks the credits required for the operation." } ], "x-enum-description": "Machine-readable reason that a request or operation failed; inspect the accompanying error\ndetails for context.", "description": "Machine-readable error code. Clients switch on this field.", "x-presence": "implicit" }, "message": { "type": "string", "description": "Human-readable error description. Intended for developers, not end users.\nMust not be parsed programmatically — use code and details instead.", "x-presence": "implicit" }, "isTerminal": { "type": "boolean", "description": "Whether this error is terminal (non-retryable). When true, repeating the\nsame request will produce the same error. When false, transient condition\nmay resolve on retry.", "x-presence": "implicit" }, "details": { "description": "Structured error details. At most one of each detail type.\nFollows google.rpc.Status details pattern but uses concrete types\ninstead of google.protobuf.Any for type safety and codegen.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ErrorDetails" } ] } }, "x-reference-model": { "title": "RpcError", "url": "/api/models/rpc-error#response" } }, "ErrorDetails": { "type": "object", "description": "Typed error details container. Concrete fields instead of Any for\ntype safety across languages. At most one of each detail type.", "properties": { "errorInfo": { "description": "Identifies the error for machine consumption.\nREQUIRED on all errors per AIP-193 (enforced at Go helper level).", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ErrorInfo" } ] }, "retryInfo": { "description": "Retry guidance for transient errors.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/RetryInfo" } ] }, "fieldViolations": { "type": "array", "items": { "$ref": "#/components/schemas/FieldViolation" }, "description": "Field-level validation failures.", "x-presence": "collection" }, "upstreamError": { "description": "Upstream provider error context.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/UpstreamError" } ] }, "modelError": { "description": "Model-specific error context.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ModelError" } ] }, "helpLinks": { "type": "array", "items": { "$ref": "#/components/schemas/HelpLink" }, "description": "Help links for error resolution.", "x-presence": "collection" } }, "x-reference-model": { "title": "ErrorDetails", "url": "/api/models/error-details#response" } }, "ErrorInfo": { "type": "object", "description": "Machine-readable error identification (per AIP-193, every error must include this).", "properties": { "reason": { "type": "string", "description": "Stable machine-readable reason string (e.g., \"MODEL_NOT_FOUND\",\n\"RATE_LIMITED\", \"MODERATION_FLAGGED\").\nUnique within the domain. Clients may switch on this field.", "x-presence": "implicit" }, "domain": { "type": "string", "description": "Machine-readable namespace identifying the origin of the error.", "x-presence": "implicit" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Arbitrary key-value metadata. If the message field mentions a specific\nvalue (model name, field path, etc.), it MUST also appear here.", "x-presence": "collection" } }, "x-reference-model": { "title": "ErrorInfo", "url": "/api/models/error-info#response" } }, "RetryInfo": { "type": "object", "description": "Retry guidance for transient errors.", "properties": { "retryDelayMs": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Suggested minimum delay before retrying, in milliseconds.", "x-presence": "implicit" } }, "x-reference-model": { "title": "RetryInfo", "url": "/api/models/retry-info#response" } }, "FieldViolation": { "type": "object", "description": "A single field-level validation violation.", "properties": { "field": { "type": "string", "description": "Dot-separated path to the field (e.g., \"generation_config.model\").", "x-presence": "implicit" }, "description": { "type": "string", "description": "Human-readable description of the violation.", "x-presence": "implicit" } }, "x-reference-model": { "title": "FieldViolation", "url": "/api/models/field-violation#response" } }, "UpstreamError": { "type": "object", "description": "Context from an upstream provider error.", "properties": { "provider": { "type": "string", "description": "Name of the upstream provider that reported the error.", "x-presence": "implicit" }, "statusCode": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "HTTP status code returned by the provider.", "x-presence": "implicit" }, "rawBody": { "type": "string", "description": "Raw error body from the provider. Truncated to 512 bytes (enforced at Go level).", "x-presence": "implicit" } }, "x-reference-model": { "title": "UpstreamError", "url": "/api/models/upstream-error#response" } }, "ModelError": { "type": "object", "description": "Model-specific error context.", "properties": { "modelId": { "type": "string", "description": "The model ID that caused the error.", "x-presence": "implicit" }, "reason": { "type": "string", "description": "Why the model failed (e.g., \"invalid\", \"unavailable\", \"moderation_flagged\").", "x-presence": "implicit" }, "alternativesTried": { "type": "array", "items": { "type": "string" }, "description": "Alternative models that were tried or could be tried.", "x-presence": "collection" } }, "x-reference-model": { "title": "ModelError", "url": "/api/models/model-error#response" } }, "HelpLink": { "type": "object", "description": "A help link for error resolution.", "properties": { "url": { "type": "string", "description": "URL to documentation or resolution guide.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Description of what the link provides.", "x-presence": "implicit" } }, "x-reference-model": { "title": "HelpLink", "url": "/api/models/help-link#response" } }, "UpdateSettingsRequest": { "type": "object", "description": "Input for updating the conversation’s settings.", "properties": { "conversationKey": { "type": "string", "minLength": 1, "description": "Identifier of the conversation thread.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "settings": { "description": "Conversation settings returned or supplied for this operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ConversationSettingsInput" } ] } }, "x-request-required": [ "conversationKey" ], "required": [ "conversationKey" ] }, "UpdateSettingsResponse": { "type": "object", "description": "Result of updating the conversation’s settings.", "properties": { "settings": { "description": "Conversation settings returned or supplied for this operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ConversationSettings" } ] } } }, "ConversationSettings": { "type": "object", "description": "Conversation-level settings controlling behavior across sends\n\n[`maxLoops`](/api/models/conversation-settings#request-field-maxloops) caps the **total number of generations** in a run — not the number of\ntool round trips. Default is **2**, which is what one round trip costs: a first\ngeneration to emit the tool call, a second to synthesize its result.\n\nOn the final generation the model is sent **no tools at all** (the request omits the\n[`tools`](/api/models/generation-config#request-field-tools) array), so it cannot emit a call there. `maxLoops: 1` therefore means a\nsingle tool-free reply — a valid way to ask for one, but not a way to get one tool\nround trip.", "properties": { "interruptPolicy": { "oneOf": [ { "type": "string", "enum": [ "INTERRUPT_POLICY_REJECT_NEW", "INTERRUPT_POLICY_CANCEL_ONGOING", "INTERRUPT_POLICY_QUEUE", "INTERRUPT_POLICY_IGNORE" ], "x-enumDescriptions": { "INTERRUPT_POLICY_REJECT_NEW": "Reject the new send with an error while a run is active; do not append its user message.", "INTERRUPT_POLICY_CANCEL_ONGOING": "Cancel the ongoing run and start a new run for the incoming message.", "INTERRUPT_POLICY_QUEUE": "Queue the incoming message to run after the current run completes.", "INTERRUPT_POLICY_IGNORE": "Accept the send without persisting its message or starting a new run; let the ongoing run\ncontinue." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "INTERRUPT_POLICY_REJECT_NEW", "number": 1, "canonical": true, "description": "Reject the new send with an error while a run is active; do not append its user message." }, { "name": "INTERRUPT_POLICY_CANCEL_ONGOING", "number": 2, "canonical": true, "description": "Cancel the ongoing run and start a new run for the incoming message." }, { "name": "INTERRUPT_POLICY_QUEUE", "number": 3, "canonical": true, "description": "Queue the incoming message to run after the current run completes." }, { "name": "INTERRUPT_POLICY_IGNORE", "number": 4, "canonical": true, "description": "Accept the send without persisting its message or starting a new run; let the ongoing run\ncontinue." } ], "x-enum-description": "How a conversation handles a new send while another generation run is active.", "description": "Policy for an incoming message while another generation run is active.", "x-presence": "implicit" }, "maxLoops": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Default limit on agentic generation loops for the conversation.", "x-presence": "implicit" }, "maxParallelTools": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum number of tool executions allowed concurrently by this configuration.", "x-presence": "implicit" }, "mcpServers": { "type": "array", "items": { "$ref": "#/components/schemas/MCPServerReference" }, "description": "MCP servers available to this conversation; used for tool discovery/filtering", "x-presence": "collection" }, "toolPolicy": { "description": "Optional per-conversation tool execution policy applied to AgentConfig", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ToolExecutionPolicy" } ] }, "promptVariables": { "type": "object", "additionalProperties": true, "description": "Typed values used when rendering profile prompt templates. They are shared by profiles in the\nconversation and can be refreshed with UpdatePromptVariables. Switching profiles renders the\nnew template with the same values.", "x-presence": "message" } }, "x-reference-model": { "title": "ConversationSettings", "url": "/api/models/conversation-settings#response" } }, "UpdatePromptVariablesRequest": { "type": "object", "description": "Inputs for merging updated prompt variables into a conversation. The profile template is\nrendered with the updated variables on the next turn.", "properties": { "conversationKey": { "type": "string", "minLength": 1, "description": "Identifier of the conversation thread.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "variables": { "type": "object", "additionalProperties": true, "description": "Prompt-variable values to merge into the conversation’s settings.", "x-presence": "message" }, "updateMask": { "type": "string", "description": "Field paths selecting which prompt variables to update.", "x-presence": "message" } }, "x-request-required": [ "conversationKey" ], "required": [ "conversationKey" ] }, "UpdatePromptVariablesResponse": { "type": "object", "description": "Result of merging prompt variables into conversation settings.", "properties": { "settings": { "description": "The merged conversation settings (mirrors UpdateSettingsResponse).", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ConversationSettings" } ] } } }, "ConversationUpdateDefaultGenerationConfigRequest": { "type": "object", "description": "Input for updating the conversation’s base generation configuration.", "properties": { "conversationKey": { "type": "string", "minLength": 1, "description": "Identifier of the conversation thread.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "defaultGenerationConfig": { "description": "Base model and tool configuration for turns in this conversation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GenerationConfigInput" } ] } }, "x-request-required": [ "conversationKey" ], "required": [ "conversationKey" ] }, "ConversationUpdateDefaultGenerationConfigResponse": { "type": "object", "description": "Result of updating the conversation’s base generation configuration.", "properties": { "defaultGenerationConfig": { "description": "Base model and tool configuration for turns in this conversation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GenerationConfig" } ] } } }, "UpdateContextManagementSettingsRequest": { "type": "object", "description": "Input for updating the conversation’s context compaction configuration.", "properties": { "conversationKey": { "type": "string", "minLength": 1, "description": "Identifier of the conversation thread.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "contextManagementSettings": { "description": "Configuration governing the conversation’s context management and compaction.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ContextManagementSettingsInput" } ] } }, "x-request-required": [ "conversationKey" ], "required": [ "conversationKey" ] }, "UpdateContextManagementSettingsResponse": { "type": "object", "description": "Result of updating the conversation’s context compaction configuration.", "properties": { "contextManagementSettings": { "description": "Configuration governing the conversation’s context management and compaction.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ContextManagementSettings" } ] } } }, "ContextManagementSettings": { "type": "object", "description": "Configuration for context management", "properties": { "strategy": { "oneOf": [ { "type": "string", "enum": [ "CONTEXT_STRATEGY_COMPACTION", "CONTEXT_STRATEGY_WINDOWING", "CONTEXT_STRATEGY_NONE" ], "x-enumDescriptions": { "CONTEXT_STRATEGY_COMPACTION": "Use completed compaction summaries and remaining history; fall back to windowing when no\ncompleted summary is available.", "CONTEXT_STRATEGY_WINDOWING": "Keep a bounded window of recent conversation messages according to the windowing\nconfiguration.", "CONTEXT_STRATEGY_NONE": "Pass the conversation history without applying compaction or windowing." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "CONTEXT_STRATEGY_COMPACTION", "number": 1, "canonical": true, "description": "Use completed compaction summaries and remaining history; fall back to windowing when no\ncompleted summary is available." }, { "name": "CONTEXT_STRATEGY_WINDOWING", "number": 2, "canonical": true, "description": "Keep a bounded window of recent conversation messages according to the windowing\nconfiguration." }, { "name": "CONTEXT_STRATEGY_NONE", "number": 3, "canonical": true, "description": "Pass the conversation history without applying compaction or windowing." } ], "x-enum-description": "How stored conversation history is selected or summarized for model context.", "description": "Context management strategy selected for the conversation.", "x-presence": "implicit" }, "compactionConfig": { "description": "Configuration applied when summarizing the conversation context.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/CompactionConfig" } ] }, "windowingConfig": { "description": "Rules selecting the message window retained in model context.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/WindowingConfig" } ] }, "selectiveExclusionConfig": { "description": "Rules selecting content to omit from the model context.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/SelectiveExclusionConfig" } ] } }, "x-reference-model": { "title": "ContextManagementSettings", "url": "/api/models/context-management-settings#response" } }, "CompactionConfig": { "type": "object", "description": "Configuration for compaction strategy", "properties": { "mode": { "oneOf": [ { "type": "string", "enum": [ "COMPACTION_MODE_SYNC", "COMPACTION_MODE_ASYNC" ], "x-enumDescriptions": { "COMPACTION_MODE_SYNC": "Wait for compaction to finish before continuing the dependent operation.", "COMPACTION_MODE_ASYNC": "Start compaction asynchronously and apply its result when it becomes available." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "COMPACTION_MODE_SYNC", "number": 1, "canonical": true, "description": "Wait for compaction to finish before continuing the dependent operation." }, { "name": "COMPACTION_MODE_ASYNC", "number": 2, "canonical": true, "description": "Start compaction asynchronously and apply its result when it becomes available." } ], "x-enum-description": "Whether context compaction blocks the triggering operation or proceeds asynchronously.", "description": "Context compaction mode selected by the operation.", "x-presence": "implicit" }, "threshold": { "description": "Token-count or context-window-percentage threshold that triggers compaction.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ThresholdConfig" } ] }, "generationConfig": { "description": "Separate config for compaction LLM calls.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GenerationConfig" } ] }, "preserveRecent": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Messages to keep uncompacted.", "x-presence": "implicit" } }, "x-reference-model": { "title": "CompactionConfig", "url": "/api/models/compaction-config#response" } }, "ThresholdConfig": { "type": "object", "description": "Threshold configuration for triggering compaction", "properties": { "tokenCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Absolute token limit.", "x-presence": "explicit" }, "percentage": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "% of model's context window.", "x-presence": "explicit" } }, "x-reference-model": { "title": "ThresholdConfig", "url": "/api/models/threshold-config#response" }, "allOf": [ { "not": { "required": [ "tokenCount", "percentage" ] } } ] }, "WindowingConfig": { "type": "object", "description": "Configuration for windowing strategy", "properties": { "maxMessages": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum number of conversation messages to retain in the context window.", "x-presence": "implicit" } }, "x-reference-model": { "title": "WindowingConfig", "url": "/api/models/windowing-config#response" } }, "SelectiveExclusionConfig": { "type": "object", "description": "Configuration for selective exclusion", "properties": { "excludeToolResults": { "type": "boolean", "description": "Whether tool-result content is excluded from model context.", "x-presence": "implicit" }, "excludeImages": { "type": "boolean", "description": "Whether image content is excluded from model context.", "x-presence": "implicit" }, "excludeFiles": { "type": "boolean", "description": "Whether file content is excluded from model context.", "x-presence": "implicit" }, "excludeReasoning": { "type": "boolean", "description": "When true, reasoning/thinking content parts are excluded from context", "x-presence": "implicit" } }, "x-reference-model": { "title": "SelectiveExclusionConfig", "url": "/api/models/selective-exclusion-config#response" } }, "CompactConversationRequest": { "type": "object", "description": "Input for compacting the conversation’s model context.", "properties": { "conversationKey": { "type": "string", "minLength": 1, "description": "Identifier of the conversation thread.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "conversationKey" ], "required": [ "conversationKey" ] }, "CompactConversationResponse": { "type": "object", "description": "Result of compacting the conversation's model context. Token counts describe the selected\nsource span and its replacement summary, not the entire context window. Counts and duration\nare unavailable while asynchronous compaction is pending.", "properties": { "compactionId": { "type": "string", "description": "Identifier assigned to this context compaction.", "x-presence": "implicit" }, "tokensBefore": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Estimated tokens in the source messages being summarized, not the compaction trigger estimate.", "x-presence": "implicit" }, "tokensAfter": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Tokens in the generated summary, using provider-reported usage when available.", "x-presence": "implicit" }, "tokensSaved": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Source count minus summary count. The counts can use different methods; this is not an invoice saving.", "x-presence": "implicit" }, "durationMs": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Recorded compaction duration in milliseconds; it can be zero. Measure client elapsed time for latency comparisons.", "x-presence": "implicit" }, "status": { "oneOf": [ { "type": "string", "enum": [ "COMPACTION_STATUS_PENDING", "COMPACTION_STATUS_COMPLETED", "COMPACTION_STATUS_FAILED" ], "x-enumDescriptions": { "COMPACTION_STATUS_PENDING": "Compaction was started and its result is still pending.", "COMPACTION_STATUS_COMPLETED": "Compaction completed and produced its result.", "COMPACTION_STATUS_FAILED": "Compaction failed; inspect the associated error." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "COMPACTION_STATUS_PENDING", "number": 1, "canonical": true, "description": "Compaction was started and its result is still pending." }, { "name": "COMPACTION_STATUS_COMPLETED", "number": 2, "canonical": true, "description": "Compaction completed and produced its result." }, { "name": "COMPACTION_STATUS_FAILED", "number": 3, "canonical": true, "description": "Compaction failed; inspect the associated error." } ], "x-enum-description": "Execution state of a conversation context-compaction attempt.", "description": "Status reported for this context compaction.", "x-presence": "implicit" } } }, "GetConversationStateRequest": { "type": "object", "description": "Input for reading conversation history and current generation state. Supply exactly one of\nconversation_key or external_id; either addresses the same stored conversation.", "properties": { "conversationKey": { "type": "string", "description": "Generated conversation thread ID. Leave empty when addressing by external_id.", "x-presence": "implicit" }, "externalId": { "type": "string", "maxLength": 255, "description": "Client-supplied conversation identifier from CreateThread, resolved within the caller’s\nownership scope.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "255" } }, "x-validation-scope": "request" } }, "x-protovalidate": { "cel": [ { "id": "exactly_one_ref", "message": "exactly one of conversation_key or external_id must be set", "expression": "(this.conversation_key != '') != (this.external_id != '')" } ] }, "x-validation-scope": "request" }, "GetConversationStateResponse": { "type": "object", "description": "Result of reading conversation history and current generation state.", "properties": { "messageHistory": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "description": "Messages recorded in the conversation history.", "x-presence": "collection" }, "defaultGenerationConfig": { "description": "Base model and tool configuration for turns in this conversation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GenerationConfig" } ] }, "settings": { "description": "Conversation settings returned or supplied for this operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ConversationSettings" } ] }, "activeRunId": { "type": "string", "description": "Run tracked by the conversation. Older threads can retain the last run ID after it ends;\ninspect active_running before interpreting this as a currently active run.", "x-presence": "implicit" }, "activeRunning": { "type": "boolean", "description": "Whether an active run was observed. False may be omitted from JSON; it does not establish\nthat an accepted or queued request completed.", "x-presence": "implicit" }, "contextManagementSettings": { "description": "Configuration governing the conversation’s context management and compaction.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ContextManagementSettings" } ] }, "compactions": { "type": "array", "items": { "$ref": "#/components/schemas/Compaction" }, "description": "Recorded context compaction operations for the conversation.", "x-presence": "collection" }, "compactionInProgress": { "type": "boolean", "description": "Whether a context compaction is currently in progress.", "x-presence": "implicit" }, "totalUsage": { "description": "Cumulative token usage and cost for the conversation. Absent when no usage has accrued.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/Usage" } ] }, "externalId": { "type": "string", "description": "Echoed back so a caller addressing by conversation_key can reconcile its\nown identifier without a second lookup. Empty when none was supplied.", "x-presence": "implicit" }, "conversationKey": { "type": "string", "description": "System thread id keying the conversation, always populated. Mirror of\nexternal_id for the other direction: a caller addressing by external_id\nlearns the thread id without a second lookup.", "x-presence": "implicit" }, "lastRunStatus": { "oneOf": [ { "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" ], "x-enumDescriptions": { "AGENT_STATUS_ACTIVE": "The run is active and has not yet reached a more specific execution phase or terminal outcome.", "AGENT_STATUS_GENERATING": "The run is generating a model response.", "AGENT_STATUS_EXECUTING_TOOLS": "The run is executing server-side tools.", "AGENT_STATUS_COMPLETED": "The run finished successfully.", "AGENT_STATUS_FAILED": "The run ended with a failure; inspect its error or end reason.", "AGENT_STATUS_QUEUED": "The incoming message is queued behind an ongoing run under the queue interruption policy.", "AGENT_STATUS_AWAITING_CLIENT_TOOLS": "The run is waiting for the caller to execute client-side tools and submit their results.", "AGENT_STATUS_CANCELLED": "The run ended because a client or its invocation cancelled it.", "AGENT_STATUS_TIMED_OUT": "The run ended because a run-level time limit elapsed." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "AGENT_STATUS_ACTIVE", "number": 1, "canonical": true, "description": "The run is active and has not yet reached a more specific execution phase or terminal outcome." }, { "name": "AGENT_STATUS_GENERATING", "number": 2, "canonical": true, "description": "The run is generating a model response." }, { "name": "AGENT_STATUS_EXECUTING_TOOLS", "number": 3, "canonical": true, "description": "The run is executing server-side tools." }, { "name": "AGENT_STATUS_COMPLETED", "number": 4, "canonical": true, "description": "The run finished successfully." }, { "name": "AGENT_STATUS_FAILED", "number": 5, "canonical": true, "description": "The run ended with a failure; inspect its error or end reason." }, { "name": "AGENT_STATUS_QUEUED", "number": 6, "canonical": true, "description": "The incoming message is queued behind an ongoing run under the queue interruption policy." }, { "name": "AGENT_STATUS_AWAITING_CLIENT_TOOLS", "number": 7, "canonical": true, "description": "The run is waiting for the caller to execute client-side tools and submit their results." }, { "name": "AGENT_STATUS_CANCELLED", "number": 8, "canonical": true, "description": "The run ended because a client or its invocation cancelled it." }, { "name": "AGENT_STATUS_TIMED_OUT", "number": 9, "canonical": true, "description": "The run ended because a run-level time limit elapsed." } ], "x-enum-description": "Execution state of an agent generation run, separate from the reason a terminal run ended.", "description": "Terminal status of the last completed generation run. Unset until a run has ended.", "x-presence": "implicit" } } }, "Compaction": { "type": "object", "description": "Compaction metadata", "properties": { "id": { "type": "string", "description": "Identifier of the compaction record.", "x-presence": "implicit" }, "startSequence": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Sequence number of the first conversation message represented by the compaction.", "x-presence": "implicit" }, "endSequence": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Sequence number of the last conversation message represented by the compaction.", "x-presence": "implicit" }, "summary": { "type": "string", "description": "Summary text produced by conversation compaction.", "x-presence": "implicit" }, "originalTokenCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Estimated token count of the context before compaction.", "x-presence": "implicit" }, "summaryTokenCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Estimated token count of the generated summary.", "x-presence": "implicit" }, "modelUsed": { "type": "string", "description": "Model identifier used for the context compaction.", "x-presence": "implicit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when this record was created.", "x-presence": "message" }, "status": { "oneOf": [ { "type": "string", "enum": [ "COMPACTION_STATUS_PENDING", "COMPACTION_STATUS_COMPLETED", "COMPACTION_STATUS_FAILED" ], "x-enumDescriptions": { "COMPACTION_STATUS_PENDING": "Compaction was started and its result is still pending.", "COMPACTION_STATUS_COMPLETED": "Compaction completed and produced its result.", "COMPACTION_STATUS_FAILED": "Compaction failed; inspect the associated error." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "COMPACTION_STATUS_PENDING", "number": 1, "canonical": true, "description": "Compaction was started and its result is still pending." }, { "name": "COMPACTION_STATUS_COMPLETED", "number": 2, "canonical": true, "description": "Compaction completed and produced its result." }, { "name": "COMPACTION_STATUS_FAILED", "number": 3, "canonical": true, "description": "Compaction failed; inspect the associated error." } ], "x-enum-description": "Execution state of a conversation context-compaction attempt.", "description": "Execution state of the conversation compaction.", "x-presence": "implicit" }, "triggerReason": { "oneOf": [ { "type": "string", "enum": [ "COMPACTION_TRIGGER_REASON_THRESHOLD_EXCEEDED", "COMPACTION_TRIGGER_REASON_MANUAL" ], "x-enumDescriptions": { "COMPACTION_TRIGGER_REASON_THRESHOLD_EXCEEDED": "Context usage crossed the configured compaction threshold.", "COMPACTION_TRIGGER_REASON_MANUAL": "A caller explicitly requested compaction." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "COMPACTION_TRIGGER_REASON_THRESHOLD_EXCEEDED", "number": 1, "canonical": true, "description": "Context usage crossed the configured compaction threshold." }, { "name": "COMPACTION_TRIGGER_REASON_MANUAL", "number": 2, "canonical": true, "description": "A caller explicitly requested compaction." } ], "x-enum-description": "Reason a conversation context-compaction attempt was started.", "description": "Reason for triggering this compaction (auto threshold vs manual)", "x-presence": "implicit" } }, "x-reference-model": { "title": "Compaction", "url": "/api/models/compaction#response" } }, "RateMessageRequest": { "type": "object", "description": "Rate an assistant message in a thread. The rater is derived server-side\nfrom the verified request headers — never supplied by the client body.\nFor THUMB feedback, thumb_up supplies the choice and rating must be zero or omitted.\nFor SCALE feedback, rating must be from 1 through 10.", "properties": { "conversationKey": { "type": "string", "minLength": 1, "description": "Identifier of the conversation thread.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "messageSequence": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Per-conversation sequence number of the assistant-generated message to rate.", "x-presence": "implicit", "x-protovalidate": { "int64": { "gte": "1" } }, "x-validation-scope": "request" }, "kind": { "oneOf": [ { "type": "string", "enum": [ "FEEDBACK_KIND_THUMB", "FEEDBACK_KIND_SCALE" ], "x-enumDescriptions": { "FEEDBACK_KIND_THUMB": "Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice.", "FEEDBACK_KIND_SCALE": "Feedback expressed as an integer rating from 1 through 10." } }, { "type": "integer", "format": "int32", "enum": [ 1, 2 ], "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "FEEDBACK_KIND_THUMB", "number": 1, "canonical": true, "description": "Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice." }, { "name": "FEEDBACK_KIND_SCALE", "number": 2, "canonical": true, "description": "Feedback expressed as an integer rating from 1 through 10." } ], "x-enum-description": "Value scale used to interpret recorded feedback.", "description": "Rating representation used to interpret the thumb or scale value.", "x-presence": "implicit", "x-protovalidate": { "enum": { "definedOnly": true, "notIn": [ 0 ] } }, "x-validation-scope": "request" }, "thumbUp": { "type": "boolean", "description": "Positive when true and negative when false; used for THUMB feedback.", "x-presence": "implicit" }, "rating": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 10, "description": "Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 10, "gte": 0 } }, "x-validation-scope": "request" }, "reason": { "type": "string", "maxLength": 1000, "description": "Optional explanation for the rating.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "1000" } }, "x-validation-scope": "request" } }, "x-request-required": [ "conversationKey", "messageSequence", "kind" ], "required": [ "conversationKey", "messageSequence", "kind" ] }, "RateMessageResponse": { "type": "object", "description": "Result of recording the caller’s rating on a conversation message.", "properties": { "ratedMessage": { "description": "The rated message with the full (all-rater) feedback list applied", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/Message" } ] }, "isUpdate": { "type": "boolean", "description": "True when this replaced the caller's previous rating on this message", "x-presence": "implicit" } } }, "DeleteMessageRatingRequest": { "type": "object", "description": "Withdraw the caller's own rating on a message in a thread. As with\nRateMessage, the rater is derived server-side from the verified request\nheaders; there is deliberately no \"whose rating\" parameter.", "properties": { "conversationKey": { "type": "string", "minLength": 1, "description": "Identifier of the conversation thread.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "messageSequence": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Message whose rating to withdraw (by sequence number)", "x-presence": "implicit", "x-protovalidate": { "int64": { "gte": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "conversationKey", "messageSequence" ], "required": [ "conversationKey", "messageSequence" ] }, "DeleteMessageRatingResponse": { "type": "object", "description": "Result of withdrawing the caller’s rating on a conversation message.", "properties": { "ratedMessage": { "description": "The message with the caller's entry removed from the feedback list", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/Message" } ] }, "removed": { "type": "boolean", "description": "False when the caller had no rating on this message — an idempotent\nsuccess, not an error.", "x-presence": "implicit" } } }, "CreateDailySessionRequest": { "type": "object", "description": "Input for starting a Pipecat voice session for the conversation.", "properties": { "conversationKey": { "type": "string", "minLength": 1, "description": "Identifier of the conversation thread.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "agentName": { "type": "string", "description": "Name of the Pipecat agent to start for the voice session.", "x-presence": "implicit" }, "socayoConfig": { "description": "Socayo-specific agent configuration", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/SocayoAgentConfig" } ] }, "createDailyRoom": { "type": "boolean", "description": "Whether session creation should also create a Daily room.", "x-presence": "implicit" }, "dailyRoomProperties": { "description": "Properties passed to Daily when creating the session room.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/DailyRoomPropertiesInput" } ] }, "dailyMeetingTokenProperties": { "description": "Properties passed to Daily when issuing the meeting token.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/DailyMeetingTokenPropertiesInput" } ] }, "userData": { "description": "User data passed to the Pipecat agent at session startup.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/StartSessionUserDataInput" } ] } }, "x-request-required": [ "conversationKey" ], "required": [ "conversationKey" ] }, "SocayoAgentConfig": { "type": "object", "description": "Socayo-specific agent configuration (bundled)", "properties": { "conversationKey": { "type": "string", "minLength": 1, "description": "Conversation thread identifier associated with the voice session.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "userId": { "type": "string", "minLength": 1, "description": "Identifier of the user associated with the operation.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "provider": { "oneOf": [ { "type": "string", "enum": [ "AGENT_PROVIDER_PIPECAT_CLOUD", "AGENT_PROVIDER_CEREBRIUM" ], "x-enumDescriptions": { "AGENT_PROVIDER_PIPECAT_CLOUD": "Use the Pipecat Cloud hosting backend.", "AGENT_PROVIDER_CEREBRIUM": "Use the Cerebrium hosting backend." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "AGENT_PROVIDER_PIPECAT_CLOUD", "number": 1, "canonical": true, "description": "Use the Pipecat Cloud hosting backend." }, { "name": "AGENT_PROVIDER_CEREBRIUM", "number": 2, "canonical": true, "description": "Use the Cerebrium hosting backend." } ], "x-enum-description": "Hosting backend used to deploy or start a voice agent.", "description": "Backend provider to use for session orchestration; defaults to PIPECAT_CLOUD", "x-presence": "implicit" }, "tts": { "description": "Bundled sub-configs\nSpeech-synthesis configuration supplied to the Socayo agent.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/TTSConfig" } ] }, "heygen": { "description": "HeyGen avatar and voice configuration for the Socayo agent.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/HeyGenConfig" } ] }, "transport": { "description": "Audio transport settings used by the Socayo agent.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/TransportConfig" } ] }, "extras": { "type": "object", "additionalProperties": true, "description": "Optional extras for forward-compat", "x-presence": "message" } }, "x-reference-model": { "title": "SocayoAgentConfig", "url": "/api/models/socayo-agent-config#request" }, "x-request-required": [ "conversationKey", "userId" ], "required": [ "conversationKey", "userId" ] }, "TTSConfig": { "type": "object", "description": "Cartesia Sonic-3 TTS configuration", "properties": { "voiceId": { "type": "string", "minLength": 1, "description": "Provider-specific voice identifier (Cartesia voice_id)", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "model": { "type": "string", "description": "Optional Cartesia model identifier (e.g., \"sonic-english\")", "x-presence": "implicit" }, "sampleRate": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Optional sample rate override (Hz)", "x-presence": "implicit" }, "volume": { "type": "number", "format": "double", "minimum": 0.5, "maximum": 2, "description": "Volume multiplier (0.5..2.0)", "x-presence": "implicit", "x-protovalidate": { "double": { "lte": 2, "gte": 0.5 } }, "x-validation-scope": "request" }, "speed": { "type": "number", "format": "double", "minimum": 0.6, "maximum": 1.5, "description": "Speed multiplier (0.6..1.5)", "x-presence": "implicit", "x-protovalidate": { "double": { "lte": 1.5, "gte": 0.6 } }, "x-validation-scope": "request" }, "emotion": { "type": "string", "description": "Single emotion string (e.g., \"neutral\", \"excited\")", "x-presence": "implicit" }, "language": { "type": "string", "description": "Cartesia language code (e.g., \"EN\")", "x-presence": "implicit" } }, "x-reference-model": { "title": "TTSConfig", "url": "/api/models/tts-config#request" }, "x-request-required": [ "voiceId", "volume", "speed" ], "required": [ "voiceId", "volume", "speed" ] }, "HeyGenConfig": { "type": "object", "description": "HeyGen avatar/video configuration", "properties": { "enabled": { "type": "boolean", "description": "Whether this configuration is enabled.", "x-presence": "implicit" }, "avatarId": { "type": "string", "description": "Identifier of the HeyGen avatar used for the session.", "x-presence": "implicit" }, "version": { "type": "string", "description": "Version of the resource represented by this message.", "x-presence": "implicit" }, "quality": { "type": "string", "description": "Video-quality setting requested for the HeyGen avatar.", "x-presence": "implicit" }, "videoEncoding": { "type": "string", "description": "Video codec requested for the HeyGen avatar stream.", "x-presence": "implicit" }, "voice": { "description": "Voice configuration used by the HeyGen avatar.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/HeyGenVoiceSettings" } ] }, "knowledgeId": { "type": "string", "description": "Identifier of the HeyGen knowledge resource associated with the avatar.", "x-presence": "implicit" }, "knowledgeBase": { "type": "string", "description": "Knowledge text supplied to the HeyGen avatar configuration.", "x-presence": "implicit" }, "disableIdleTimeout": { "type": "boolean", "description": "Whether HeyGen’s session idle timeout is disabled.", "x-presence": "implicit" }, "activityIdleTimeout": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "HeyGen activity idle timeout, in seconds.", "x-presence": "implicit" } }, "x-reference-model": { "title": "HeyGenConfig", "url": "/api/models/hey-gen-config#request" } }, "HeyGenVoiceSettings": { "type": "object", "description": "HeyGen voice settings", "properties": { "voiceId": { "type": "string", "description": "Provider voice identifier used for speech synthesis.", "x-presence": "implicit" }, "rate": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Speech-rate setting passed to the HeyGen voice provider.", "x-presence": "implicit" }, "emotion": { "type": "string", "description": "Emotion setting passed to HeyGen voice synthesis.", "x-presence": "implicit" }, "elevenlabsSettings": { "description": "ElevenLabs synthesis settings associated with the HeyGen voice.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/HeyGenElevenLabsSettings" } ] } }, "x-reference-model": { "title": "HeyGenVoiceSettings", "url": "/api/models/hey-gen-voice-settings#request" } }, "HeyGenElevenLabsSettings": { "type": "object", "description": "ElevenLabs settings used within HeyGen voice configuration", "properties": { "stability": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "ElevenLabs voice-stability setting passed through HeyGen.", "x-presence": "implicit" }, "similarityBoost": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "ElevenLabs voice-similarity setting passed through HeyGen.", "x-presence": "implicit" }, "modelId": { "type": "string", "description": "ElevenLabs model identifier used for HeyGen voice synthesis.", "x-presence": "implicit" }, "style": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Integer style code.", "x-presence": "implicit" }, "useSpeakerBoost": { "type": "boolean", "description": "Whether ElevenLabs speaker boost is requested for the HeyGen voice.", "x-presence": "implicit" } }, "x-reference-model": { "title": "HeyGenElevenLabsSettings", "url": "/api/models/hey-gen-eleven-labs-settings#request" } }, "TransportConfig": { "type": "object", "description": "Transport audio configuration", "properties": { "audioInSampleRate": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Sample rate of incoming audio, in hertz.", "x-presence": "implicit" }, "audioOutSampleRate": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Sample rate of outgoing audio, in hertz.", "x-presence": "implicit" } }, "x-reference-model": { "title": "TransportConfig", "url": "/api/models/transport-config#request" } }, "DailyRoomPropertiesInput": { "type": "object", "description": "Daily room configuration (subset of frequently used fields)", "properties": { "nbf": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Timestamps (unix seconds)", "x-presence": "implicit" }, "exp": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Expiration time of the Daily room, as Unix seconds.", "x-presence": "implicit" }, "maxParticipants": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Limits\nMaximum number of participants allowed in the Daily room.", "x-presence": "implicit" }, "enablePeopleUi": { "type": "boolean", "description": "UI toggles\nWhether the Daily room exposes the participant-list controls.", "x-presence": "implicit" }, "enablePipUi": { "type": "boolean", "description": "Whether the Daily room enables picture-in-picture controls.", "x-presence": "implicit" }, "enableEmojiReactions": { "type": "boolean", "description": "Whether the Daily room enables emoji reactions.", "x-presence": "implicit" }, "enableHandRaising": { "type": "boolean", "description": "Whether the Daily room enables hand-raising controls.", "x-presence": "implicit" }, "enablePrejoinUi": { "type": "boolean", "description": "Whether the Daily room enables its prejoin screen.", "x-presence": "implicit" }, "enableLiveCaptionsUi": { "type": "boolean", "description": "Whether the Daily room exposes live-caption controls.", "x-presence": "implicit" }, "enableNetworkUi": { "type": "boolean", "description": "Whether the Daily room exposes network-information controls.", "x-presence": "implicit" }, "enableNoiseCancellationUi": { "type": "boolean", "description": "Whether the Daily room exposes noise-cancellation controls.", "x-presence": "implicit" }, "enableBreakoutRooms": { "type": "boolean", "description": "Whether the Daily room enables breakout rooms.", "x-presence": "implicit" }, "enableKnocking": { "type": "boolean", "description": "Access and permissions", "x-presence": "implicit" }, "ownerOnlyBroadcast": { "type": "boolean", "description": "Whether broadcasting is restricted to Daily room owners.", "x-presence": "implicit" }, "enforceUniqueUserIds": { "type": "boolean", "description": "Whether the Daily room requires participant user identifiers to be unique.", "x-presence": "implicit" }, "enableScreenshare": { "type": "boolean", "description": "Features\nWhether screen sharing is enabled in the Daily room.", "x-presence": "implicit" }, "enableVideoProcessingUi": { "type": "boolean", "description": "Whether the Daily room exposes video-processing controls.", "x-presence": "implicit" }, "enableChat": { "type": "boolean", "description": "Whether chat is enabled in the Daily room.", "x-presence": "implicit" }, "enableSharedChatHistory": { "type": "boolean", "description": "Whether the Daily room enables shared chat history.", "x-presence": "implicit" }, "enableAdvancedChat": { "type": "boolean", "description": "Whether the Daily room enables advanced chat features.", "x-presence": "implicit" }, "enableHiddenParticipants": { "type": "boolean", "description": "Whether the Daily room allows hidden participants.", "x-presence": "implicit" }, "startVideoOff": { "type": "boolean", "description": "Media defaults\nWhether participants join the Daily room with video initially off.", "x-presence": "implicit" }, "startAudioOff": { "type": "boolean", "description": "Whether participants join the Daily room with audio initially off.", "x-presence": "implicit" }, "enableRecording": { "oneOf": [ { "type": "string", "enum": [ "RECORDING_MODE_CLOUD", "RECORDING_MODE_LOCAL", "RECORDING_MODE_RAW_TRACKS", "RECORDING_MODE_DISABLED" ], "x-enumDescriptions": { "RECORDING_MODE_CLOUD": "Request the provider's cloud recording mode.", "RECORDING_MODE_LOCAL": "Request the provider's local recording mode.", "RECORDING_MODE_RAW_TRACKS": "Request separate raw media tracks for recording.", "RECORDING_MODE_DISABLED": "Explicitly disable room recording." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "RECORDING_MODE_CLOUD", "number": 1, "canonical": true, "description": "Request the provider's cloud recording mode." }, { "name": "RECORDING_MODE_LOCAL", "number": 2, "canonical": true, "description": "Request the provider's local recording mode." }, { "name": "RECORDING_MODE_RAW_TRACKS", "number": 3, "canonical": true, "description": "Request separate raw media tracks for recording." }, { "name": "RECORDING_MODE_DISABLED", "number": 4, "canonical": true, "description": "Explicitly disable room recording." } ], "x-enum-description": "Recording mode requested when configuring a Daily room.", "description": "Recording mode configured for the Daily room.", "x-presence": "implicit" }, "ejectAtRoomExp": { "type": "boolean", "description": "Whether participants are removed when the Daily room expires.", "x-presence": "implicit" }, "ejectAfterElapsed": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Elapsed session duration after which to eject participants, in seconds.", "x-presence": "implicit" }, "enableMeshSfu": { "type": "boolean", "description": "Topology and bandwidth", "x-presence": "implicit" }, "sfuSwitchover": { "oneOf": [ { "type": "number", "format": "float" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Daily topology setting controlling the switch to SFU transport.", "x-presence": "implicit" }, "enableAdaptiveSimulcast": { "type": "boolean", "description": "Whether adaptive simulcast is enabled for the Daily room.", "x-presence": "implicit" }, "enableMultipartyAdaptiveSimulcast": { "type": "boolean", "description": "Whether multiparty adaptive simulcast is enabled for the Daily room.", "x-presence": "implicit" }, "experimentalOptimizeLargeCalls": { "type": "boolean", "description": "Whether Daily’s experimental large-call optimization is requested.", "x-presence": "implicit" }, "lang": { "type": "string", "description": "Localization and hooks", "x-presence": "implicit" }, "meetingJoinHook": { "type": "string", "description": "Webhook URL invoked by the Daily meeting-join hook.", "x-presence": "implicit" }, "geo": { "type": "string", "description": "Regions\nRegion selected for the Daily room’s media infrastructure.", "x-presence": "implicit" }, "rtmpGeo": { "type": "string", "description": "Region selected for Daily RTMP streaming.", "x-presence": "implicit" }, "disableRtmpGeoFallback": { "type": "boolean", "description": "Whether automatic RTMP region fallback is disabled.", "x-presence": "implicit" }, "recordingsBucket": { "description": "Storage destination configured for Daily recordings.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/RecordingBucketConfigInput" } ] }, "transcriptionBucket": { "description": "Storage destination configured for Daily transcriptions.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/TranscriptionBucketConfigInput" } ] }, "recordingsTemplate": { "type": "string", "description": "Template used for recording object names in storage.", "x-presence": "implicit" }, "transcriptionTemplate": { "type": "string", "description": "Template used for transcription object names in storage.", "x-presence": "implicit" } }, "x-reference-model": { "title": "DailyRoomProperties", "url": "/api/models/daily-room-properties#request" } }, "RecordingBucketConfigInput": { "type": "object", "description": "Storage configs\nObject-storage destination and access settings for Daily recordings.", "properties": { "bucketName": { "type": "string", "description": "Object-storage bucket used for Daily recordings or transcriptions.", "x-presence": "implicit" }, "bucketRegion": { "type": "string", "description": "Region containing the Daily recording or transcription bucket.", "x-presence": "implicit" }, "assumeRoleArn": { "type": "string", "description": "Role ARN Daily uses when accessing the storage bucket.", "x-presence": "implicit" }, "allowApiAccess": { "type": "boolean", "description": "Whether Daily API access to bucket content is enabled.", "x-presence": "implicit" }, "allowStreamingFromBucket": { "type": "boolean", "description": "Whether streaming directly from the recording bucket is enabled.", "x-presence": "implicit" } }, "x-reference-model": { "title": "RecordingBucketConfig", "url": "/api/models/recording-bucket-config#request" } }, "TranscriptionBucketConfigInput": { "type": "object", "description": "Object-storage destination and access settings for Daily transcriptions.", "properties": { "bucketName": { "type": "string", "description": "Object-storage bucket used for Daily recordings or transcriptions.", "x-presence": "implicit" }, "bucketRegion": { "type": "string", "description": "Region containing the Daily recording or transcription bucket.", "x-presence": "implicit" }, "assumeRoleArn": { "type": "string", "description": "Role ARN Daily uses when accessing the storage bucket.", "x-presence": "implicit" }, "allowApiAccess": { "type": "boolean", "description": "Whether Daily API access to bucket content is enabled.", "x-presence": "implicit" } }, "x-reference-model": { "title": "TranscriptionBucketConfig", "url": "/api/models/transcription-bucket-config#request" } }, "DailyMeetingTokenPropertiesInput": { "type": "object", "description": "Daily meeting token configuration (subset of common fields)", "properties": { "isOwner": { "type": "boolean", "description": "Whether the issued Daily meeting token grants room-owner privileges.", "x-presence": "implicit" }, "enableAutoRecording": { "type": "boolean", "description": "Whether the Daily meeting token requests automatic recording.", "x-presence": "implicit" } }, "x-reference-model": { "title": "DailyMeetingTokenProperties", "url": "/api/models/daily-meeting-token-properties#request" } }, "StartSessionUserDataInput": { "type": "object", "description": "Arbitrary user data passed when starting a session, as simple key/value pairs", "properties": { "fields": { "type": "object", "additionalProperties": true, "description": "Structured user data passed to the session-start request.", "x-presence": "message" } }, "x-reference-model": { "title": "StartSessionUserData", "url": "/api/models/start-session-user-data#request" } }, "CreateDailySessionResponse": { "type": "object", "description": "Result of starting a Pipecat voice session for the conversation.", "properties": { "session": { "description": "Daily voice session connection information.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/DailySession" } ] } } }, "DailySession": { "type": "object", "description": "Session metadata for a Daily/Pipecat voice session", "properties": { "agentName": { "type": "string", "description": "Name of the Pipecat agent running this voice session.", "x-presence": "implicit" }, "sessionId": { "type": "string", "description": "Identifier of the Pipecat voice session.", "x-presence": "implicit" }, "dailyRoom": { "type": "string", "description": "Daily room address associated with the voice session.", "x-presence": "implicit" }, "dailyToken": { "type": "string", "description": "Daily meeting token issued for the voice session.", "x-presence": "implicit" }, "userData": { "description": "Generic body payload used to start.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/StartSessionUserData" } ] }, "dailyRoomProperties": { "description": "Properties passed to Daily when configuring the session room.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/DailyRoomProperties" } ] }, "dailyMeetingTokenProperties": { "description": "Properties passed to Daily when issuing the meeting token.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/DailyMeetingTokenProperties" } ] }, "startedAt": { "type": "string", "format": "date-time", "description": "Time when the operation started.", "x-presence": "message" } }, "x-reference-model": { "title": "DailySession", "url": "/api/models/daily-session#response" } }, "StartSessionUserData": { "type": "object", "description": "Arbitrary user data passed when starting a session, as simple key/value pairs", "properties": { "fields": { "type": "object", "additionalProperties": true, "description": "Structured user data passed to the session-start request.", "x-presence": "message" } }, "x-reference-model": { "title": "StartSessionUserData", "url": "/api/models/start-session-user-data#response" } }, "DailyRoomProperties": { "type": "object", "description": "Daily room configuration (subset of frequently used fields)", "properties": { "nbf": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Timestamps (unix seconds)", "x-presence": "implicit" }, "exp": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Expiration time of the Daily room, as Unix seconds.", "x-presence": "implicit" }, "maxParticipants": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Limits\nMaximum number of participants allowed in the Daily room.", "x-presence": "implicit" }, "enablePeopleUi": { "type": "boolean", "description": "UI toggles\nWhether the Daily room exposes the participant-list controls.", "x-presence": "implicit" }, "enablePipUi": { "type": "boolean", "description": "Whether the Daily room enables picture-in-picture controls.", "x-presence": "implicit" }, "enableEmojiReactions": { "type": "boolean", "description": "Whether the Daily room enables emoji reactions.", "x-presence": "implicit" }, "enableHandRaising": { "type": "boolean", "description": "Whether the Daily room enables hand-raising controls.", "x-presence": "implicit" }, "enablePrejoinUi": { "type": "boolean", "description": "Whether the Daily room enables its prejoin screen.", "x-presence": "implicit" }, "enableLiveCaptionsUi": { "type": "boolean", "description": "Whether the Daily room exposes live-caption controls.", "x-presence": "implicit" }, "enableNetworkUi": { "type": "boolean", "description": "Whether the Daily room exposes network-information controls.", "x-presence": "implicit" }, "enableNoiseCancellationUi": { "type": "boolean", "description": "Whether the Daily room exposes noise-cancellation controls.", "x-presence": "implicit" }, "enableBreakoutRooms": { "type": "boolean", "description": "Whether the Daily room enables breakout rooms.", "x-presence": "implicit" }, "enableKnocking": { "type": "boolean", "description": "Access and permissions", "x-presence": "implicit" }, "ownerOnlyBroadcast": { "type": "boolean", "description": "Whether broadcasting is restricted to Daily room owners.", "x-presence": "implicit" }, "enforceUniqueUserIds": { "type": "boolean", "description": "Whether the Daily room requires participant user identifiers to be unique.", "x-presence": "implicit" }, "enableScreenshare": { "type": "boolean", "description": "Features\nWhether screen sharing is enabled in the Daily room.", "x-presence": "implicit" }, "enableVideoProcessingUi": { "type": "boolean", "description": "Whether the Daily room exposes video-processing controls.", "x-presence": "implicit" }, "enableChat": { "type": "boolean", "description": "Whether chat is enabled in the Daily room.", "x-presence": "implicit" }, "enableSharedChatHistory": { "type": "boolean", "description": "Whether the Daily room enables shared chat history.", "x-presence": "implicit" }, "enableAdvancedChat": { "type": "boolean", "description": "Whether the Daily room enables advanced chat features.", "x-presence": "implicit" }, "enableHiddenParticipants": { "type": "boolean", "description": "Whether the Daily room allows hidden participants.", "x-presence": "implicit" }, "startVideoOff": { "type": "boolean", "description": "Media defaults\nWhether participants join the Daily room with video initially off.", "x-presence": "implicit" }, "startAudioOff": { "type": "boolean", "description": "Whether participants join the Daily room with audio initially off.", "x-presence": "implicit" }, "enableRecording": { "oneOf": [ { "type": "string", "enum": [ "RECORDING_MODE_CLOUD", "RECORDING_MODE_LOCAL", "RECORDING_MODE_RAW_TRACKS", "RECORDING_MODE_DISABLED" ], "x-enumDescriptions": { "RECORDING_MODE_CLOUD": "Request the provider's cloud recording mode.", "RECORDING_MODE_LOCAL": "Request the provider's local recording mode.", "RECORDING_MODE_RAW_TRACKS": "Request separate raw media tracks for recording.", "RECORDING_MODE_DISABLED": "Explicitly disable room recording." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "RECORDING_MODE_CLOUD", "number": 1, "canonical": true, "description": "Request the provider's cloud recording mode." }, { "name": "RECORDING_MODE_LOCAL", "number": 2, "canonical": true, "description": "Request the provider's local recording mode." }, { "name": "RECORDING_MODE_RAW_TRACKS", "number": 3, "canonical": true, "description": "Request separate raw media tracks for recording." }, { "name": "RECORDING_MODE_DISABLED", "number": 4, "canonical": true, "description": "Explicitly disable room recording." } ], "x-enum-description": "Recording mode requested when configuring a Daily room.", "description": "Recording mode configured for the Daily room.", "x-presence": "implicit" }, "ejectAtRoomExp": { "type": "boolean", "description": "Whether participants are removed when the Daily room expires.", "x-presence": "implicit" }, "ejectAfterElapsed": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Elapsed session duration after which to eject participants, in seconds.", "x-presence": "implicit" }, "enableMeshSfu": { "type": "boolean", "description": "Topology and bandwidth", "x-presence": "implicit" }, "sfuSwitchover": { "oneOf": [ { "type": "number", "format": "float" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Daily topology setting controlling the switch to SFU transport.", "x-presence": "implicit" }, "enableAdaptiveSimulcast": { "type": "boolean", "description": "Whether adaptive simulcast is enabled for the Daily room.", "x-presence": "implicit" }, "enableMultipartyAdaptiveSimulcast": { "type": "boolean", "description": "Whether multiparty adaptive simulcast is enabled for the Daily room.", "x-presence": "implicit" }, "experimentalOptimizeLargeCalls": { "type": "boolean", "description": "Whether Daily’s experimental large-call optimization is requested.", "x-presence": "implicit" }, "lang": { "type": "string", "description": "Localization and hooks", "x-presence": "implicit" }, "meetingJoinHook": { "type": "string", "description": "Webhook URL invoked by the Daily meeting-join hook.", "x-presence": "implicit" }, "geo": { "type": "string", "description": "Regions\nRegion selected for the Daily room’s media infrastructure.", "x-presence": "implicit" }, "rtmpGeo": { "type": "string", "description": "Region selected for Daily RTMP streaming.", "x-presence": "implicit" }, "disableRtmpGeoFallback": { "type": "boolean", "description": "Whether automatic RTMP region fallback is disabled.", "x-presence": "implicit" }, "recordingsBucket": { "description": "Storage destination configured for Daily recordings.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/RecordingBucketConfig" } ] }, "transcriptionBucket": { "description": "Storage destination configured for Daily transcriptions.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/TranscriptionBucketConfig" } ] }, "recordingsTemplate": { "type": "string", "description": "Template used for recording object names in storage.", "x-presence": "implicit" }, "transcriptionTemplate": { "type": "string", "description": "Template used for transcription object names in storage.", "x-presence": "implicit" } }, "x-reference-model": { "title": "DailyRoomProperties", "url": "/api/models/daily-room-properties#response" } }, "RecordingBucketConfig": { "type": "object", "description": "Storage configs\nObject-storage destination and access settings for Daily recordings.", "properties": { "bucketName": { "type": "string", "description": "Object-storage bucket used for Daily recordings or transcriptions.", "x-presence": "implicit" }, "bucketRegion": { "type": "string", "description": "Region containing the Daily recording or transcription bucket.", "x-presence": "implicit" }, "assumeRoleArn": { "type": "string", "description": "Role ARN Daily uses when accessing the storage bucket.", "x-presence": "implicit" }, "allowApiAccess": { "type": "boolean", "description": "Whether Daily API access to bucket content is enabled.", "x-presence": "implicit" }, "allowStreamingFromBucket": { "type": "boolean", "description": "Whether streaming directly from the recording bucket is enabled.", "x-presence": "implicit" } }, "x-reference-model": { "title": "RecordingBucketConfig", "url": "/api/models/recording-bucket-config#response" } }, "TranscriptionBucketConfig": { "type": "object", "description": "Object-storage destination and access settings for Daily transcriptions.", "properties": { "bucketName": { "type": "string", "description": "Object-storage bucket used for Daily recordings or transcriptions.", "x-presence": "implicit" }, "bucketRegion": { "type": "string", "description": "Region containing the Daily recording or transcription bucket.", "x-presence": "implicit" }, "assumeRoleArn": { "type": "string", "description": "Role ARN Daily uses when accessing the storage bucket.", "x-presence": "implicit" }, "allowApiAccess": { "type": "boolean", "description": "Whether Daily API access to bucket content is enabled.", "x-presence": "implicit" } }, "x-reference-model": { "title": "TranscriptionBucketConfig", "url": "/api/models/transcription-bucket-config#response" } }, "DailyMeetingTokenProperties": { "type": "object", "description": "Daily meeting token configuration (subset of common fields)", "properties": { "isOwner": { "type": "boolean", "description": "Whether the issued Daily meeting token grants room-owner privileges.", "x-presence": "implicit" }, "enableAutoRecording": { "type": "boolean", "description": "Whether the Daily meeting token requests automatic recording.", "x-presence": "implicit" } }, "x-reference-model": { "title": "DailyMeetingTokenProperties", "url": "/api/models/daily-meeting-token-properties#response" } }, "MintSttTokenRequest": { "type": "object", "description": "Mint a short-lived Cartesia STT access token for the calling user.", "properties": {} }, "MintSttTokenResponse": { "type": "object", "description": "Result of issuing a short-lived Cartesia speech-to-text access token.", "properties": { "token": { "type": "string", "description": "Short-lived Cartesia speech-to-text access token.", "x-presence": "implicit" }, "expiresInSeconds": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Lifetime of the issued access token, in seconds.", "x-presence": "implicit" } } }, "ListPendingApprovalsRequest": { "type": "object", "description": "Input for reading tool calls awaiting approval.", "properties": { "conversationKey": { "type": "string", "minLength": 1, "description": "Identifier of the conversation thread.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "conversationKey" ], "required": [ "conversationKey" ] }, "ListPendingApprovalsResponse": { "type": "object", "description": "Result of reading tool calls awaiting approval.", "properties": { "toolCalls": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCall" }, "description": "Tool calls waiting for a caller approval decision.", "x-presence": "collection" } } }, "SubmitToolApprovalsRequest": { "type": "object", "description": "Input for submitting decisions for tool calls awaiting approval.", "properties": { "conversationKey": { "type": "string", "minLength": 1, "description": "Identifier of the conversation thread.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "approvals": { "type": "array", "items": { "$ref": "#/components/schemas/ToolApproval" }, "description": "Approval decisions for the identified pending tool calls.", "x-presence": "collection" } }, "x-request-required": [ "conversationKey" ], "required": [ "conversationKey" ] }, "ToolApproval": { "type": "object", "description": "Approval decision for a specific tool call", "properties": { "toolCallId": { "type": "string", "description": "Identifier of the tool call being approved, executed, or retrieved.", "x-presence": "implicit" }, "toolName": { "type": "string", "description": "Name of the tool associated with the call or result.", "x-presence": "implicit" }, "approved": { "type": "boolean", "description": "Whether the caller approves execution of the identified tool call.", "x-presence": "implicit" }, "reason": { "type": "string", "description": "Optional rejection reason.", "x-presence": "implicit" } }, "x-reference-model": { "title": "ToolApproval", "url": "/api/models/tool-approval#request" } }, "SubmitToolApprovalsResponse": { "type": "object", "description": "Result of submitting decisions for tool calls awaiting approval. This message declares no response fields.", "properties": {} }, "SubmitClientToolResultsRequest": { "type": "object", "description": "Input for returning client-side tool execution results to the conversation.", "properties": { "conversationKey": { "type": "string", "minLength": 1, "description": "Identifier of the conversation thread.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ClientToolResult" }, "description": "Execution results for tools that ran on the client.", "x-presence": "collection" } }, "x-request-required": [ "conversationKey" ], "required": [ "conversationKey" ] }, "ClientToolResult": { "type": "object", "description": "Result submitted by the caller for a client-side tool call. Both tool_call_id and tool_name\nmust identify the same pending call. When submission reaches workflow validation, either missing\nvalue causes a 400 response. Copy the call's id and name into these result fields, rather than\nsubmitting the pending ToolCall unchanged.", "properties": { "toolCallId": { "type": "string", "description": "Required call identifier, copied from the pending ToolCall.id.", "x-presence": "implicit" }, "toolName": { "type": "string", "description": "Required tool name, copied from the pending ToolCall.name.", "x-presence": "implicit" }, "resultJson": { "type": "object", "additionalProperties": true, "description": "Structured output for a matched pending call. A nonempty object records COMPLETED; an empty\nor omitted object records FAILED, including when the client could not complete the action.", "x-presence": "message" }, "error": { "description": "Supplied error detail. The current result handler does not consume this field; the presence\nof a nonempty result_json alone determines whether the tool is recorded as completed.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/RpcErrorInput" } ] } }, "x-reference-model": { "title": "ClientToolResult", "url": "/api/models/client-tool-result#request" } }, "RpcErrorInput": { "type": "object", "description": "Standardized error payload following google.rpc.Status (AIP-193).\nUsed across all response messages and event payloads.", "properties": { "code": { "oneOf": [ { "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" ], "x-enumDescriptions": { "ERROR_CODE_CANCELLED": "The caller cancelled the operation before it completed.", "ERROR_CODE_UNKNOWN": "The operation failed without a more specific error classification.", "ERROR_CODE_INVALID_ARGUMENT": "The request contains an invalid argument or field value.", "ERROR_CODE_DEADLINE_EXCEEDED": "The operation did not complete before its deadline.", "ERROR_CODE_NOT_FOUND": "The requested resource does not exist or could not be found.", "ERROR_CODE_ALREADY_EXISTS": "The requested creation conflicts with a resource that already exists.", "ERROR_CODE_PERMISSION_DENIED": "The authenticated caller is not permitted to perform the operation.", "ERROR_CODE_RESOURCE_EXHAUSTED": "A quota, rate limit or other capacity limit prevented the operation.", "ERROR_CODE_FAILED_PRECONDITION": "The operation requires a system or resource state that is not currently satisfied.", "ERROR_CODE_ABORTED": "The operation was aborted, for example by a concurrent modification conflict.", "ERROR_CODE_OUT_OF_RANGE": "An argument is outside the range supported by this operation.", "ERROR_CODE_UNIMPLEMENTED": "The requested operation is not implemented.", "ERROR_CODE_INTERNAL": "An internal failure prevented the operation from completing.", "ERROR_CODE_UNAVAILABLE": "The service or a required dependency is temporarily unavailable.", "ERROR_CODE_DATA_LOSS": "The operation encountered unrecoverable loss or corruption of data.", "ERROR_CODE_UNAUTHENTICATED": "Authentication credentials are missing or invalid.", "ERROR_CODE_MODEL_INVALID": "The requested model identifier is absent from the model catalog.", "ERROR_CODE_MODEL_UNAVAILABLE": "The model exists, but no provider is currently available to serve it.", "ERROR_CODE_MODERATION_FLAGGED": "Content moderation flagged the submitted content.", "ERROR_CODE_GENERATION_FAILED": "Model generation failed after its configured attempts.", "ERROR_CODE_TOOL_EXECUTION_FAILED": "Execution of a requested tool failed.", "ERROR_CODE_UPSTREAM_PROVIDER": "An upstream model provider returned an error.", "ERROR_CODE_VALIDATION_EXHAUSTED": "Structured-output validation still failed after the configured attempts.", "ERROR_CODE_PAYMENT_REQUIRED": "The account lacks the credits required for the operation." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "ERROR_CODE_CANCELLED", "number": 1, "canonical": true, "description": "The caller cancelled the operation before it completed." }, { "name": "ERROR_CODE_UNKNOWN", "number": 2, "canonical": true, "description": "The operation failed without a more specific error classification." }, { "name": "ERROR_CODE_INVALID_ARGUMENT", "number": 3, "canonical": true, "description": "The request contains an invalid argument or field value." }, { "name": "ERROR_CODE_DEADLINE_EXCEEDED", "number": 4, "canonical": true, "description": "The operation did not complete before its deadline." }, { "name": "ERROR_CODE_NOT_FOUND", "number": 5, "canonical": true, "description": "The requested resource does not exist or could not be found." }, { "name": "ERROR_CODE_ALREADY_EXISTS", "number": 6, "canonical": true, "description": "The requested creation conflicts with a resource that already exists." }, { "name": "ERROR_CODE_PERMISSION_DENIED", "number": 7, "canonical": true, "description": "The authenticated caller is not permitted to perform the operation." }, { "name": "ERROR_CODE_RESOURCE_EXHAUSTED", "number": 8, "canonical": true, "description": "A quota, rate limit or other capacity limit prevented the operation." }, { "name": "ERROR_CODE_FAILED_PRECONDITION", "number": 9, "canonical": true, "description": "The operation requires a system or resource state that is not currently satisfied." }, { "name": "ERROR_CODE_ABORTED", "number": 10, "canonical": true, "description": "The operation was aborted, for example by a concurrent modification conflict." }, { "name": "ERROR_CODE_OUT_OF_RANGE", "number": 11, "canonical": true, "description": "An argument is outside the range supported by this operation." }, { "name": "ERROR_CODE_UNIMPLEMENTED", "number": 12, "canonical": true, "description": "The requested operation is not implemented." }, { "name": "ERROR_CODE_INTERNAL", "number": 13, "canonical": true, "description": "An internal failure prevented the operation from completing." }, { "name": "ERROR_CODE_UNAVAILABLE", "number": 14, "canonical": true, "description": "The service or a required dependency is temporarily unavailable." }, { "name": "ERROR_CODE_DATA_LOSS", "number": 15, "canonical": true, "description": "The operation encountered unrecoverable loss or corruption of data." }, { "name": "ERROR_CODE_UNAUTHENTICATED", "number": 16, "canonical": true, "description": "Authentication credentials are missing or invalid." }, { "name": "ERROR_CODE_MODEL_INVALID", "number": 600, "canonical": true, "description": "The requested model identifier is absent from the model catalog." }, { "name": "ERROR_CODE_MODEL_UNAVAILABLE", "number": 601, "canonical": true, "description": "The model exists, but no provider is currently available to serve it." }, { "name": "ERROR_CODE_MODERATION_FLAGGED", "number": 602, "canonical": true, "description": "Content moderation flagged the submitted content." }, { "name": "ERROR_CODE_GENERATION_FAILED", "number": 603, "canonical": true, "description": "Model generation failed after its configured attempts." }, { "name": "ERROR_CODE_TOOL_EXECUTION_FAILED", "number": 604, "canonical": true, "description": "Execution of a requested tool failed." }, { "name": "ERROR_CODE_UPSTREAM_PROVIDER", "number": 605, "canonical": true, "description": "An upstream model provider returned an error." }, { "name": "ERROR_CODE_VALIDATION_EXHAUSTED", "number": 606, "canonical": true, "description": "Structured-output validation still failed after the configured attempts." }, { "name": "ERROR_CODE_PAYMENT_REQUIRED", "number": 607, "canonical": true, "description": "The account lacks the credits required for the operation." } ], "x-enum-description": "Machine-readable reason that a request or operation failed; inspect the accompanying error\ndetails for context.", "description": "Machine-readable error code. Clients switch on this field.", "x-presence": "implicit" }, "message": { "type": "string", "description": "Human-readable error description. Intended for developers, not end users.\nMust not be parsed programmatically — use code and details instead.", "x-presence": "implicit" }, "isTerminal": { "type": "boolean", "description": "Whether this error is terminal (non-retryable). When true, repeating the\nsame request will produce the same error. When false, transient condition\nmay resolve on retry.", "x-presence": "implicit" }, "details": { "description": "Structured error details. At most one of each detail type.\nFollows google.rpc.Status details pattern but uses concrete types\ninstead of google.protobuf.Any for type safety and codegen.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ErrorDetailsInput" } ] } }, "x-reference-model": { "title": "RpcError", "url": "/api/models/rpc-error#request" } }, "ErrorDetailsInput": { "type": "object", "description": "Typed error details container. Concrete fields instead of Any for\ntype safety across languages. At most one of each detail type.", "properties": { "errorInfo": { "description": "Identifies the error for machine consumption.\nREQUIRED on all errors per AIP-193 (enforced at Go helper level).", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ErrorInfoInput" } ] }, "retryInfo": { "description": "Retry guidance for transient errors.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/RetryInfoInput" } ] }, "fieldViolations": { "type": "array", "items": { "$ref": "#/components/schemas/FieldViolationInput" }, "description": "Field-level validation failures.", "x-presence": "collection" }, "upstreamError": { "description": "Upstream provider error context.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/UpstreamErrorInput" } ] }, "modelError": { "description": "Model-specific error context.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ModelErrorInput" } ] }, "helpLinks": { "type": "array", "items": { "$ref": "#/components/schemas/HelpLinkInput" }, "description": "Help links for error resolution.", "x-presence": "collection" } }, "x-reference-model": { "title": "ErrorDetails", "url": "/api/models/error-details#request" } }, "ErrorInfoInput": { "type": "object", "description": "Machine-readable error identification (per AIP-193, every error must include this).", "properties": { "reason": { "type": "string", "description": "Stable machine-readable reason string (e.g., \"MODEL_NOT_FOUND\",\n\"RATE_LIMITED\", \"MODERATION_FLAGGED\").\nUnique within the domain. Clients may switch on this field.", "x-presence": "implicit" }, "domain": { "type": "string", "description": "Machine-readable namespace identifying the origin of the error.", "x-presence": "implicit" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Arbitrary key-value metadata. If the message field mentions a specific\nvalue (model name, field path, etc.), it MUST also appear here.", "x-presence": "collection" } }, "x-reference-model": { "title": "ErrorInfo", "url": "/api/models/error-info#request" } }, "RetryInfoInput": { "type": "object", "description": "Retry guidance for transient errors.", "properties": { "retryDelayMs": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Suggested minimum delay before retrying, in milliseconds.", "x-presence": "implicit" } }, "x-reference-model": { "title": "RetryInfo", "url": "/api/models/retry-info#request" } }, "FieldViolationInput": { "type": "object", "description": "A single field-level validation violation.", "properties": { "field": { "type": "string", "description": "Dot-separated path to the field (e.g., \"generation_config.model\").", "x-presence": "implicit" }, "description": { "type": "string", "description": "Human-readable description of the violation.", "x-presence": "implicit" } }, "x-reference-model": { "title": "FieldViolation", "url": "/api/models/field-violation#request" } }, "UpstreamErrorInput": { "type": "object", "description": "Context from an upstream provider error.", "properties": { "provider": { "type": "string", "description": "Name of the upstream provider that reported the error.", "x-presence": "implicit" }, "statusCode": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "HTTP status code returned by the provider.", "x-presence": "implicit" }, "rawBody": { "type": "string", "description": "Raw error body from the provider. Truncated to 512 bytes (enforced at Go level).", "x-presence": "implicit" } }, "x-reference-model": { "title": "UpstreamError", "url": "/api/models/upstream-error#request" } }, "ModelErrorInput": { "type": "object", "description": "Model-specific error context.", "properties": { "modelId": { "type": "string", "description": "The model ID that caused the error.", "x-presence": "implicit" }, "reason": { "type": "string", "description": "Why the model failed (e.g., \"invalid\", \"unavailable\", \"moderation_flagged\").", "x-presence": "implicit" }, "alternativesTried": { "type": "array", "items": { "type": "string" }, "description": "Alternative models that were tried or could be tried.", "x-presence": "collection" } }, "x-reference-model": { "title": "ModelError", "url": "/api/models/model-error#request" } }, "HelpLinkInput": { "type": "object", "description": "A help link for error resolution.", "properties": { "url": { "type": "string", "description": "URL to documentation or resolution guide.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Description of what the link provides.", "x-presence": "implicit" } }, "x-reference-model": { "title": "HelpLink", "url": "/api/models/help-link#request" } }, "SubmitClientToolResultsResponse": { "type": "object", "description": "Result of returning client-side tool execution results to the conversation.", "properties": { "runId": { "type": "string", "description": "Identifier of the generation run, usable for retrieving its result or status after submitting\nclient-tool results.", "x-presence": "implicit" } } }, "SubmitClientToolResultsSyncRequest": { "type": "object", "description": "Input for returning client-side tool results and waiting for the next generation segment.", "properties": { "conversationKey": { "type": "string", "minLength": 1, "description": "Identifier of the conversation thread.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ClientToolResult" }, "description": "Execution results for tools that ran on the client.", "x-presence": "collection" }, "clientToolCursor": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "dispatch_seq this caller last observed — same semantics as\nAwaitGenerationRequest.client_tool_cursor. 0 on first call.", "x-presence": "implicit" } }, "x-request-required": [ "conversationKey" ], "required": [ "conversationKey" ] }, "SubmitClientToolResultsSyncResponse": { "type": "object", "description": "Result of returning client-side tool results and waiting for the next generation segment.", "properties": { "runId": { "type": "string", "description": "Identifier of the generation run associated with the operation.", "x-presence": "implicit" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "description": "Conversation messages returned by the generation segment.", "x-presence": "collection" }, "status": { "oneOf": [ { "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" ], "x-enumDescriptions": { "AGENT_STATUS_ACTIVE": "The run is active and has not yet reached a more specific execution phase or terminal outcome.", "AGENT_STATUS_GENERATING": "The run is generating a model response.", "AGENT_STATUS_EXECUTING_TOOLS": "The run is executing server-side tools.", "AGENT_STATUS_COMPLETED": "The run finished successfully.", "AGENT_STATUS_FAILED": "The run ended with a failure; inspect its error or end reason.", "AGENT_STATUS_QUEUED": "The incoming message is queued behind an ongoing run under the queue interruption policy.", "AGENT_STATUS_AWAITING_CLIENT_TOOLS": "The run is waiting for the caller to execute client-side tools and submit their results.", "AGENT_STATUS_CANCELLED": "The run ended because a client or its invocation cancelled it.", "AGENT_STATUS_TIMED_OUT": "The run ended because a run-level time limit elapsed." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "AGENT_STATUS_ACTIVE", "number": 1, "canonical": true, "description": "The run is active and has not yet reached a more specific execution phase or terminal outcome." }, { "name": "AGENT_STATUS_GENERATING", "number": 2, "canonical": true, "description": "The run is generating a model response." }, { "name": "AGENT_STATUS_EXECUTING_TOOLS", "number": 3, "canonical": true, "description": "The run is executing server-side tools." }, { "name": "AGENT_STATUS_COMPLETED", "number": 4, "canonical": true, "description": "The run finished successfully." }, { "name": "AGENT_STATUS_FAILED", "number": 5, "canonical": true, "description": "The run ended with a failure; inspect its error or end reason." }, { "name": "AGENT_STATUS_QUEUED", "number": 6, "canonical": true, "description": "The incoming message is queued behind an ongoing run under the queue interruption policy." }, { "name": "AGENT_STATUS_AWAITING_CLIENT_TOOLS", "number": 7, "canonical": true, "description": "The run is waiting for the caller to execute client-side tools and submit their results." }, { "name": "AGENT_STATUS_CANCELLED", "number": 8, "canonical": true, "description": "The run ended because a client or its invocation cancelled it." }, { "name": "AGENT_STATUS_TIMED_OUT", "number": 9, "canonical": true, "description": "The run ended because a run-level time limit elapsed." } ], "x-enum-description": "Execution state of an agent generation run, separate from the reason a terminal run ended.", "description": "Generation status reported for the next segment after tool results are submitted.", "x-presence": "implicit" }, "aggregateUsage": { "description": "Aggregated model usage reported for the generation run.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/Usage" } ] }, "pendingClientTools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCall" }, "description": "Tool calls dispatched for execution by the client.", "x-presence": "collection" }, "clientToolCursor": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Latest client-tool dispatch sequence represented by this response.", "x-presence": "implicit" }, "error": { "description": "Structured error for partial success scenarios. Full failures propagate\nas TerminalError → HTTP error status + RpcError JSON body.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/RpcError" } ] } } }, "ListPendingClientToolsRequest": { "type": "object", "description": "Input for reading client-side tool calls awaiting execution.", "properties": { "conversationKey": { "type": "string", "minLength": 1, "description": "Identifier of the conversation thread.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "namePrefixFilters": { "type": "array", "items": { "type": "string" }, "description": "When supplied, include only pending client tools whose names match one of these prefixes.", "x-presence": "collection" } }, "x-request-required": [ "conversationKey" ], "required": [ "conversationKey" ] }, "ListPendingClientToolsResponse": { "type": "object", "description": "Result of reading client-side tool calls awaiting execution.", "properties": { "messageSequences": { "type": "array", "items": { "type": "string", "format": "int64", "pattern": "^-?\\d+$" }, "description": "Inlined fields aligned by index across the three arrays.", "x-presence": "collection" }, "messageIds": { "type": "array", "items": { "type": "string" }, "description": "Message identifiers aligned with the returned tool calls.", "x-presence": "collection" }, "toolCalls": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCall" }, "description": "Client-side tool calls aligned with the returned message identifiers and sequences.", "x-presence": "collection" } } }, "GetToolCallRequest": { "type": "object", "description": "Input for locating a tool call within conversation history.", "properties": { "conversationKey": { "type": "string", "minLength": 1, "description": "Identifier of the conversation thread.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "toolCallId": { "type": "string", "description": "Identifier of the tool call to retrieve.", "x-presence": "implicit" } }, "x-request-required": [ "conversationKey" ], "required": [ "conversationKey" ] }, "GetToolCallResponse": { "type": "object", "description": "Result of locating a tool call within conversation history.", "properties": { "messageSequence": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Sequence number of the conversation message containing the tool call.", "x-presence": "implicit" }, "messageId": { "type": "string", "description": "Identifier of the conversation message containing the tool call.", "x-presence": "implicit" }, "toolCall": { "description": "Tool call retrieved from the identified conversation message.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ToolCall" } ] } } }, "MCPListAvailableServersRequest": { "type": "object", "description": "Server management", "properties": { "includeDisconnected": { "type": "boolean", "description": "Whether the server listing should include disconnected MCP servers.", "x-presence": "implicit" }, "kinds": { "type": "array", "items": { "oneOf": [ { "type": "string", "enum": [ "MCP_SERVER_KIND_INTERNAL", "MCP_SERVER_KIND_BUILT_IN", "MCP_SERVER_KIND_CUSTOM", "MCP_SERVER_KIND_EXTERNAL", "MCP_SERVER_KIND_INTEGRATION" ], "x-enumDescriptions": { "MCP_SERVER_KIND_INTERNAL": "A server compiled into the deployment and dispatched in-process.", "MCP_SERVER_KIND_BUILT_IN": "A platform-owned catalog server invoked with platform-held vendor credentials.", "MCP_SERVER_KIND_CUSTOM": "A tenant-registered server invoked with the tenant's credentials.", "MCP_SERVER_KIND_EXTERNAL": "A legacy externally configured server; this category does not designate a new tenant\nregistration.", "MCP_SERVER_KIND_INTEGRATION": "An account-connected integration reached through Pipedream Connect." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "MCP_SERVER_KIND_INTERNAL", "number": 1, "canonical": true, "description": "A server compiled into the deployment and dispatched in-process." }, { "name": "MCP_SERVER_KIND_BUILT_IN", "number": 2, "canonical": true, "description": "A platform-owned catalog server invoked with platform-held vendor credentials." }, { "name": "MCP_SERVER_KIND_CUSTOM", "number": 3, "canonical": true, "description": "A tenant-registered server invoked with the tenant's credentials." }, { "name": "MCP_SERVER_KIND_EXTERNAL", "number": 4, "canonical": true, "description": "A legacy externally configured server; this category does not designate a new tenant\nregistration." }, { "name": "MCP_SERVER_KIND_INTEGRATION", "number": 5, "canonical": true, "description": "An account-connected integration reached through Pipedream Connect." } ], "x-enum-description": "Ownership and connection category of an MCP server available to the platform.", "description": "Ownership and connection category of an MCP server available to the platform." }, "description": "Restrict the listing to these ownership classes. Empty = every kind, so an\nexisting caller that omits it sees no behavior change. Lets a console\nrequest a narrow view without standing up a new endpoint.", "x-presence": "collection" } } }, "MCPListAvailableServersResponse": { "type": "object", "description": "Result of listing the MCP servers available through the gateway.", "properties": { "servers": { "type": "array", "items": { "$ref": "#/components/schemas/MCPServerStatus" }, "description": "Connection status of each MCP server included in the listing.", "x-presence": "collection" } } }, "MCPServerStatus": { "type": "object", "description": "MCP Server Status\nStatus information about an MCP server (used in responses)", "properties": { "serverId": { "type": "string", "description": "Identifier of the MCP server associated with the operation or tool.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Display name of the MCP server.", "x-presence": "implicit" }, "status": { "oneOf": [ { "type": "string", "enum": [ "MCP_SERVER_CONNECTION_STATUS_CONNECTED", "MCP_SERVER_CONNECTION_STATUS_DISCONNECTED", "MCP_SERVER_CONNECTION_STATUS_ERROR", "MCP_SERVER_CONNECTION_STATUS_DISCOVERING" ], "x-enumDescriptions": { "MCP_SERVER_CONNECTION_STATUS_CONNECTED": "A connection to the MCP server is established.", "MCP_SERVER_CONNECTION_STATUS_DISCONNECTED": "There is no active connection to the MCP server.", "MCP_SERVER_CONNECTION_STATUS_ERROR": "A connection or discovery attempt encountered an error.", "MCP_SERVER_CONNECTION_STATUS_DISCOVERING": "The platform is discovering the server's available capabilities." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "MCP_SERVER_CONNECTION_STATUS_CONNECTED", "number": 1, "canonical": true, "description": "A connection to the MCP server is established." }, { "name": "MCP_SERVER_CONNECTION_STATUS_DISCONNECTED", "number": 2, "canonical": true, "description": "There is no active connection to the MCP server." }, { "name": "MCP_SERVER_CONNECTION_STATUS_ERROR", "number": 3, "canonical": true, "description": "A connection or discovery attempt encountered an error." }, { "name": "MCP_SERVER_CONNECTION_STATUS_DISCOVERING", "number": 4, "canonical": true, "description": "The platform is discovering the server's available capabilities." } ], "x-enum-description": "Current connection or discovery condition reported for an MCP server.", "description": "Current connection status reported for the MCP server.", "x-presence": "implicit" }, "toolsDiscovered": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of tool definitions found during the last discovery.", "x-presence": "implicit" }, "lastDiscoveryDuration": { "type": "string", "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]{1,9})?s$", "description": "Elapsed duration of the last MCP tool discovery.", "x-presence": "message" }, "lastError": { "type": "string", "description": "Most recent error reported while contacting the MCP server.", "x-presence": "implicit" }, "lastDiscoveryTime": { "type": "string", "format": "date-time", "description": "Time when MCP tool discovery last ran.", "x-presence": "message" }, "kind": { "oneOf": [ { "type": "string", "enum": [ "MCP_SERVER_KIND_INTERNAL", "MCP_SERVER_KIND_BUILT_IN", "MCP_SERVER_KIND_CUSTOM", "MCP_SERVER_KIND_EXTERNAL", "MCP_SERVER_KIND_INTEGRATION" ], "x-enumDescriptions": { "MCP_SERVER_KIND_INTERNAL": "A server compiled into the deployment and dispatched in-process.", "MCP_SERVER_KIND_BUILT_IN": "A platform-owned catalog server invoked with platform-held vendor credentials.", "MCP_SERVER_KIND_CUSTOM": "A tenant-registered server invoked with the tenant's credentials.", "MCP_SERVER_KIND_EXTERNAL": "A legacy externally configured server; this category does not designate a new tenant\nregistration.", "MCP_SERVER_KIND_INTEGRATION": "An account-connected integration reached through Pipedream Connect." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "MCP_SERVER_KIND_INTERNAL", "number": 1, "canonical": true, "description": "A server compiled into the deployment and dispatched in-process." }, { "name": "MCP_SERVER_KIND_BUILT_IN", "number": 2, "canonical": true, "description": "A platform-owned catalog server invoked with platform-held vendor credentials." }, { "name": "MCP_SERVER_KIND_CUSTOM", "number": 3, "canonical": true, "description": "A tenant-registered server invoked with the tenant's credentials." }, { "name": "MCP_SERVER_KIND_EXTERNAL", "number": 4, "canonical": true, "description": "A legacy externally configured server; this category does not designate a new tenant\nregistration." }, { "name": "MCP_SERVER_KIND_INTEGRATION", "number": 5, "canonical": true, "description": "An account-connected integration reached through Pipedream Connect." } ], "x-enum-description": "Ownership and connection category of an MCP server available to the platform.", "description": "Ownership of this server. Populated by ListAvailableServers for every\nsource it merges.", "x-presence": "implicit" }, "defaultEnabled": { "type": "boolean", "description": "Whether the built-in catalog recommends this server by default. This is a catalog\nrecommendation, not whether the server is enabled for a particular profile or conversation.", "x-presence": "implicit" } }, "x-reference-model": { "title": "MCPServerStatus", "url": "/api/models/mcp-server-status#response" } }, "MCPGetServerInfoRequest": { "type": "object", "description": "Input for reading connection and capability information for an MCP server.", "properties": { "serverId": { "type": "string", "description": "Identifier of the MCP server to query.", "x-presence": "implicit" } } }, "MCPGetServerInfoResponse": { "type": "object", "description": "Result of reading connection and capability information for an MCP server.", "properties": { "serverInfo": { "description": "Connection and capability information for the selected MCP server.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/MCPServerInfo" } ] } } }, "MCPServerInfo": { "type": "object", "description": "Detailed server information", "properties": { "serverId": { "type": "string", "description": "Identifier of the MCP server associated with the operation or tool.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Display name of the MCP server.", "x-presence": "implicit" }, "version": { "type": "string", "description": "Version of the resource represented by this message.", "x-presence": "implicit" }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Capabilities reported by the MCP server.", "x-presence": "collection" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional attributes associated with the resource.", "x-presence": "collection" }, "status": { "oneOf": [ { "type": "string", "enum": [ "MCP_SERVER_CONNECTION_STATUS_CONNECTED", "MCP_SERVER_CONNECTION_STATUS_DISCONNECTED", "MCP_SERVER_CONNECTION_STATUS_ERROR", "MCP_SERVER_CONNECTION_STATUS_DISCOVERING" ], "x-enumDescriptions": { "MCP_SERVER_CONNECTION_STATUS_CONNECTED": "A connection to the MCP server is established.", "MCP_SERVER_CONNECTION_STATUS_DISCONNECTED": "There is no active connection to the MCP server.", "MCP_SERVER_CONNECTION_STATUS_ERROR": "A connection or discovery attempt encountered an error.", "MCP_SERVER_CONNECTION_STATUS_DISCOVERING": "The platform is discovering the server's available capabilities." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "MCP_SERVER_CONNECTION_STATUS_CONNECTED", "number": 1, "canonical": true, "description": "A connection to the MCP server is established." }, { "name": "MCP_SERVER_CONNECTION_STATUS_DISCONNECTED", "number": 2, "canonical": true, "description": "There is no active connection to the MCP server." }, { "name": "MCP_SERVER_CONNECTION_STATUS_ERROR", "number": 3, "canonical": true, "description": "A connection or discovery attempt encountered an error." }, { "name": "MCP_SERVER_CONNECTION_STATUS_DISCOVERING", "number": 4, "canonical": true, "description": "The platform is discovering the server's available capabilities." } ], "x-enum-description": "Current connection or discovery condition reported for an MCP server.", "description": "Current connection status reported for the MCP server.", "x-presence": "implicit" }, "availableTools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinition" }, "description": "Tool definitions currently reported by the MCP server.", "x-presence": "collection" }, "kind": { "oneOf": [ { "type": "string", "enum": [ "MCP_SERVER_KIND_INTERNAL", "MCP_SERVER_KIND_BUILT_IN", "MCP_SERVER_KIND_CUSTOM", "MCP_SERVER_KIND_EXTERNAL", "MCP_SERVER_KIND_INTEGRATION" ], "x-enumDescriptions": { "MCP_SERVER_KIND_INTERNAL": "A server compiled into the deployment and dispatched in-process.", "MCP_SERVER_KIND_BUILT_IN": "A platform-owned catalog server invoked with platform-held vendor credentials.", "MCP_SERVER_KIND_CUSTOM": "A tenant-registered server invoked with the tenant's credentials.", "MCP_SERVER_KIND_EXTERNAL": "A legacy externally configured server; this category does not designate a new tenant\nregistration.", "MCP_SERVER_KIND_INTEGRATION": "An account-connected integration reached through Pipedream Connect." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "MCP_SERVER_KIND_INTERNAL", "number": 1, "canonical": true, "description": "A server compiled into the deployment and dispatched in-process." }, { "name": "MCP_SERVER_KIND_BUILT_IN", "number": 2, "canonical": true, "description": "A platform-owned catalog server invoked with platform-held vendor credentials." }, { "name": "MCP_SERVER_KIND_CUSTOM", "number": 3, "canonical": true, "description": "A tenant-registered server invoked with the tenant's credentials." }, { "name": "MCP_SERVER_KIND_EXTERNAL", "number": 4, "canonical": true, "description": "A legacy externally configured server; this category does not designate a new tenant\nregistration." }, { "name": "MCP_SERVER_KIND_INTEGRATION", "number": 5, "canonical": true, "description": "An account-connected integration reached through Pipedream Connect." } ], "x-enum-description": "Ownership and connection category of an MCP server available to the platform.", "description": "Ownership category of the MCP server definition.", "x-presence": "implicit" } }, "x-reference-model": { "title": "MCPServerInfo", "url": "/api/models/mcp-server-info#response" } }, "MCPListToolsRequest": { "type": "object", "description": "Tool operations", "properties": { "servers": { "type": "array", "items": { "$ref": "#/components/schemas/MCPServerReferenceInput" }, "description": "MCP servers to inspect; an empty list requests tools from all available servers.", "x-presence": "collection" }, "sessionId": { "type": "string", "description": "Session routing hint for the MCP operation.", "x-presence": "implicit" } } }, "MCPListToolsResponse": { "type": "object", "description": "Result of discovering tools exposed by MCP servers.", "properties": { "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinition" }, "description": "Tool definitions returned by MCP discovery.", "x-presence": "collection" }, "totalCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of entries reported by the MCP operation.", "x-presence": "implicit" } } }, "MCPCallToolRequest": { "type": "object", "description": "Input for executing a tool through an MCP server.", "properties": { "toolCall": { "description": "Prefer ToolCall with server_id/name and arguments_json (object)", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ToolCallInput" } ] }, "requestId": { "type": "string", "description": "Correlation identifier for the MCP tool execution request.", "x-presence": "implicit" }, "sessionId": { "type": "string", "description": "Session routing hint for the MCP operation.", "x-presence": "implicit" } } }, "MCPCallToolResponse": { "type": "object", "description": "Result of executing a tool through an MCP server.", "properties": { "requestId": { "type": "string", "description": "Correlation identifier for the MCP tool execution request.", "x-presence": "implicit" }, "toolCall": { "description": "Tool call with its arguments, execution state, and available result.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ToolCall" } ] }, "executionTimeMs": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Reported duration of MCP tool execution, in milliseconds.", "x-presence": "implicit" } } }, "MCPListResourcesRequest": { "type": "object", "description": "Resources", "properties": { "serverId": { "type": "string", "description": "Identifier of the MCP server to query.", "x-presence": "implicit" }, "uriFilter": { "type": "string", "description": "Filter applied to the URIs of discovered MCP resources.", "x-presence": "implicit" }, "sessionId": { "type": "string", "description": "Session routing hint for the MCP operation.", "x-presence": "implicit" } } }, "MCPListResourcesResponse": { "type": "object", "description": "Result of discovering resources exposed by an MCP server.", "properties": { "resources": { "type": "array", "items": { "$ref": "#/components/schemas/Resource" }, "description": "Resource descriptions returned by MCP discovery.", "x-presence": "collection" }, "totalCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of entries reported by the MCP operation.", "x-presence": "implicit" } } }, "Resource": { "type": "object", "description": "A resource exposed by an MCP server", "properties": { "uri": { "type": "string", "description": "Canonical URI for the resource.", "x-presence": "implicit" }, "title": { "type": "string", "description": "Display title of the MCP resource.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Description of the content available from the MCP resource.", "x-presence": "implicit" }, "mimeType": { "type": "string", "description": "Media type of the content exposed by the MCP resource.", "x-presence": "implicit" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/ContentPart" }, "description": "Optional embedded content.", "x-presence": "collection" }, "annotations": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional annotations/metadata.", "x-presence": "collection" }, "lastModified": { "type": "string", "format": "date-time", "description": "Time when this resource was last modified.", "x-presence": "message" } }, "x-reference-model": { "title": "Resource", "url": "/api/models/resource#response" } }, "MCPReadResourceRequest": { "type": "object", "description": "Input for reading an MCP resource by URI.", "properties": { "serverId": { "type": "string", "description": "Identifier of the MCP server to query.", "x-presence": "implicit" }, "uri": { "type": "string", "description": "URI identifying the MCP resource to read.", "x-presence": "implicit" }, "sessionId": { "type": "string", "description": "Session routing hint for the MCP operation.", "x-presence": "implicit" } } }, "MCPReadResourceResponse": { "type": "object", "description": "Result of reading an MCP resource by URI.", "properties": { "resource": { "description": "MCP resource with content when provided by the server.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/Resource" } ] } } }, "MCPListPromptsRequest": { "type": "object", "description": "Prompts", "properties": { "serverId": { "type": "string", "description": "Identifier of the MCP server to query.", "x-presence": "implicit" }, "nameFilter": { "type": "string", "description": "Filter applied to the names of discovered MCP prompts.", "x-presence": "implicit" }, "sessionId": { "type": "string", "description": "Session routing hint for the MCP operation.", "x-presence": "implicit" } } }, "MCPListPromptsResponse": { "type": "object", "description": "Result of discovering prompt templates exposed by an MCP server.", "properties": { "prompts": { "type": "array", "items": { "$ref": "#/components/schemas/PromptDefinition" }, "description": "Prompt templates returned by MCP discovery.", "x-presence": "collection" }, "totalCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of entries reported by the MCP operation.", "x-presence": "implicit" } } }, "PromptDefinition": { "type": "object", "description": "A prompt definition exposed by an MCP server", "properties": { "name": { "type": "string", "description": "Name identifying the prompt template on the MCP server.", "x-presence": "implicit" }, "title": { "type": "string", "description": "Display title of the MCP prompt template.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Description of the MCP prompt template’s purpose.", "x-presence": "implicit" }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/PromptParameter" }, "description": "Parameter definitions accepted by the prompt template.", "x-presence": "collection" }, "template": { "type": "string", "description": "Template string; clients may render with parameters.", "x-presence": "implicit" } }, "x-reference-model": { "title": "PromptDefinition", "url": "/api/models/prompt-definition#response" } }, "PromptParameter": { "type": "object", "description": "A parameter used by a prompt template", "properties": { "name": { "type": "string", "description": "Name used to bind a value to this prompt-template parameter.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Explanation of the value expected for this prompt parameter.", "x-presence": "implicit" }, "type": { "type": "string", "description": "Free-form type hint, e.g. \"string\", \"number\"", "x-presence": "implicit" }, "required": { "type": "boolean", "description": "Whether the prompt parameter must be supplied by the caller.", "x-presence": "implicit" } }, "x-reference-model": { "title": "PromptParameter", "url": "/api/models/prompt-parameter#response" } }, "MCPGetPromptRequest": { "type": "object", "description": "Input for retrieving an MCP prompt template by name.", "properties": { "serverId": { "type": "string", "description": "Identifier of the MCP server to query.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Name of the MCP prompt template to retrieve.", "x-presence": "implicit" }, "sessionId": { "type": "string", "description": "Session routing hint for the MCP operation.", "x-presence": "implicit" } } }, "MCPGetPromptResponse": { "type": "object", "description": "Result of retrieving an MCP prompt template by name.", "properties": { "prompt": { "description": "Prompt template returned by the MCP server.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PromptDefinition" } ] } } }, "SearchMemoriesRequest": { "type": "object", "description": "Input for a semantic search of memories in the authenticated user’s tenant scope.", "properties": { "query": { "type": "string", "minLength": 1, "description": "Non-empty natural-language search query.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "topK": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 100, "description": "Maximum results requested. Supply explicitly; omission is rejected before search.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 100, "gte": 1 } }, "x-validation-scope": "request" }, "threshold": { "type": "number", "format": "float", "minimum": 0, "maximum": 1, "description": "Minimum provider relevance score. Omission and zero do not request a positive cutoff.\nScores are provider-specific, not probabilities that the memory is true.", "x-presence": "implicit", "x-protovalidate": { "float": { "lte": 1, "gte": 0 } }, "x-validation-scope": "request" }, "rerank": { "type": "boolean", "description": "Requests reranking when supported. Absence leaves the provider behavior unchanged; explicit\nfalse is forwarded as false. It does not guarantee relevance or correctness.", "x-presence": "explicit" } }, "x-request-required": [ "query", "topK" ], "required": [ "query", "topK" ] }, "SearchMemoriesResponse": { "type": "object", "description": "Relevant memory records and any graph relationships returned by the search provider.", "properties": { "memories": { "type": "array", "items": { "$ref": "#/components/schemas/Memory" }, "description": "Matched memories ordered by relevance. An empty result does not prove that no memories\nexist.", "x-presence": "collection" }, "relations": { "type": "array", "items": { "$ref": "#/components/schemas/Relation" }, "description": "Returned graph relationships; this list may be absent when there are no relationships.", "x-presence": "collection" } } }, "Memory": { "type": "object", "description": "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.\n\n`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.\n\nMemory 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.", "properties": { "id": { "type": "string", "description": "Unique memory identifier.", "x-presence": "implicit" }, "memory": { "type": "string", "description": "Stored fact text. It may be incomplete, stale or incorrect.", "x-presence": "implicit" }, "userId": { "type": "string", "description": "User associated with the memory.", "x-presence": "implicit" }, "agentId": { "type": "string", "description": "Agent or conversation associated with the memory.", "x-presence": "implicit" }, "appId": { "type": "string", "description": "Tenant identifier associated with the memory.", "x-presence": "implicit" }, "runId": { "type": "string", "description": "Associated run or session identifier.", "x-presence": "implicit" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional string-valued metadata attached to the memory.", "x-presence": "collection" }, "score": { "oneOf": [ { "type": "number", "format": "float" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Relevance score returned by search. Its scale is provider-specific and is not a probability\nthat the fact is correct.", "x-presence": "implicit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation time as an RFC 3339 timestamp; absent when unavailable.", "x-presence": "message" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update time as an RFC 3339 timestamp; absent when unavailable.", "x-presence": "message" } }, "x-reference-model": { "title": "Memory", "url": "/api/memory/models/memory#response" } }, "Relation": { "type": "object", "description": "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.\n\nRelationships may be absent even when memory records are returned. They describe extracted associations, not verified facts, ownership permissions or lifecycle transitions.", "properties": { "source": { "type": "string", "description": "Source entity name.", "x-presence": "implicit" }, "relationship": { "type": "string", "description": "Open string describing the relationship. Example labels do not restrict the allowed values.", "x-presence": "implicit" }, "destination": { "type": "string", "description": "Destination entity name.", "x-presence": "implicit" } }, "x-reference-model": { "title": "Memory relation", "url": "/api/memory/models/relation#response" } }, "ListMemoriesRequest": { "type": "object", "description": "Input for listing memory records in the caller’s scope.", "properties": { "agentId": { "type": "string", "description": "Filter by agent/conversation ID (optional)", "x-presence": "implicit" }, "limit": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 100, "description": "Maximum number of memories to return. Supply explicitly; omission is rejected.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 100, "gte": 1 } }, "x-validation-scope": "request" } }, "x-request-required": [ "limit" ], "required": [ "limit" ] }, "ListMemoriesResponse": { "type": "object", "description": "Result of listing memory records in the caller’s scope.", "properties": { "memories": { "type": "array", "items": { "$ref": "#/components/schemas/Memory" }, "description": "List of user's memories", "x-presence": "collection" } } }, "GetMemoryRequest": { "type": "object", "description": "Input for retrieving a memory record by its identifier.", "properties": { "memoryId": { "type": "string", "minLength": 1, "description": "Memory ID to retrieve", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "memoryId" ], "required": [ "memoryId" ] }, "GetMemoryResponse": { "type": "object", "description": "Result of retrieving a memory record by its identifier.", "properties": { "memory": { "description": "The requested memory", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/Memory" } ] } } }, "UpdateMemoryRequest": { "type": "object", "description": "Input for replacing the text of a memory record.", "properties": { "memoryId": { "type": "string", "minLength": 1, "description": "Memory ID to update", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "text": { "type": "string", "minLength": 1, "description": "New memory text content", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "memoryId", "text" ], "required": [ "memoryId", "text" ] }, "UpdateMemoryResponse": { "type": "object", "description": "Result of replacing the text of a memory record. This message declares no response fields.", "properties": {} }, "DeleteMemoryRequest": { "type": "object", "description": "Input for deleting a memory record by its identifier.", "properties": { "memoryId": { "type": "string", "minLength": 1, "description": "Memory ID to delete", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "memoryId" ], "required": [ "memoryId" ] }, "DeleteMemoryResponse": { "type": "object", "description": "Result of deleting a memory record by its identifier.", "properties": { "success": { "type": "boolean", "description": "Whether deletion was successful", "x-presence": "implicit" } } }, "GetEndUserRequest": { "type": "object", "description": "Inputs for retrieving an end-user identity and profile record. This schema declares no request\nfields.", "properties": {} }, "GetEndUserResponse": { "type": "object", "description": "Result of retrieving an end-user identity and profile record.", "properties": { "endUser": { "description": "End-user identity and profile returned by the lookup. An empty message is returned when no\nmatching end user exists.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/EndUserState" } ] } } }, "EndUserState": { "type": "object", "description": "Captured identity claims and editable profile values for a tenant's end user.\nIdentity claims are copied from the verified token and are read-only through the\nprofile update operations. Location, locale overrides, generation preferences and\napplication metadata are set through their corresponding profile update operations.", "properties": { "subject": { "type": "string", "description": "Subject claim identifying the end user within the identity provider.", "x-presence": "implicit" }, "tenantId": { "type": "string", "description": "Identifier of the tenant that owns or scopes this record.", "x-presence": "implicit" }, "issuer": { "type": "string", "description": "OIDC issuer identifying the identity provider.", "x-presence": "implicit" }, "projectId": { "type": "string", "description": "Identifier of the project within the tenant that scopes this record.", "x-presence": "implicit" }, "email": { "type": "string", "description": "Email address received from the identity provider.", "x-presence": "implicit" }, "emailVerified": { "type": "boolean", "description": "Whether the identity provider marked the email address as verified.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Full name received from the identity provider.", "x-presence": "implicit" }, "givenName": { "type": "string", "description": "Given-name claim received from the identity provider.", "x-presence": "implicit" }, "familyName": { "type": "string", "description": "Family-name claim received from the identity provider.", "x-presence": "implicit" }, "preferredUsername": { "type": "string", "description": "Preferred username claim received from the identity provider.", "x-presence": "implicit" }, "picture": { "type": "string", "description": "Profile picture URL received from the identity provider.", "x-presence": "implicit" }, "phoneNumber": { "type": "string", "description": "Telephone number received from the identity provider.", "x-presence": "implicit" }, "phoneNumberVerified": { "type": "boolean", "description": "Whether the identity provider marked the telephone number as verified.", "x-presence": "implicit" }, "signInProvider": { "type": "string", "description": "Sign-in provider recorded with the captured identity.", "x-presence": "implicit" }, "authMethod": { "type": "string", "description": "Authentication method recorded with the captured identity.", "x-presence": "implicit" }, "locale": { "type": "string", "description": "Locale preference associated with the user or subscriber. IdP-sourced default (not the\noverride).", "x-presence": "implicit" }, "zoneinfo": { "type": "string", "description": "Time zone claim received from the identity provider. IdP-sourced default.", "x-presence": "implicit" }, "customClaims": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional identity claims stored as string key-value pairs.", "x-presence": "collection" }, "location": { "description": "Coordinates and derived location metadata selected by the end user.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/Location" } ] }, "localeOverride": { "type": "string", "description": "Locale explicitly selected by the end user. When set, takes precedence over the\nidentity provider's locale; when empty, the identity-provider locale is used.", "x-presence": "implicit" }, "defaultGenerationConfig": { "description": "Default model generation settings associated with the end-user profile.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GenerationConfig" } ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Application-defined key-value metadata associated with the end user.", "x-presence": "collection" }, "firstSeenAt": { "type": "string", "format": "date-time", "description": "Time the end-user identity was first captured.", "x-presence": "message" }, "lastSeenAt": { "type": "string", "format": "date-time", "description": "Time the end user's identity was most recently observed.", "x-presence": "message" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time this record was most recently updated.", "x-presence": "message" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time this record was created.", "x-presence": "message" } }, "x-reference-model": { "title": "EndUserState", "url": "/api/models/end-user-state#response" } }, "Location": { "type": "object", "description": "End-user coordinates and associated location metadata.", "properties": { "latitude": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Latitude of the location in decimal degrees.", "x-presence": "implicit" }, "longitude": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Longitude of the location in decimal degrees.", "x-presence": "implicit" }, "city": { "type": "string", "description": "City associated with the location; currently left empty because reverse geocoding is not\nimplemented.", "x-presence": "implicit" }, "timezone": { "type": "string", "description": "IANA time zone associated with the record or schedule. IANA, derived from coordinates\nserver-side.", "x-presence": "implicit" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time this record was most recently updated.", "x-presence": "message" } }, "x-reference-model": { "title": "Location", "url": "/api/models/location#response" } }, "UpdateLocationRequest": { "type": "object", "description": "Inputs for updating the end user's geographic coordinates.", "properties": { "latitude": { "type": "number", "format": "double", "minimum": -90, "maximum": 90, "description": "Latitude of the location in decimal degrees.", "x-presence": "implicit", "x-protovalidate": { "double": { "lte": 90, "gte": -90 } }, "x-validation-scope": "request" }, "longitude": { "type": "number", "format": "double", "minimum": -180, "maximum": 180, "description": "Longitude of the location in decimal degrees.", "x-presence": "implicit", "x-protovalidate": { "double": { "lte": 180, "gte": -180 } }, "x-validation-scope": "request" } } }, "UpdateLocationResponse": { "type": "object", "description": "Result of updating the end user's geographic coordinates.", "properties": { "location": { "description": "Coordinates and derived location metadata stored for the end user. Includes derived IANA\ntimezone.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/Location" } ] } } }, "UpdateLocaleRequest": { "type": "object", "description": "Inputs for updating the end user's locale preference.", "properties": { "locale": { "type": "string", "pattern": "^$|^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$", "description": "BCP-47 locale override, such as \"es-MX\". Empty string clears the override.", "x-presence": "implicit", "x-protovalidate": { "string": { "pattern": "^$|^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$" } }, "x-validation-scope": "request" } } }, "UpdateLocaleResponse": { "type": "object", "description": "Result of updating the end user's locale preference. This schema declares no result fields.", "properties": {} }, "EndUserUpdateDefaultGenerationConfigRequest": { "type": "object", "description": "Inputs for updating default model generation settings.", "properties": { "config": { "description": "Default generation settings restricted to these user-settable fields: model, models,\ntemperature, top_p, max_output_tokens, frequency_penalty, presence_penalty,\nstop_sequences, seed and language_preference. Recognized fields outside this list,\nincluding operational settings for prompts, tools, MCP and timeouts, reject the whole\nrequest. New GenerationConfig fields are rejected unless added to this allowlist.\nEach model must also be permitted by the platform model allowlist. Unknown JSON names\nmay be discarded before these checks; they are not supported configuration settings.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GenerationConfigInput" } ], "x-protovalidate": { "required": true }, "x-validation-scope": "request" } }, "x-request-required": [ "config" ], "required": [ "config" ] }, "EndUserUpdateDefaultGenerationConfigResponse": { "type": "object", "description": "Result of updating default model generation settings. This schema declares no result fields.", "properties": {} }, "UpdateMetadataRequest": { "type": "object", "description": "Inputs for updating the end user's profile metadata.", "properties": { "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Application-defined key-value metadata associated with the end user.", "x-presence": "collection" } } }, "UpdateMetadataResponse": { "type": "object", "description": "Result of updating the end user's profile metadata. This schema declares no result fields.", "properties": {} }, "AddDatasetItemRequest": { "type": "object", "description": "Inputs for adding an input and expected-output pair in an evaluation dataset.", "properties": { "datasetId": { "type": "string", "minLength": 1, "description": "Identifier of the evaluation dataset.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "inputJson": { "type": "string", "description": "Dataset item input serialized as JSON text.", "x-presence": "implicit" }, "expectedOutputJson": { "type": "string", "description": "Expected dataset item output serialized as JSON text.", "x-presence": "implicit" }, "sourceTraceId": { "type": "string", "description": "Identifier of the trace used as the source for the dataset item.", "x-presence": "implicit" }, "metadataJson": { "type": "string", "description": "Additional evaluation metadata serialized as JSON text.", "x-presence": "implicit" }, "conversationId": { "type": "string", "maxLength": 256, "description": "Identifier of the conversation associated with the evaluation record.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" }, "sourceUserMessageId": { "type": "string", "maxLength": 256, "description": "Identifier of the user message that originated the evaluated generation.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" } }, "x-protovalidate": { "cel": [ { "id": "exactly_one_source_ref", "message": "exactly one of source_trace_id or (conversation_id + source_user_message_id) must be set", "expression": "(this.source_trace_id != '') != (this.conversation_id != '' && this.source_user_message_id != '')" } ] }, "x-validation-scope": "request", "x-request-required": [ "datasetId" ], "required": [ "datasetId" ] }, "AddDatasetItemResponse": { "type": "object", "description": "Result of adding an input and expected-output pair in an evaluation dataset.", "properties": { "itemId": { "type": "string", "description": "Identifier of the dataset item or annotation queue item being addressed.", "x-presence": "implicit" } } }, "CompleteAnnotationQueueItemRequest": { "type": "object", "description": "Inputs for completing an evaluation object in an annotation queue.", "properties": { "queueId": { "type": "string", "minLength": 1, "description": "Identifier of the evaluation annotation queue.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "itemId": { "type": "string", "minLength": 1, "description": "Identifier of the dataset item or annotation queue item being addressed.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "queueId", "itemId" ], "required": [ "queueId", "itemId" ] }, "CompleteAnnotationQueueItemResponse": { "type": "object", "description": "Result of completing an evaluation object in an annotation queue.", "properties": { "item": { "description": "Annotation queue item returned by the operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/AnnotationQueueItem" } ] } } }, "AnnotationQueueItem": { "type": "object", "description": "Evaluation object assigned to an annotation queue with completion state and attribution.", "properties": { "itemId": { "type": "string", "description": "Identifier of the dataset or annotation queue item.", "x-presence": "implicit" }, "queueId": { "type": "string", "description": "Identifier of the annotation queue.", "x-presence": "implicit" }, "objectId": { "type": "string", "description": "Identifier of the evaluation object addressed by the comment or queue item.", "x-presence": "implicit" }, "objectType": { "oneOf": [ { "type": "string", "enum": [ "EVAL_TARGET_TYPE_TRACE", "EVAL_TARGET_TYPE_OBSERVATION", "EVAL_TARGET_TYPE_DATASET_RUN", "EVAL_TARGET_TYPE_SESSION" ], "x-enumDescriptions": { "EVAL_TARGET_TYPE_TRACE": "A complete trace identified by its trace identifier.", "EVAL_TARGET_TYPE_OBSERVATION": "A specific observation within a trace.", "EVAL_TARGET_TYPE_DATASET_RUN": "An evaluation run over a dataset.", "EVAL_TARGET_TYPE_SESSION": "A session grouping multiple traces; session scores are attached directly by the harness." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "EVAL_TARGET_TYPE_TRACE", "number": 1, "canonical": true, "description": "A complete trace identified by its trace identifier." }, { "name": "EVAL_TARGET_TYPE_OBSERVATION", "number": 2, "canonical": true, "description": "A specific observation within a trace." }, { "name": "EVAL_TARGET_TYPE_DATASET_RUN", "number": 3, "canonical": true, "description": "An evaluation run over a dataset." }, { "name": "EVAL_TARGET_TYPE_SESSION", "number": 4, "canonical": true, "description": "A session grouping multiple traces; session scores are attached directly by the harness." } ], "x-enum-description": "Kind of evaluation object a score or evaluation configuration addresses.", "description": "Kind of evaluation object addressed by the comment or annotation queue item.", "x-presence": "implicit" }, "status": { "oneOf": [ { "type": "string", "enum": [ "ANNOTATION_QUEUE_ITEM_STATUS_PENDING", "ANNOTATION_QUEUE_ITEM_STATUS_COMPLETED" ], "x-enumDescriptions": { "ANNOTATION_QUEUE_ITEM_STATUS_PENDING": "The item is waiting for its annotation to be completed.", "ANNOTATION_QUEUE_ITEM_STATUS_COMPLETED": "Annotation of the queue item has been completed." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "ANNOTATION_QUEUE_ITEM_STATUS_PENDING", "number": 1, "canonical": true, "description": "The item is waiting for its annotation to be completed." }, { "name": "ANNOTATION_QUEUE_ITEM_STATUS_COMPLETED", "number": 2, "canonical": true, "description": "Annotation of the queue item has been completed." } ], "x-enum-description": "Progress of a work item in a human annotation queue.", "description": "Completion state of the annotation queue item.", "x-presence": "implicit" }, "completedAt": { "type": "string", "format": "date-time", "description": "Time when the operation was marked complete.", "x-presence": "message" }, "completedBy": { "type": "string", "description": "Identifier of the user who completed the annotation queue item.", "x-presence": "implicit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when this record was created.", "x-presence": "message" } }, "x-reference-model": { "title": "AnnotationQueueItem", "url": "/api/models/annotation-queue-item#response" } }, "CreateAnnotationQueueRequest": { "type": "object", "description": "Inputs for creating a queue of evaluation objects awaiting annotation.", "properties": { "name": { "type": "string", "minLength": 1, "description": "Name assigned to, or used to filter, the evaluation record.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "scoreConfigIds": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "At least one: a queue's fixed config set is the whole difference between it\nand ad-hoc annotation.", "x-presence": "collection", "x-protovalidate": { "repeated": { "minItems": "1" } }, "x-validation-scope": "request" }, "description": { "type": "string", "description": "Human-readable explanation of the evaluation record.", "x-presence": "implicit" } }, "x-request-required": [ "name", "scoreConfigIds" ], "required": [ "name", "scoreConfigIds" ] }, "CreateAnnotationQueueResponse": { "type": "object", "description": "Result of creating a queue of evaluation objects awaiting annotation.", "properties": { "queueId": { "type": "string", "description": "Identifier of the evaluation annotation queue.", "x-presence": "implicit" } } }, "CreateCommentRequest": { "type": "object", "description": "Inputs for creating a comment attached to an evaluation object.", "properties": { "objectType": { "oneOf": [ { "type": "string", "enum": [ "COMMENT_OBJECT_TYPE_TRACE", "COMMENT_OBJECT_TYPE_OBSERVATION", "COMMENT_OBJECT_TYPE_SESSION", "COMMENT_OBJECT_TYPE_PROMPT" ], "x-enumDescriptions": { "COMMENT_OBJECT_TYPE_TRACE": "Attach the comment to a trace.", "COMMENT_OBJECT_TYPE_OBSERVATION": "Attach the comment to a particular observation.", "COMMENT_OBJECT_TYPE_SESSION": "Attach the comment to a session.", "COMMENT_OBJECT_TYPE_PROMPT": "Attach the comment to a specific prompt version using that version's UUID, not the prompt\nname. A comment on one version does not appear on later versions." } }, { "type": "integer", "format": "int32", "enum": [ 1, 2, 3, 4 ], "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "COMMENT_OBJECT_TYPE_TRACE", "number": 1, "canonical": true, "description": "Attach the comment to a trace." }, { "name": "COMMENT_OBJECT_TYPE_OBSERVATION", "number": 2, "canonical": true, "description": "Attach the comment to a particular observation." }, { "name": "COMMENT_OBJECT_TYPE_SESSION", "number": 3, "canonical": true, "description": "Attach the comment to a session." }, { "name": "COMMENT_OBJECT_TYPE_PROMPT", "number": 4, "canonical": true, "description": "Attach the comment to a specific prompt version using that version's UUID, not the prompt\nname. A comment on one version does not appear on later versions." } ], "x-enum-description": "Kind of evaluation object to which a reviewer comment is attached.", "description": "Kind of evaluation object to which the comment belongs.", "x-presence": "implicit", "x-protovalidate": { "enum": { "definedOnly": true, "notIn": [ 0 ] } }, "x-validation-scope": "request" }, "objectId": { "type": "string", "minLength": 1, "description": "Identifier of the evaluation object to which the comment belongs.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "content": { "type": "string", "minLength": 1, "maxLength": 3000, "description": "Body of the evaluation comment.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1", "maxLen": "3000" } }, "x-validation-scope": "request" } }, "x-request-required": [ "objectType", "objectId", "content" ], "required": [ "objectType", "objectId", "content" ] }, "CreateCommentResponse": { "type": "object", "description": "Result of creating a comment attached to an evaluation object.", "properties": { "commentId": { "type": "string", "description": "Identifier of the evaluation comment.", "x-presence": "implicit" } } }, "CreateDatasetRequest": { "type": "object", "description": "Inputs for creating an evaluation dataset.", "properties": { "name": { "type": "string", "minLength": 1, "description": "Name assigned to, or used to filter, the evaluation record.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "description": { "type": "string", "description": "Human-readable explanation of the evaluation record.", "x-presence": "implicit" }, "metadataJson": { "type": "string", "description": "Additional evaluation metadata serialized as JSON text.", "x-presence": "implicit" } }, "x-request-required": [ "name" ], "required": [ "name" ] }, "CreateDatasetResponse": { "type": "object", "description": "Result of creating an evaluation dataset.", "properties": { "datasetId": { "type": "string", "description": "Identifier of the evaluation dataset.", "x-presence": "implicit" } } }, "CreateScoreConfigRequest": { "type": "object", "description": "Inputs for creating the definition and allowed values of an evaluation score.", "properties": { "name": { "type": "string", "minLength": 1, "description": "Name assigned to, or used to filter, the evaluation record.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "dataType": { "oneOf": [ { "type": "string", "enum": [ "SCORE_DATA_TYPE_NUMERIC", "SCORE_DATA_TYPE_CATEGORICAL", "SCORE_DATA_TYPE_BOOLEAN", "SCORE_DATA_TYPE_TEXT" ], "x-enumDescriptions": { "SCORE_DATA_TYPE_NUMERIC": "A numeric measurement or rating.", "SCORE_DATA_TYPE_CATEGORICAL": "A value chosen from a named set of categories.", "SCORE_DATA_TYPE_BOOLEAN": "A true-or-false evaluation result.", "SCORE_DATA_TYPE_TEXT": "Free-form text supplied by an evaluator or reviewer." } }, { "type": "integer", "format": "int32", "enum": [ 1, 2, 3, 4 ], "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "SCORE_DATA_TYPE_NUMERIC", "number": 1, "canonical": true, "description": "A numeric measurement or rating." }, { "name": "SCORE_DATA_TYPE_CATEGORICAL", "number": 2, "canonical": true, "description": "A value chosen from a named set of categories." }, { "name": "SCORE_DATA_TYPE_BOOLEAN", "number": 3, "canonical": true, "description": "A true-or-false evaluation result." }, { "name": "SCORE_DATA_TYPE_TEXT", "number": 4, "canonical": true, "description": "Free-form text supplied by an evaluator or reviewer." } ], "x-enum-description": "Data representation of an evaluation score or score configuration.", "description": "Value type used to interpret the evaluation score.", "x-presence": "implicit", "x-protovalidate": { "enum": { "definedOnly": true, "notIn": [ 0 ] } }, "x-validation-scope": "request" }, "categoricalValues": { "type": "array", "items": { "type": "string" }, "description": "Allowed category values for the score configuration.", "x-presence": "collection" }, "minValue": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Lower numeric bound for the score range.", "x-presence": "implicit" }, "maxValue": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Upper numeric bound for the score range.", "x-presence": "implicit" } }, "x-request-required": [ "name", "dataType" ], "required": [ "name", "dataType" ] }, "CreateScoreConfigResponse": { "type": "object", "description": "Result of creating the definition and allowed values of an evaluation score.", "properties": { "configId": { "type": "string", "description": "Identifier of the evaluation score configuration.", "x-presence": "implicit" } } }, "DeleteCommentRequest": { "type": "object", "description": "Inputs for deleting a comment attached to an evaluation object.", "properties": { "commentId": { "type": "string", "minLength": 1, "description": "Identifier of the evaluation comment.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "commentId" ], "required": [ "commentId" ] }, "DeleteCommentResponse": { "type": "object", "description": "Result of deleting a comment attached to an evaluation object.", "properties": { "deleted": { "type": "boolean", "description": "Whether the deletion operation reported that it deleted the selected resource.", "x-presence": "implicit" } } }, "DeleteScoreRequest": { "type": "object", "description": "Inputs for deleting a score attached to an evaluation object.", "properties": { "scoreId": { "type": "string", "minLength": 1, "description": "Identifier of the recorded evaluation score.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "scoreId" ], "required": [ "scoreId" ] }, "DeleteScoreResponse": { "type": "object", "description": "Result of deleting a score attached to an evaluation object.", "properties": { "deleted": { "type": "boolean", "description": "Whether the deletion operation reported that it deleted the selected resource.", "x-presence": "implicit" } } }, "EnqueueForAnnotationRequest": { "type": "object", "description": "Inputs for adding an evaluation object to an annotation queue.", "properties": { "queueId": { "type": "string", "minLength": 1, "description": "Identifier of the evaluation annotation queue.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "targetType": { "oneOf": [ { "type": "string", "enum": [ "EVAL_TARGET_TYPE_TRACE", "EVAL_TARGET_TYPE_OBSERVATION", "EVAL_TARGET_TYPE_DATASET_RUN", "EVAL_TARGET_TYPE_SESSION" ], "x-enumDescriptions": { "EVAL_TARGET_TYPE_TRACE": "A complete trace identified by its trace identifier.", "EVAL_TARGET_TYPE_OBSERVATION": "A specific observation within a trace.", "EVAL_TARGET_TYPE_DATASET_RUN": "An evaluation run over a dataset.", "EVAL_TARGET_TYPE_SESSION": "A session grouping multiple traces; session scores are attached directly by the harness." } }, { "type": "integer", "format": "int32", "enum": [ 1, 2, 3, 4 ], "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "EVAL_TARGET_TYPE_TRACE", "number": 1, "canonical": true, "description": "A complete trace identified by its trace identifier." }, { "name": "EVAL_TARGET_TYPE_OBSERVATION", "number": 2, "canonical": true, "description": "A specific observation within a trace." }, { "name": "EVAL_TARGET_TYPE_DATASET_RUN", "number": 3, "canonical": true, "description": "An evaluation run over a dataset." }, { "name": "EVAL_TARGET_TYPE_SESSION", "number": 4, "canonical": true, "description": "A session grouping multiple traces; session scores are attached directly by the harness." } ], "x-enum-description": "Kind of evaluation object a score or evaluation configuration addresses.", "description": "Kind of evaluation object targeted by the score or annotation.", "x-presence": "implicit", "x-protovalidate": { "enum": { "definedOnly": true, "notIn": [ 0 ] } }, "x-validation-scope": "request" }, "targetId": { "type": "string", "minLength": 1, "description": "Identifier of the evaluation object targeted by the score or annotation.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "queueId", "targetType", "targetId" ], "required": [ "queueId", "targetType", "targetId" ] }, "EnqueueForAnnotationResponse": { "type": "object", "description": "Result of adding an evaluation object to an annotation queue.", "properties": { "queueItemId": { "type": "string", "description": "Identifier assigned to the item in the annotation queue.", "x-presence": "implicit" } } }, "GetDatasetRunRequest": { "type": "object", "description": "Inputs for retrieving a named run against an evaluation dataset.", "properties": { "datasetName": { "type": "string", "minLength": 1, "description": "Name used to address the evaluation dataset.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "runName": { "type": "string", "minLength": 1, "description": "Name assigned to the evaluation dataset run.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "datasetName", "runName" ], "required": [ "datasetName", "runName" ] }, "GetDatasetRunResponse": { "type": "object", "description": "Result of retrieving a named run against an evaluation dataset.", "properties": { "run": { "description": "Evaluation dataset run returned by the lookup.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/DatasetRun" } ] } } }, "DatasetRun": { "type": "object", "description": "Metadata describing one execution of an evaluation dataset.", "properties": { "runId": { "type": "string", "description": "Identifier of the dataset or candidate evaluation run.", "x-presence": "implicit" }, "datasetId": { "type": "string", "description": "Identifier of the evaluation dataset.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Name assigned to this execution of the evaluation dataset.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Human-readable description of the resource.", "x-presence": "implicit" }, "metadataJson": { "type": "string", "description": "Additional attributes serialized as a JSON object.", "x-presence": "implicit" }, "itemCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of dataset items reported for the dataset or run.", "x-presence": "implicit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when this record was created.", "x-presence": "message" } }, "x-reference-model": { "title": "DatasetRun", "url": "/api/models/dataset-run#response" } }, "GetOverviewRequest": { "type": "object", "description": "Inputs for retrieving aggregate evaluation activity and score statistics.", "properties": { "fromTime": { "type": "string", "format": "date-time", "description": "Beginning of the time range used to select evaluation records.", "x-presence": "message" }, "toTime": { "type": "string", "format": "date-time", "description": "End of the time range used to select evaluation records.", "x-presence": "message" }, "profileId": { "type": "string", "maxLength": 256, "description": "Identifier of the agent profile associated with the operation or generation.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" }, "environment": { "type": "string", "maxLength": 256, "description": "Environment label used to select evaluation records.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" } } }, "GetOverviewResponse": { "type": "object", "description": "Result of retrieving aggregate evaluation activity and score statistics.", "properties": { "overview": { "description": "Aggregate evaluation activity and score statistics for the selected scope.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/EvalOverview" } ] } } }, "EvalOverview": { "type": "object", "description": "Aggregated trace, score, latency, and profile metrics for an evaluation window.", "properties": { "totalTraces": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Total trace count reported for the selected evaluation window.", "x-presence": "implicit" }, "tracesByName": { "type": "array", "items": { "$ref": "#/components/schemas/NamedCount" }, "description": "Trace counts grouped by trace name.", "x-presence": "collection" }, "tracesOverTime": { "type": "array", "items": { "$ref": "#/components/schemas/TimeSeriesPoint" }, "description": "Trace counts grouped into time buckets.", "x-presence": "collection" }, "observationsByLevel": { "type": "array", "items": { "$ref": "#/components/schemas/TimeSeriesPoint" }, "description": "Observation counts grouped by reported log level.", "x-presence": "collection" }, "scores": { "type": "array", "items": { "$ref": "#/components/schemas/ScoreAggregate" }, "description": "Score aggregates grouped separately by metric name and source.", "x-presence": "collection" }, "scoreMovingAverage": { "type": "array", "items": { "$ref": "#/components/schemas/TimeSeriesPoint" }, "description": "Moving-average score series returned for the selected window.", "x-presence": "collection" }, "scoredTraceRatio": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Coverage card: share of traces carrying any score, and the annotated count.", "x-presence": "implicit" }, "annotatedTraceCount": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Number of traces reported to have annotations in the selected window.", "x-presence": "implicit" }, "byProfile": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileQualityRow" }, "description": "Evaluation metrics grouped by agent profile.", "x-presence": "collection" }, "latencyPercentiles": { "type": "array", "items": { "$ref": "#/components/schemas/LatencyPercentileRow" }, "description": "Latency percentile summaries grouped by trace name.", "x-presence": "collection" }, "recentLowScores": { "type": "array", "items": { "$ref": "#/components/schemas/Score" }, "description": "Recent scores selected by the overview’s low-score query.", "x-presence": "collection" } }, "x-reference-model": { "title": "EvalOverview", "url": "/api/models/eval-overview#response" } }, "NamedCount": { "type": "object", "description": "Count of evaluation records grouped under a shared label.", "properties": { "name": { "type": "string", "description": "Grouping label associated with this record count.", "x-presence": "implicit" }, "count": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Number of evaluation records represented by this group.", "x-presence": "implicit" } }, "x-reference-model": { "title": "NamedCount", "url": "/api/models/named-count#response" } }, "TimeSeriesPoint": { "type": "object", "description": "Numeric evaluation measurement associated with a time bucket and series.", "properties": { "bucket": { "type": "string", "format": "date-time", "description": "Time bucket identifying this point in the evaluation series.", "x-presence": "message" }, "value": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Numeric measurement recorded for this time bucket and series.", "x-presence": "implicit" }, "series": { "type": "string", "description": "Series key when the query is split — a score name, level, or profile id.", "x-presence": "implicit" } }, "x-reference-model": { "title": "TimeSeriesPoint", "url": "/api/models/time-series-point#response" } }, "ScoreAggregate": { "type": "object", "description": "Count and average for scores grouped by name and source.", "properties": { "name": { "type": "string", "description": "Metric name shared by the aggregated scores.", "x-presence": "implicit" }, "source": { "oneOf": [ { "type": "string", "enum": [ "SCORE_SOURCE_JUDGE", "SCORE_SOURCE_HUMAN", "SCORE_SOURCE_USER", "SCORE_SOURCE_HARNESS", "SCORE_SOURCE_EVAL" ], "x-enumDescriptions": { "SCORE_SOURCE_JUDGE": "A score produced by an automated judge.", "SCORE_SOURCE_HUMAN": "A score entered by a human reviewer through the annotation path.", "SCORE_SOURCE_USER": "Feedback supplied by an end user.", "SCORE_SOURCE_HARNESS": "A score written by an evaluation harness or another API-based producer.", "SCORE_SOURCE_EVAL": "A read-only score produced by the evaluation provider's managed evaluators; it cannot be\nwritten through the public score API." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "SCORE_SOURCE_JUDGE", "number": 1, "canonical": true, "description": "A score produced by an automated judge." }, { "name": "SCORE_SOURCE_HUMAN", "number": 2, "canonical": true, "description": "A score entered by a human reviewer through the annotation path." }, { "name": "SCORE_SOURCE_USER", "number": 3, "canonical": true, "description": "Feedback supplied by an end user." }, { "name": "SCORE_SOURCE_HARNESS", "number": 4, "canonical": true, "description": "A score written by an evaluation harness or another API-based producer." }, { "name": "SCORE_SOURCE_EVAL", "number": 5, "canonical": true, "description": "A read-only score produced by the evaluation provider's managed evaluators; it cannot be\nwritten through the public score API." } ], "x-enum-description": "Platform classification of who produced an evaluation score; the provider source label preserves\nits original vocabulary.", "description": "Source classification reported for the evaluation score.", "x-presence": "implicit" }, "count": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Number of evaluation records represented by this group.", "x-presence": "implicit" }, "average": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Average score value reported for the aggregate.", "x-presence": "implicit" } }, "x-reference-model": { "title": "ScoreAggregate", "url": "/api/models/score-aggregate#response" } }, "ProfileQualityRow": { "type": "object", "description": "Aggregated evaluation results and usage for one agent profile.", "properties": { "profileId": { "type": "string", "description": "Identifier of the agent profile associated with the generation.", "x-presence": "implicit" }, "traceCount": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Number of traces represented by this summary or group.", "x-presence": "implicit" }, "avgEndUserRating": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Average end-user rating reported for the selected generation group.", "x-presence": "implicit" }, "avgJudgeScore": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Average automated judge score reported for the selected generation group.", "x-presence": "implicit" }, "thumbsDownCount": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Number of negative thumb ratings reported for the selected group.", "x-presence": "implicit" } }, "x-reference-model": { "title": "ProfileQualityRow", "url": "/api/models/profile-quality-row#response" } }, "LatencyPercentileRow": { "type": "object", "description": "Latency percentiles aggregated for one evaluation trace name.", "properties": { "traceName": { "type": "string", "description": "Display name used to group or identify the evaluation trace.", "x-presence": "implicit" }, "p50": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "50th-percentile latency reported for the trace group.", "x-presence": "implicit" }, "p90": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "90th-percentile latency reported for the trace group.", "x-presence": "implicit" }, "p95": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "95th-percentile latency reported for the trace group.", "x-presence": "implicit" }, "p99": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "99th-percentile latency reported for the trace group.", "x-presence": "implicit" } }, "x-reference-model": { "title": "LatencyPercentileRow", "url": "/api/models/latency-percentile-row#response" } }, "Score": { "type": "object", "description": "Evaluation score with its value, source, target identity, and generation attribution.", "properties": { "scoreId": { "type": "string", "description": "Identifier of the evaluation score.", "x-presence": "implicit" }, "targetType": { "oneOf": [ { "type": "string", "enum": [ "EVAL_TARGET_TYPE_TRACE", "EVAL_TARGET_TYPE_OBSERVATION", "EVAL_TARGET_TYPE_DATASET_RUN", "EVAL_TARGET_TYPE_SESSION" ], "x-enumDescriptions": { "EVAL_TARGET_TYPE_TRACE": "A complete trace identified by its trace identifier.", "EVAL_TARGET_TYPE_OBSERVATION": "A specific observation within a trace.", "EVAL_TARGET_TYPE_DATASET_RUN": "An evaluation run over a dataset.", "EVAL_TARGET_TYPE_SESSION": "A session grouping multiple traces; session scores are attached directly by the harness." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "EVAL_TARGET_TYPE_TRACE", "number": 1, "canonical": true, "description": "A complete trace identified by its trace identifier." }, { "name": "EVAL_TARGET_TYPE_OBSERVATION", "number": 2, "canonical": true, "description": "A specific observation within a trace." }, { "name": "EVAL_TARGET_TYPE_DATASET_RUN", "number": 3, "canonical": true, "description": "An evaluation run over a dataset." }, { "name": "EVAL_TARGET_TYPE_SESSION", "number": 4, "canonical": true, "description": "A session grouping multiple traces; session scores are attached directly by the harness." } ], "x-enum-description": "Kind of evaluation object a score or evaluation configuration addresses.", "description": "Kind of evaluation object to which the score applies.", "x-presence": "implicit" }, "targetId": { "type": "string", "description": "Identifier of the evaluation object to which the score applies.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Metric name identifying the recorded evaluation score.", "x-presence": "implicit" }, "dataType": { "oneOf": [ { "type": "string", "enum": [ "SCORE_DATA_TYPE_NUMERIC", "SCORE_DATA_TYPE_CATEGORICAL", "SCORE_DATA_TYPE_BOOLEAN", "SCORE_DATA_TYPE_TEXT" ], "x-enumDescriptions": { "SCORE_DATA_TYPE_NUMERIC": "A numeric measurement or rating.", "SCORE_DATA_TYPE_CATEGORICAL": "A value chosen from a named set of categories.", "SCORE_DATA_TYPE_BOOLEAN": "A true-or-false evaluation result.", "SCORE_DATA_TYPE_TEXT": "Free-form text supplied by an evaluator or reviewer." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "SCORE_DATA_TYPE_NUMERIC", "number": 1, "canonical": true, "description": "A numeric measurement or rating." }, { "name": "SCORE_DATA_TYPE_CATEGORICAL", "number": 2, "canonical": true, "description": "A value chosen from a named set of categories." }, { "name": "SCORE_DATA_TYPE_BOOLEAN", "number": 3, "canonical": true, "description": "A true-or-false evaluation result." }, { "name": "SCORE_DATA_TYPE_TEXT", "number": 4, "canonical": true, "description": "Free-form text supplied by an evaluator or reviewer." } ], "x-enum-description": "Data representation of an evaluation score or score configuration.", "description": "Score value type used to interpret the numeric, categorical, or boolean value.", "x-presence": "implicit" }, "numericValue": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Numeric score value reported by the evaluator.", "x-presence": "implicit" }, "stringValue": { "type": "string", "description": "String operand or score value used by the selected evaluation type.", "x-presence": "implicit" }, "booleanValue": { "type": "boolean", "description": "Boolean operand or score value used by the selected evaluation type.", "x-presence": "implicit" }, "source": { "oneOf": [ { "type": "string", "enum": [ "SCORE_SOURCE_JUDGE", "SCORE_SOURCE_HUMAN", "SCORE_SOURCE_USER", "SCORE_SOURCE_HARNESS", "SCORE_SOURCE_EVAL" ], "x-enumDescriptions": { "SCORE_SOURCE_JUDGE": "A score produced by an automated judge.", "SCORE_SOURCE_HUMAN": "A score entered by a human reviewer through the annotation path.", "SCORE_SOURCE_USER": "Feedback supplied by an end user.", "SCORE_SOURCE_HARNESS": "A score written by an evaluation harness or another API-based producer.", "SCORE_SOURCE_EVAL": "A read-only score produced by the evaluation provider's managed evaluators; it cannot be\nwritten through the public score API." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "SCORE_SOURCE_JUDGE", "number": 1, "canonical": true, "description": "A score produced by an automated judge." }, { "name": "SCORE_SOURCE_HUMAN", "number": 2, "canonical": true, "description": "A score entered by a human reviewer through the annotation path." }, { "name": "SCORE_SOURCE_USER", "number": 3, "canonical": true, "description": "Feedback supplied by an end user." }, { "name": "SCORE_SOURCE_HARNESS", "number": 4, "canonical": true, "description": "A score written by an evaluation harness or another API-based producer." }, { "name": "SCORE_SOURCE_EVAL", "number": 5, "canonical": true, "description": "A read-only score produced by the evaluation provider's managed evaluators; it cannot be\nwritten through the public score API." } ], "x-enum-description": "Platform classification of who produced an evaluation score; the provider source label preserves\nits original vocabulary.", "description": "Source classification reported for the evaluation score.", "x-presence": "implicit" }, "comment": { "type": "string", "description": "Explanatory text attached to the evaluation score.", "x-presence": "implicit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when this record was created.", "x-presence": "message" }, "textValue": { "type": "string", "description": "Text value of the evaluation score.", "x-presence": "implicit" }, "authorUserId": { "type": "string", "description": "Identifier recorded for the user who authored the score.", "x-presence": "implicit" }, "configId": { "type": "string", "description": "Identifier of the score configuration defining the score’s value domain.", "x-presence": "implicit" }, "queueId": { "type": "string", "description": "Identifier of the annotation queue.", "x-presence": "implicit" }, "traceId": { "type": "string", "description": "Identifier of the evaluation trace.", "x-presence": "implicit" }, "observationId": { "type": "string", "description": "Identifier of the evaluation observation.", "x-presence": "implicit" }, "sessionId": { "type": "string", "description": "Identifier of the evaluation session grouping related traces.", "x-presence": "implicit" }, "datasetRunId": { "type": "string", "description": "Identifier of the dataset run associated with the score.", "x-presence": "implicit" }, "environment": { "type": "string", "description": "Environment label attached to the evaluation record.", "x-presence": "implicit" }, "metadataJson": { "type": "string", "description": "Additional attributes serialized as a JSON object.", "x-presence": "implicit" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time when this record was last updated.", "x-presence": "message" }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp associated with the conversation message or event.", "x-presence": "message" }, "traceName": { "type": "string", "description": "Denormalised for the Scores table's Trace Name column, which would\notherwise need one trace read per row.", "x-presence": "implicit" }, "userId": { "type": "string", "description": "Identifier of the user associated with the operation.", "x-presence": "implicit" }, "sourceLabel": { "type": "string", "description": "Original evaluation-provider source label, such as API, ANNOTATION or EVAL. Interpret it\nalongside source and authorship: API alone does not distinguish an end-user rating from a\nharness, and a source label does not independently prove verified human provenance.", "x-presence": "implicit" }, "conversationId": { "type": "string", "description": "Conversation identifier recorded in the score's own metadata. Scores authored directly in\nthe evaluation store can lack platform attribution; an empty link is not repaired by retrying.", "x-presence": "implicit" }, "messageId": { "type": "string", "description": "Identifier of the conversation message associated with the evaluation record.", "x-presence": "implicit" }, "messageSequence": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Sequence number of the evaluated message within its conversation.", "x-presence": "implicit" }, "profileId": { "type": "string", "description": "Identifier of the agent profile associated with the generation.", "x-presence": "implicit" }, "configHash": { "type": "string", "description": "Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation\nresults. Other settings are excluded; this is not an immutable profile revision.", "x-presence": "implicit" } }, "x-reference-model": { "title": "Score", "url": "/api/models/score#response" } }, "GetSessionRequest": { "type": "object", "description": "Inputs for retrieving an evaluation session and its associated traces.", "properties": { "sessionId": { "type": "string", "minLength": 1, "description": "Identifier of the evaluation session grouping related traces.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "sessionId" ], "required": [ "sessionId" ] }, "GetSessionResponse": { "type": "object", "description": "Result of retrieving an evaluation session and its associated traces.", "properties": { "session": { "description": "Evaluation session details returned by the lookup.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/SessionDetail" } ] }, "contentRedacted": { "type": "boolean", "description": "Whether sensitive evaluation content has been removed from the returned view.", "x-presence": "implicit" } } }, "SessionDetail": { "type": "object", "description": "Evaluation session summary together with the traces belonging to the session.", "properties": { "summary": { "description": "Summary information for the evaluation trace or session.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/SessionSummary" } ] }, "traces": { "type": "array", "items": { "$ref": "#/components/schemas/TraceSummary" }, "description": "Evaluation traces returned by the query.", "x-presence": "collection" } }, "x-reference-model": { "title": "SessionDetail", "url": "/api/models/session-detail#response" } }, "SessionSummary": { "type": "object", "description": "Aggregated trace, usage, and score information for an evaluation session.", "properties": { "sessionId": { "type": "string", "description": "Identifier of the evaluation session grouping related traces.", "x-presence": "implicit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when this record was created.", "x-presence": "message" }, "durationSeconds": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Elapsed session duration, in seconds.", "x-presence": "implicit" }, "environment": { "type": "string", "description": "Environment label attached to the evaluation record.", "x-presence": "implicit" }, "userIds": { "type": "array", "items": { "type": "string" }, "description": "Identifiers of the users selected by the operation.", "x-presence": "collection" }, "traceCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of traces represented by this summary or group.", "x-presence": "implicit" }, "totalCost": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Total cost reported for the evaluated generation or aggregate.", "x-presence": "implicit" }, "inputTokens": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Input-token usage reported for the evaluated generation.", "x-presence": "implicit" }, "outputTokens": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Output-token usage reported for the evaluated generation.", "x-presence": "implicit" }, "totalTokens": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Total token usage reported for the evaluated generation or aggregate.", "x-presence": "implicit" }, "traceTags": { "type": "array", "items": { "type": "string" }, "description": "Labels collected from the session’s evaluation traces.", "x-presence": "collection" }, "scores": { "type": "array", "items": { "$ref": "#/components/schemas/Score" }, "description": "Evaluation scores returned for the selected objects or query.", "x-presence": "collection" }, "commentCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of comments reported on the evaluation object.", "x-presence": "implicit" }, "metadataJson": { "type": "string", "description": "Additional attributes serialized as a JSON object.", "x-presence": "implicit" }, "bookmarked": { "type": "boolean", "description": "Whether the evaluation object is bookmarked.", "x-presence": "implicit" }, "conversationIds": { "type": "array", "items": { "type": "string" }, "description": "Conversation identifiers observed on the session’s traces; a session may span multiple\nconversations.", "x-presence": "collection" } }, "x-reference-model": { "title": "SessionSummary", "url": "/api/models/session-summary#response" } }, "TraceSummary": { "type": "object", "description": "Evaluation summary for a conversation turn, including its recorded conversation, message and\nprofile attribution.", "properties": { "traceId": { "type": "string", "description": "Identifier of the evaluation trace.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Name recorded for the evaluation trace.", "x-presence": "implicit" }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp associated with the conversation message or event.", "x-presence": "message" }, "inputJson": { "type": "string", "description": "Evaluation input serialized as JSON.", "x-presence": "implicit" }, "outputJson": { "type": "string", "description": "Evaluation output serialized as JSON.", "x-presence": "implicit" }, "latencySeconds": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Elapsed observation latency, in seconds.", "x-presence": "implicit" }, "totalCost": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Total cost reported for the evaluated generation or aggregate.", "x-presence": "implicit" }, "environment": { "type": "string", "description": "Environment label attached to the evaluation record.", "x-presence": "implicit" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Labels associated with the resource for organization or filtering.", "x-presence": "collection" }, "metadataJson": { "type": "string", "description": "Additional attributes serialized as a JSON object.", "x-presence": "implicit" }, "bookmarked": { "type": "boolean", "description": "Whether the evaluation object is bookmarked.", "x-presence": "implicit" }, "version": { "type": "string", "description": "Version of the resource represented by this message.", "x-presence": "implicit" }, "release": { "type": "string", "description": "Application release identifier attached to the trace.", "x-presence": "implicit" }, "userId": { "type": "string", "description": "Identifier of the user associated with the operation.", "x-presence": "implicit" }, "sessionId": { "type": "string", "description": "Identifier of the evaluation session grouping related traces.", "x-presence": "implicit" }, "observationCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of observations reported for the evaluation object.", "x-presence": "implicit" }, "conversationId": { "type": "string", "description": "Identifier of the conversation associated with the trace.", "x-presence": "implicit" }, "sourceUserMessageId": { "type": "string", "description": "Identifier of the user message that opened the evaluated generation turn.", "x-presence": "implicit" }, "profileId": { "type": "string", "description": "Identifier of the agent profile associated with the generation.", "x-presence": "implicit" }, "configHash": { "type": "string", "description": "Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation\nresults. Other settings are excluded; this is not an immutable profile revision.", "x-presence": "implicit" }, "inputTokens": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Input-token usage reported for the evaluated generation.", "x-presence": "implicit" }, "outputTokens": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Output-token usage reported for the evaluated generation.", "x-presence": "implicit" }, "totalTokens": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Total token usage reported for the evaluated generation or aggregate.", "x-presence": "implicit" }, "errorCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of observations reported at error level.", "x-presence": "implicit" }, "warningCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of observations reported at warning level.", "x-presence": "implicit" }, "defaultCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of observations reported at the default level.", "x-presence": "implicit" }, "debugCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of observations reported at debug level.", "x-presence": "implicit" }, "scores": { "type": "array", "items": { "$ref": "#/components/schemas/Score" }, "description": "Evaluation scores returned for the selected objects or query.", "x-presence": "collection" }, "commentCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of comments reported on the evaluation object.", "x-presence": "implicit" } }, "x-reference-model": { "title": "TraceSummary", "url": "/api/models/trace-summary#response" } }, "GetTraceRequest": { "type": "object", "description": "Inputs for retrieving an evaluation trace with its recorded generation details. Supply exactly\none address: trace_id, or both conversation_id and source_user_message_id.", "properties": { "traceId": { "type": "string", "description": "Identifier of the evaluation trace.", "x-presence": "implicit" }, "conversationId": { "type": "string", "maxLength": 256, "description": "Identifier of the conversation associated with the evaluation record.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" }, "sourceUserMessageId": { "type": "string", "maxLength": 256, "description": "Identifier of the user message that started the evaluated turn, not the assistant reply's\nmessage identifier. Supply it together with conversation_id when addressing by turn.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" } }, "x-protovalidate": { "cel": [ { "id": "exactly_one_trace_ref", "message": "exactly one of trace_id or (conversation_id + source_user_message_id) must be set", "expression": "(this.trace_id != '') != (this.conversation_id != '' && this.source_user_message_id != '')" } ] }, "x-validation-scope": "request" }, "GetTraceResponse": { "type": "object", "description": "Result of retrieving an evaluation trace with its recorded generation details.", "properties": { "trace": { "description": "Evaluation trace details returned by the lookup.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/TraceDetail" } ] }, "contentRedacted": { "type": "boolean", "description": "Whether returned trace content is redacted. Redaction occurs before the trace is recorded, so\nits text is not a faithful copy of the conversation store.", "x-presence": "implicit" } } }, "TraceDetail": { "type": "object", "description": "Evaluation trace summary together with its observations and attached scores.", "properties": { "summary": { "description": "Summary information for the evaluation trace or session.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/TraceSummary" } ] }, "observations": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" }, "description": "Observations associated with the trace or returned by the query.", "x-presence": "collection" }, "scores": { "type": "array", "items": { "$ref": "#/components/schemas/Score" }, "description": "Evaluation scores returned for the selected objects or query.", "x-presence": "collection" } }, "x-reference-model": { "title": "TraceDetail", "url": "/api/models/trace-detail#response" } }, "Observation": { "type": "object", "description": "Timed evaluation span or generation record with model usage, inputs, outputs, and scores.\nA generation observation originates the profile and configuration attribution promoted to\nits trace; callers can read those links directly on either record.", "properties": { "observationId": { "type": "string", "description": "Identifier of the evaluation observation.", "x-presence": "implicit" }, "traceId": { "type": "string", "description": "Identifier of the evaluation trace.", "x-presence": "implicit" }, "parentObservationId": { "type": "string", "description": "Identifier of the parent observation within the trace.", "x-presence": "implicit" }, "type": { "oneOf": [ { "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" ], "x-enumDescriptions": { "OBSERVATION_TYPE_SPAN": "A timed unit of work represented as a span.", "OBSERVATION_TYPE_GENERATION": "A model-generation operation and its recorded inputs, outputs and usage.", "OBSERVATION_TYPE_EVENT": "A point-in-time event rather than a timed operation.", "OBSERVATION_TYPE_TOOL": "Execution of a tool call.", "OBSERVATION_TYPE_RETRIEVER": "Retrieval of supporting documents or other context.", "OBSERVATION_TYPE_AGENT": "An agent-level operation reported in the trace.", "OBSERVATION_TYPE_CHAIN": "A sequence or chain of related processing steps.", "OBSERVATION_TYPE_EMBEDDING": "Computation of vector embeddings.", "OBSERVATION_TYPE_EVALUATOR": "An evaluator operation that assesses another result.", "OBSERVATION_TYPE_GUARDRAIL": "A guardrail check on inputs, outputs or processing." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "OBSERVATION_TYPE_SPAN", "number": 1, "canonical": true, "description": "A timed unit of work represented as a span." }, { "name": "OBSERVATION_TYPE_GENERATION", "number": 2, "canonical": true, "description": "A model-generation operation and its recorded inputs, outputs and usage." }, { "name": "OBSERVATION_TYPE_EVENT", "number": 3, "canonical": true, "description": "A point-in-time event rather than a timed operation." }, { "name": "OBSERVATION_TYPE_TOOL", "number": 4, "canonical": true, "description": "Execution of a tool call." }, { "name": "OBSERVATION_TYPE_RETRIEVER", "number": 5, "canonical": true, "description": "Retrieval of supporting documents or other context." }, { "name": "OBSERVATION_TYPE_AGENT", "number": 6, "canonical": true, "description": "An agent-level operation reported in the trace." }, { "name": "OBSERVATION_TYPE_CHAIN", "number": 7, "canonical": true, "description": "A sequence or chain of related processing steps." }, { "name": "OBSERVATION_TYPE_EMBEDDING", "number": 8, "canonical": true, "description": "Computation of vector embeddings." }, { "name": "OBSERVATION_TYPE_EVALUATOR", "number": 9, "canonical": true, "description": "An evaluator operation that assesses another result." }, { "name": "OBSERVATION_TYPE_GUARDRAIL", "number": 10, "canonical": true, "description": "A guardrail check on inputs, outputs or processing." } ], "x-enum-description": "Semantic category of a trace observation, including categories accepted from upstream even when\nthe platform does not emit them.", "description": "Observation kind reported by the evaluation provider.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Operation name recorded for the evaluation observation.", "x-presence": "implicit" }, "level": { "oneOf": [ { "type": "string", "enum": [ "OBSERVATION_LEVEL_DEBUG", "OBSERVATION_LEVEL_DEFAULT", "OBSERVATION_LEVEL_WARNING", "OBSERVATION_LEVEL_ERROR" ], "x-enumDescriptions": { "OBSERVATION_LEVEL_DEBUG": "Detailed diagnostic information intended for debugging.", "OBSERVATION_LEVEL_DEFAULT": "Ordinary observation information without an elevated warning or error level.", "OBSERVATION_LEVEL_WARNING": "A condition reported at warning severity.", "OBSERVATION_LEVEL_ERROR": "A condition reported at error severity." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "OBSERVATION_LEVEL_DEBUG", "number": 1, "canonical": true, "description": "Detailed diagnostic information intended for debugging." }, { "name": "OBSERVATION_LEVEL_DEFAULT", "number": 2, "canonical": true, "description": "Ordinary observation information without an elevated warning or error level." }, { "name": "OBSERVATION_LEVEL_WARNING", "number": 3, "canonical": true, "description": "A condition reported at warning severity." }, { "name": "OBSERVATION_LEVEL_ERROR", "number": 4, "canonical": true, "description": "A condition reported at error severity." } ], "x-enum-description": "Diagnostic severity attached to an evaluation observation.", "description": "Observation log level reported by the evaluation provider.", "x-presence": "implicit" }, "statusMessage": { "type": "string", "description": "Diagnostic text explaining the reported state.", "x-presence": "implicit" }, "startTime": { "type": "string", "format": "date-time", "description": "Beginning of the time interval represented by this operation.", "x-presence": "message" }, "endTime": { "type": "string", "format": "date-time", "description": "End of the time interval represented by this operation.", "x-presence": "message" }, "completionStartTime": { "type": "string", "format": "date-time", "description": "Time to first token, generations only.", "x-presence": "message" }, "latencySeconds": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Elapsed observation latency, in seconds.", "x-presence": "implicit" }, "inputJson": { "type": "string", "description": "Evaluation input serialized as JSON.", "x-presence": "implicit" }, "outputJson": { "type": "string", "description": "Evaluation output serialized as JSON.", "x-presence": "implicit" }, "metadataJson": { "type": "string", "description": "Additional attributes serialized as a JSON object.", "x-presence": "implicit" }, "model": { "type": "string", "description": "Model identifier recorded for the evaluated generation.", "x-presence": "implicit" }, "modelParametersJson": { "type": "string", "description": "Model parameters recorded as a serialized JSON object.", "x-presence": "implicit" }, "inputTokens": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Input-token usage reported for the evaluated generation.", "x-presence": "implicit" }, "outputTokens": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Output-token usage reported for the evaluated generation.", "x-presence": "implicit" }, "totalTokens": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Total token usage reported for the evaluated generation or aggregate.", "x-presence": "implicit" }, "inputCost": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Cost attributed to model input by the evaluation provider.", "x-presence": "implicit" }, "outputCost": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Cost attributed to model output by the evaluation provider.", "x-presence": "implicit" }, "totalCost": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Total cost reported for the evaluated generation or aggregate.", "x-presence": "implicit" }, "environment": { "type": "string", "description": "Environment label attached to the evaluation record.", "x-presence": "implicit" }, "version": { "type": "string", "description": "Version of the resource represented by this message.", "x-presence": "implicit" }, "promptName": { "type": "string", "description": "Name of the versioned prompt associated with the generation.", "x-presence": "implicit" }, "promptVersion": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Version of the prompt associated with the generation.", "x-presence": "implicit" }, "scores": { "type": "array", "items": { "$ref": "#/components/schemas/Score" }, "description": "Evaluation scores returned for the selected objects or query.", "x-presence": "collection" }, "commentCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of comments reported on the evaluation object.", "x-presence": "implicit" }, "conversationId": { "type": "string", "description": "Identifier of the conversation associated with this evaluation observation, when recorded.", "x-presence": "implicit" }, "sourceUserMessageId": { "type": "string", "description": "Identifier of the user message that opened the evaluated generation turn.", "x-presence": "implicit" }, "profileId": { "type": "string", "description": "Identifier of the agent profile associated with the generation.", "x-presence": "implicit" }, "configHash": { "type": "string", "description": "Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation\nresults. Other settings are excluded; this is not an immutable profile revision.", "x-presence": "implicit" } }, "x-reference-model": { "title": "Observation", "url": "/api/models/observation#response" } }, "ListAnnotationQueueItemsRequest": { "type": "object", "description": "Inputs for listing evaluation objects in an annotation queue.", "properties": { "queueId": { "type": "string", "minLength": 1, "description": "Identifier of the evaluation annotation queue.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "page": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 2147483647, "description": "Page number requested from the backing service.", "x-presence": "implicit", "x-protovalidate": { "int32": { "gte": 0 } }, "x-validation-scope": "request" }, "pageSize": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100, "description": "Requested maximum number of entries in a result page.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 100, "gte": 0 } }, "x-validation-scope": "request" }, "status": { "oneOf": [ { "type": "string", "enum": [ "ANNOTATION_QUEUE_ITEM_STATUS_PENDING", "ANNOTATION_QUEUE_ITEM_STATUS_COMPLETED" ], "x-enumDescriptions": { "ANNOTATION_QUEUE_ITEM_STATUS_PENDING": "The item is waiting for its annotation to be completed.", "ANNOTATION_QUEUE_ITEM_STATUS_COMPLETED": "Annotation of the queue item has been completed." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "ANNOTATION_QUEUE_ITEM_STATUS_PENDING", "number": 1, "canonical": true, "description": "The item is waiting for its annotation to be completed." }, { "name": "ANNOTATION_QUEUE_ITEM_STATUS_COMPLETED", "number": 2, "canonical": true, "description": "Annotation of the queue item has been completed." } ], "x-enum-description": "Progress of a work item in a human annotation queue.", "description": "Annotation state used to restrict the queue listing. Omit to include both pending and\ncompleted items.", "x-presence": "implicit" } }, "x-request-required": [ "queueId" ], "required": [ "queueId" ] }, "ListAnnotationQueueItemsResponse": { "type": "object", "description": "Result of listing evaluation objects in an annotation queue.", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AnnotationQueueItem" }, "description": "Evaluation annotation queue items in this page.", "x-presence": "collection" }, "page": { "description": "Page number, page size, and result totals returned by the evaluation provider.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/EvaluationPageInfo" } ] } } }, "EvaluationPageInfo": { "type": "object", "description": "Offset-pagination position, page size and result totals.", "properties": { "page": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "One-based page number.", "x-presence": "implicit" }, "limit": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum number of entries requested from the listing.", "x-presence": "implicit" }, "totalItems": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Total item count reported for the selected dataset query.", "x-presence": "implicit" }, "totalPages": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Total number of pages reported for the current query.", "x-presence": "implicit" } }, "x-reference-model": { "title": "EvaluationPageInfo", "url": "/api/models/evaluation-page-info#response" } }, "ListAnnotationQueuesRequest": { "type": "object", "description": "Inputs for listing queues of evaluation objects awaiting annotation.", "properties": { "page": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 2147483647, "description": "Page number requested from the backing service.", "x-presence": "implicit", "x-protovalidate": { "int32": { "gte": 0 } }, "x-validation-scope": "request" }, "pageSize": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100, "description": "Requested maximum number of entries in a result page.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 100, "gte": 0 } }, "x-validation-scope": "request" } } }, "ListAnnotationQueuesResponse": { "type": "object", "description": "Result of listing queues of evaluation objects awaiting annotation.", "properties": { "queues": { "type": "array", "items": { "$ref": "#/components/schemas/AnnotationQueue" }, "description": "Evaluation annotation queues included in this result page.", "x-presence": "collection" }, "page": { "description": "Page number, page size, and result totals returned by the evaluation provider.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/EvaluationPageInfo" } ] } } }, "AnnotationQueue": { "type": "object", "description": "Named work queue assigning score configurations to human annotation items.", "properties": { "queueId": { "type": "string", "description": "Identifier of the annotation queue.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Display name of the annotation work queue.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Human-readable description of the resource.", "x-presence": "implicit" }, "scoreConfigIds": { "type": "array", "items": { "type": "string" }, "description": "Score configurations available when annotating items in this queue. At least one configuration\nis required.", "x-presence": "collection" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when this record was created.", "x-presence": "message" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time when this record was last updated.", "x-presence": "message" }, "pendingCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of queue items awaiting annotation.", "x-presence": "implicit" }, "completedCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of queue items reported completed.", "x-presence": "implicit" } }, "x-reference-model": { "title": "AnnotationQueue", "url": "/api/models/annotation-queue#response" } }, "ListCommentsRequest": { "type": "object", "description": "Inputs for listing comments attached to evaluation objects.", "properties": { "objectType": { "oneOf": [ { "type": "string", "enum": [ "COMMENT_OBJECT_TYPE_TRACE", "COMMENT_OBJECT_TYPE_OBSERVATION", "COMMENT_OBJECT_TYPE_SESSION", "COMMENT_OBJECT_TYPE_PROMPT" ], "x-enumDescriptions": { "COMMENT_OBJECT_TYPE_TRACE": "Attach the comment to a trace.", "COMMENT_OBJECT_TYPE_OBSERVATION": "Attach the comment to a particular observation.", "COMMENT_OBJECT_TYPE_SESSION": "Attach the comment to a session.", "COMMENT_OBJECT_TYPE_PROMPT": "Attach the comment to a specific prompt version using that version's UUID, not the prompt\nname. A comment on one version does not appear on later versions." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "COMMENT_OBJECT_TYPE_TRACE", "number": 1, "canonical": true, "description": "Attach the comment to a trace." }, { "name": "COMMENT_OBJECT_TYPE_OBSERVATION", "number": 2, "canonical": true, "description": "Attach the comment to a particular observation." }, { "name": "COMMENT_OBJECT_TYPE_SESSION", "number": 3, "canonical": true, "description": "Attach the comment to a session." }, { "name": "COMMENT_OBJECT_TYPE_PROMPT", "number": 4, "canonical": true, "description": "Attach the comment to a specific prompt version using that version's UUID, not the prompt\nname. A comment on one version does not appear on later versions." } ], "x-enum-description": "Kind of evaluation object to which a reviewer comment is attached.", "description": "Kind of evaluation object to which the comment belongs.", "x-presence": "implicit" }, "objectId": { "type": "string", "description": "Identifier of the evaluation object to which the comment belongs.", "x-presence": "implicit" }, "page": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 2147483647, "description": "Page number requested from the backing service.", "x-presence": "implicit", "x-protovalidate": { "int32": { "gte": 0 } }, "x-validation-scope": "request" }, "pageSize": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100, "description": "Requested maximum number of entries in a result page.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 100, "gte": 0 } }, "x-validation-scope": "request" } } }, "ListCommentsResponse": { "type": "object", "description": "Result of listing comments attached to evaluation objects.", "properties": { "comments": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" }, "description": "Evaluation comments included in this result page.", "x-presence": "collection" }, "page": { "description": "Page number, page size, and result totals returned by the evaluation provider.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/EvaluationPageInfo" } ] } } }, "Comment": { "type": "object", "description": "Authored text attached to a trace, observation, or other evaluation object.", "properties": { "commentId": { "type": "string", "description": "Identifier of the evaluation comment.", "x-presence": "implicit" }, "objectType": { "oneOf": [ { "type": "string", "enum": [ "COMMENT_OBJECT_TYPE_TRACE", "COMMENT_OBJECT_TYPE_OBSERVATION", "COMMENT_OBJECT_TYPE_SESSION", "COMMENT_OBJECT_TYPE_PROMPT" ], "x-enumDescriptions": { "COMMENT_OBJECT_TYPE_TRACE": "Attach the comment to a trace.", "COMMENT_OBJECT_TYPE_OBSERVATION": "Attach the comment to a particular observation.", "COMMENT_OBJECT_TYPE_SESSION": "Attach the comment to a session.", "COMMENT_OBJECT_TYPE_PROMPT": "Attach the comment to a specific prompt version using that version's UUID, not the prompt\nname. A comment on one version does not appear on later versions." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "COMMENT_OBJECT_TYPE_TRACE", "number": 1, "canonical": true, "description": "Attach the comment to a trace." }, { "name": "COMMENT_OBJECT_TYPE_OBSERVATION", "number": 2, "canonical": true, "description": "Attach the comment to a particular observation." }, { "name": "COMMENT_OBJECT_TYPE_SESSION", "number": 3, "canonical": true, "description": "Attach the comment to a session." }, { "name": "COMMENT_OBJECT_TYPE_PROMPT", "number": 4, "canonical": true, "description": "Attach the comment to a specific prompt version using that version's UUID, not the prompt\nname. A comment on one version does not appear on later versions." } ], "x-enum-description": "Kind of evaluation object to which a reviewer comment is attached.", "description": "Kind of evaluation object addressed by the comment or annotation queue item.", "x-presence": "implicit" }, "objectId": { "type": "string", "description": "Identifier of the evaluation object addressed by the comment or queue item.", "x-presence": "implicit" }, "content": { "type": "string", "description": "Text content of the evaluation comment.", "x-presence": "implicit" }, "authorUserId": { "type": "string", "description": "Identifier recorded for the user who authored the comment.", "x-presence": "implicit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when this record was created.", "x-presence": "message" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time when this record was last updated.", "x-presence": "message" } }, "x-reference-model": { "title": "Comment", "url": "/api/models/comment#response" } }, "ListDatasetItemsRequest": { "type": "object", "description": "Inputs for listing input and expected-output pairs in an evaluation dataset.", "properties": { "datasetId": { "type": "string", "description": "Identifier of the evaluation dataset.", "x-presence": "implicit" }, "datasetName": { "type": "string", "description": "Name used to address the evaluation dataset.", "x-presence": "implicit" }, "page": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 2147483647, "description": "Page number requested from the backing service.", "x-presence": "implicit", "x-protovalidate": { "int32": { "gte": 0 } }, "x-validation-scope": "request" }, "pageSize": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100, "description": "Requested maximum number of entries in a result page.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 100, "gte": 0 } }, "x-validation-scope": "request" }, "sourceTraceId": { "type": "string", "description": "Identifier of the trace used as the source for the dataset item.", "x-presence": "implicit" }, "onlyMissingExpectedOutput": { "type": "boolean", "description": "Backs the curation list: items still lacking ground truth.", "x-presence": "implicit" } } }, "ListDatasetItemsResponse": { "type": "object", "description": "Result of listing input and expected-output pairs in an evaluation dataset.", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetItem" }, "description": "Evaluation dataset items in this page.", "x-presence": "collection" }, "page": { "description": "Page number, page size, and result totals returned by the evaluation provider.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/EvaluationPageInfo" } ] } } }, "DatasetItem": { "type": "object", "description": "One evaluation input with its expected output and source trace references.", "properties": { "itemId": { "type": "string", "description": "Identifier of the dataset or annotation queue item.", "x-presence": "implicit" }, "datasetId": { "type": "string", "description": "Identifier of the evaluation dataset.", "x-presence": "implicit" }, "datasetName": { "type": "string", "description": "Name of the evaluation dataset.", "x-presence": "implicit" }, "inputJson": { "type": "string", "description": "Evaluation input serialized as JSON.", "x-presence": "implicit" }, "expectedOutputJson": { "type": "string", "description": "Expected output serialized as JSON. Empty until a curator supplies an expected result.", "x-presence": "implicit" }, "metadataJson": { "type": "string", "description": "Additional attributes serialized as a JSON object.", "x-presence": "implicit" }, "sourceTraceId": { "type": "string", "description": "Identifier of the trace from which the dataset item originated.", "x-presence": "implicit" }, "sourceObservationId": { "type": "string", "description": "Identifier of the observation from which the dataset item originated.", "x-presence": "implicit" }, "status": { "oneOf": [ { "type": "string", "enum": [ "DATASET_ITEM_STATUS_ACTIVE", "DATASET_ITEM_STATUS_ARCHIVED" ], "x-enumDescriptions": { "DATASET_ITEM_STATUS_ACTIVE": "The dataset item is active.", "DATASET_ITEM_STATUS_ARCHIVED": "The dataset item is archived and retained as historical content." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "DATASET_ITEM_STATUS_ACTIVE", "number": 1, "canonical": true, "description": "The dataset item is active." }, { "name": "DATASET_ITEM_STATUS_ARCHIVED", "number": 2, "canonical": true, "description": "The dataset item is archived and retained as historical content." } ], "x-enum-description": "Whether a dataset item is active or retained as archived content.", "description": "State controlling whether the dataset item participates in evaluation.", "x-presence": "implicit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when this record was created.", "x-presence": "message" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time when this record was last updated.", "x-presence": "message" } }, "x-reference-model": { "title": "DatasetItem", "url": "/api/models/dataset-item#response" } }, "ListDatasetRunsRequest": { "type": "object", "description": "Inputs for listing recorded runs against an evaluation dataset.", "properties": { "datasetName": { "type": "string", "minLength": 1, "description": "Name used to address the evaluation dataset.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "pageSize": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100, "description": "Requested maximum number of entries in a result page.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 100, "gte": 0 } }, "x-validation-scope": "request" }, "cursor": { "type": "string", "maxLength": 4096, "description": "Opaque cursor from the previous response’s cursor_page.next_cursor. Leave empty for the first\npage.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "4096" } }, "x-validation-scope": "request" } }, "x-request-required": [ "datasetName" ], "required": [ "datasetName" ] }, "ListDatasetRunsResponse": { "type": "object", "description": "Result of listing recorded runs against an evaluation dataset.", "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetRun" }, "description": "Evaluation dataset runs included in this result page.", "x-presence": "collection" }, "cursorPage": { "description": "Cursor pagination details accompanying this result page.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/CursorPageInfo" } ] } } }, "CursorPageInfo": { "type": "object", "description": "Opaque-cursor pagination details. A cursor is used to request the next page; arbitrary\npage-number seeking is not supported.", "properties": { "nextCursor": { "type": "string", "description": "Pass back as the request's `cursor` for the next page. Empty on the last\npage.", "x-presence": "implicit" }, "limit": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum number of entries requested from the listing.", "x-presence": "implicit" }, "totalItems": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Total number of matching items when it can be counted exactly. Absent when the selected\nfilters do not support an exact total.", "x-presence": "explicit" } }, "x-reference-model": { "title": "CursorPageInfo", "url": "/api/models/cursor-page-info#response" } }, "ListDatasetsRequest": { "type": "object", "description": "Inputs for listing evaluation datasets.", "properties": { "page": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 2147483647, "description": "Page number requested from the backing service.", "x-presence": "implicit", "x-protovalidate": { "int32": { "gte": 0 } }, "x-validation-scope": "request" }, "pageSize": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100, "description": "Requested maximum number of entries in a result page.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 100, "gte": 0 } }, "x-validation-scope": "request" } } }, "ListDatasetsResponse": { "type": "object", "description": "Result of listing evaluation datasets.", "properties": { "datasets": { "type": "array", "items": { "$ref": "#/components/schemas/Dataset" }, "description": "Evaluation datasets included in this result page.", "x-presence": "collection" }, "page": { "description": "Page number, page size, and result totals returned by the evaluation provider.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/EvaluationPageInfo" } ] } } }, "Dataset": { "type": "object", "description": "Evaluation dataset metadata, item counts, run history, and input/output schemas.", "properties": { "datasetId": { "type": "string", "description": "Identifier of the evaluation dataset.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Name identifying the evaluation dataset.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Human-readable description of the resource.", "x-presence": "implicit" }, "metadataJson": { "type": "string", "description": "Additional attributes serialized as a JSON object.", "x-presence": "implicit" }, "itemCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of dataset items reported for the dataset or run.", "x-presence": "implicit" }, "runCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of runs reported for the evaluation dataset.", "x-presence": "implicit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when this record was created.", "x-presence": "message" }, "lastRunAt": { "type": "string", "format": "date-time", "description": "Time when the dataset was most recently evaluated.", "x-presence": "message" }, "inputSchemaJson": { "type": "string", "description": "JSON Schema describing dataset input values.", "x-presence": "implicit" }, "expectedOutputSchemaJson": { "type": "string", "description": "JSON Schema describing expected dataset output values.", "x-presence": "implicit" } }, "x-reference-model": { "title": "Dataset", "url": "/api/models/dataset#response" } }, "ListObservationsRequest": { "type": "object", "description": "Inputs for listing observations recorded within evaluation traces.", "properties": { "pageSize": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100, "description": "Requested maximum number of entries in a result page.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 100, "gte": 0 } }, "x-validation-scope": "request" }, "traceId": { "type": "string", "description": "Identifier of the evaluation trace.", "x-presence": "implicit" }, "type": { "oneOf": [ { "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" ], "x-enumDescriptions": { "OBSERVATION_TYPE_SPAN": "A timed unit of work represented as a span.", "OBSERVATION_TYPE_GENERATION": "A model-generation operation and its recorded inputs, outputs and usage.", "OBSERVATION_TYPE_EVENT": "A point-in-time event rather than a timed operation.", "OBSERVATION_TYPE_TOOL": "Execution of a tool call.", "OBSERVATION_TYPE_RETRIEVER": "Retrieval of supporting documents or other context.", "OBSERVATION_TYPE_AGENT": "An agent-level operation reported in the trace.", "OBSERVATION_TYPE_CHAIN": "A sequence or chain of related processing steps.", "OBSERVATION_TYPE_EMBEDDING": "Computation of vector embeddings.", "OBSERVATION_TYPE_EVALUATOR": "An evaluator operation that assesses another result.", "OBSERVATION_TYPE_GUARDRAIL": "A guardrail check on inputs, outputs or processing." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "OBSERVATION_TYPE_SPAN", "number": 1, "canonical": true, "description": "A timed unit of work represented as a span." }, { "name": "OBSERVATION_TYPE_GENERATION", "number": 2, "canonical": true, "description": "A model-generation operation and its recorded inputs, outputs and usage." }, { "name": "OBSERVATION_TYPE_EVENT", "number": 3, "canonical": true, "description": "A point-in-time event rather than a timed operation." }, { "name": "OBSERVATION_TYPE_TOOL", "number": 4, "canonical": true, "description": "Execution of a tool call." }, { "name": "OBSERVATION_TYPE_RETRIEVER", "number": 5, "canonical": true, "description": "Retrieval of supporting documents or other context." }, { "name": "OBSERVATION_TYPE_AGENT", "number": 6, "canonical": true, "description": "An agent-level operation reported in the trace." }, { "name": "OBSERVATION_TYPE_CHAIN", "number": 7, "canonical": true, "description": "A sequence or chain of related processing steps." }, { "name": "OBSERVATION_TYPE_EMBEDDING", "number": 8, "canonical": true, "description": "Computation of vector embeddings." }, { "name": "OBSERVATION_TYPE_EVALUATOR", "number": 9, "canonical": true, "description": "An evaluator operation that assesses another result." }, { "name": "OBSERVATION_TYPE_GUARDRAIL", "number": 10, "canonical": true, "description": "A guardrail check on inputs, outputs or processing." } ], "x-enum-description": "Semantic category of a trace observation, including categories accepted from upstream even when\nthe platform does not emit them.", "description": "Observation type used to restrict the evaluation query.", "x-presence": "implicit" }, "level": { "oneOf": [ { "type": "string", "enum": [ "OBSERVATION_LEVEL_DEBUG", "OBSERVATION_LEVEL_DEFAULT", "OBSERVATION_LEVEL_WARNING", "OBSERVATION_LEVEL_ERROR" ], "x-enumDescriptions": { "OBSERVATION_LEVEL_DEBUG": "Detailed diagnostic information intended for debugging.", "OBSERVATION_LEVEL_DEFAULT": "Ordinary observation information without an elevated warning or error level.", "OBSERVATION_LEVEL_WARNING": "A condition reported at warning severity.", "OBSERVATION_LEVEL_ERROR": "A condition reported at error severity." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "OBSERVATION_LEVEL_DEBUG", "number": 1, "canonical": true, "description": "Detailed diagnostic information intended for debugging." }, { "name": "OBSERVATION_LEVEL_DEFAULT", "number": 2, "canonical": true, "description": "Ordinary observation information without an elevated warning or error level." }, { "name": "OBSERVATION_LEVEL_WARNING", "number": 3, "canonical": true, "description": "A condition reported at warning severity." }, { "name": "OBSERVATION_LEVEL_ERROR", "number": 4, "canonical": true, "description": "A condition reported at error severity." } ], "x-enum-description": "Diagnostic severity attached to an evaluation observation.", "description": "Severity level used to restrict evaluation observations or traces.", "x-presence": "implicit" }, "parentObservationId": { "type": "string", "description": "Identifier of the parent observation used to select child observations.", "x-presence": "implicit" }, "userId": { "type": "string", "maxLength": 256, "description": "Identifier of the end user associated with this operation or record.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" }, "name": { "type": "string", "maxLength": 256, "description": "Name used to restrict the evaluation record listing.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" }, "environment": { "type": "string", "maxLength": 256, "description": "Environment label used to select evaluation records.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" }, "fromTime": { "type": "string", "format": "date-time", "description": "Beginning of the time range used to select evaluation records.", "x-presence": "message" }, "toTime": { "type": "string", "format": "date-time", "description": "End of the time range used to select evaluation records.", "x-presence": "message" }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/EvalFilter" }, "description": "Structured filters applied to the evaluation record query.", "x-presence": "collection" }, "cursor": { "type": "string", "maxLength": 4096, "description": "Opaque cursor from the previous response’s cursor_page.next_cursor. Leave empty for the first\npage.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "4096" } }, "x-validation-scope": "request" } } }, "EvalFilter": { "type": "object", "description": "Typed comparison operand and column selector for querying evaluation-provider records.", "properties": { "type": { "oneOf": [ { "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" ], "x-enumDescriptions": { "EVAL_FILTER_TYPE_DATETIME": "Compare a date-time value using ordered comparisons.", "EVAL_FILTER_TYPE_STRING": "Compare text using equality or supported substring and prefix or suffix operators.", "EVAL_FILTER_TYPE_NUMBER": "Compare a numeric value using equality or ordered comparisons.", "EVAL_FILTER_TYPE_STRING_OPTIONS": "Match a string against a set of allowed or excluded choices.", "EVAL_FILTER_TYPE_CATEGORY_OPTIONS": "Match a category against a set of allowed or excluded choices.", "EVAL_FILTER_TYPE_ARRAY_OPTIONS": "Match array contents using any-of, none-of or all-of selection.", "EVAL_FILTER_TYPE_BOOLEAN": "Compare a boolean value for equality or inequality.", "EVAL_FILTER_TYPE_NULL": "Test whether the selected property is null or non-null.", "EVAL_FILTER_TYPE_STRING_OBJECT": "Compare a string-valued member identified by a key, such as a metadata property.", "EVAL_FILTER_TYPE_NUMBER_OBJECT": "Compare a numeric member identified by a key, such as a named score.", "EVAL_FILTER_TYPE_BOOLEAN_OBJECT": "Compare a boolean member identified by a key." } }, { "type": "integer", "format": "int32", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 ], "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "EVAL_FILTER_TYPE_DATETIME", "number": 1, "canonical": true, "description": "Compare a date-time value using ordered comparisons." }, { "name": "EVAL_FILTER_TYPE_STRING", "number": 2, "canonical": true, "description": "Compare text using equality or supported substring and prefix or suffix operators." }, { "name": "EVAL_FILTER_TYPE_NUMBER", "number": 3, "canonical": true, "description": "Compare a numeric value using equality or ordered comparisons." }, { "name": "EVAL_FILTER_TYPE_STRING_OPTIONS", "number": 4, "canonical": true, "description": "Match a string against a set of allowed or excluded choices." }, { "name": "EVAL_FILTER_TYPE_CATEGORY_OPTIONS", "number": 5, "canonical": true, "description": "Match a category against a set of allowed or excluded choices." }, { "name": "EVAL_FILTER_TYPE_ARRAY_OPTIONS", "number": 6, "canonical": true, "description": "Match array contents using any-of, none-of or all-of selection." }, { "name": "EVAL_FILTER_TYPE_BOOLEAN", "number": 7, "canonical": true, "description": "Compare a boolean value for equality or inequality." }, { "name": "EVAL_FILTER_TYPE_NULL", "number": 8, "canonical": true, "description": "Test whether the selected property is null or non-null." }, { "name": "EVAL_FILTER_TYPE_STRING_OBJECT", "number": 9, "canonical": true, "description": "Compare a string-valued member identified by a key, such as a metadata property." }, { "name": "EVAL_FILTER_TYPE_NUMBER_OBJECT", "number": 10, "canonical": true, "description": "Compare a numeric member identified by a key, such as a named score." }, { "name": "EVAL_FILTER_TYPE_BOOLEAN_OBJECT", "number": 11, "canonical": true, "description": "Compare a boolean member identified by a key." } ], "x-enum-description": "Operand shape and comparison vocabulary for an evaluation-record filter.", "description": "Discriminator selecting the evaluation filter’s operand type.", "x-presence": "implicit", "x-protovalidate": { "enum": { "definedOnly": true, "notIn": [ 0 ] } }, "x-validation-scope": "request" }, "column": { "type": "string", "minLength": 1, "description": "Evaluation filter column identifier, for example traceName, scores_avg, metadata or level.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "operator": { "type": "string", "minLength": 1, "description": "Operator accepted for the selected filter type, for example contains, any of or >=.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "key": { "type": "string", "description": "Set only for the *_OBJECT types: the metadata key or score name.", "x-presence": "implicit" }, "stringValue": { "type": "string", "description": "Exactly one value field is meaningful, chosen by type — flat siblings\nrather than a oneof, per repo convention.", "x-presence": "implicit" }, "numberValue": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Numeric operand used by the evaluation filter.", "x-presence": "implicit" }, "booleanValue": { "type": "boolean", "description": "Boolean operand or score value used by the selected evaluation type.", "x-presence": "implicit" }, "stringValues": { "type": "array", "items": { "type": "string" }, "description": "The *_OPTIONS types.", "x-presence": "collection" }, "timeValue": { "type": "string", "format": "date-time", "description": "Timestamp operand used by the evaluation filter.", "x-presence": "message" } }, "x-reference-model": { "title": "EvalFilter", "url": "/api/models/eval-filter#request" }, "x-request-required": [ "type", "column", "operator" ], "required": [ "type", "column", "operator" ] }, "ListObservationsResponse": { "type": "object", "description": "Result of listing observations recorded within evaluation traces.", "properties": { "observations": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" }, "description": "Evaluation observations included in this result page.", "x-presence": "collection" }, "contentRedacted": { "type": "boolean", "description": "Whether sensitive evaluation content has been removed from the returned view.", "x-presence": "implicit" }, "cursorPage": { "description": "Cursor pagination details accompanying this result page.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/CursorPageInfo" } ] } } }, "ListScoreConfigsRequest": { "type": "object", "description": "Inputs for listing definitions and allowed values of evaluation scores.", "properties": { "page": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 2147483647, "description": "Page number requested from the backing service.", "x-presence": "implicit", "x-protovalidate": { "int32": { "gte": 0 } }, "x-validation-scope": "request" }, "pageSize": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100, "description": "Requested maximum number of entries in a result page.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 100, "gte": 0 } }, "x-validation-scope": "request" }, "includeArchived": { "type": "boolean", "description": "Whether archived score configurations are included in the listing. They are excluded when\nthis field is omitted or false.", "x-presence": "implicit" } } }, "ListScoreConfigsResponse": { "type": "object", "description": "Result of listing definitions and allowed values of evaluation scores.", "properties": { "configs": { "type": "array", "items": { "$ref": "#/components/schemas/ScoreConfig" }, "description": "Evaluation score configurations included in this result page.", "x-presence": "collection" }, "page": { "description": "Page number, page size, and result totals returned by the evaluation provider.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/EvaluationPageInfo" } ] } } }, "ScoreConfig": { "type": "object", "description": "Score definition specifying its value type, bounds, and allowed categories.", "properties": { "configId": { "type": "string", "description": "Identifier of the score configuration defining the score’s value domain.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Name identifying the score definition.", "x-presence": "implicit" }, "dataType": { "oneOf": [ { "type": "string", "enum": [ "SCORE_DATA_TYPE_NUMERIC", "SCORE_DATA_TYPE_CATEGORICAL", "SCORE_DATA_TYPE_BOOLEAN", "SCORE_DATA_TYPE_TEXT" ], "x-enumDescriptions": { "SCORE_DATA_TYPE_NUMERIC": "A numeric measurement or rating.", "SCORE_DATA_TYPE_CATEGORICAL": "A value chosen from a named set of categories.", "SCORE_DATA_TYPE_BOOLEAN": "A true-or-false evaluation result.", "SCORE_DATA_TYPE_TEXT": "Free-form text supplied by an evaluator or reviewer." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "SCORE_DATA_TYPE_NUMERIC", "number": 1, "canonical": true, "description": "A numeric measurement or rating." }, { "name": "SCORE_DATA_TYPE_CATEGORICAL", "number": 2, "canonical": true, "description": "A value chosen from a named set of categories." }, { "name": "SCORE_DATA_TYPE_BOOLEAN", "number": 3, "canonical": true, "description": "A true-or-false evaluation result." }, { "name": "SCORE_DATA_TYPE_TEXT", "number": 4, "canonical": true, "description": "Free-form text supplied by an evaluator or reviewer." } ], "x-enum-description": "Data representation of an evaluation score or score configuration.", "description": "Score value type used to interpret the numeric, categorical, or boolean value.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Human-readable description of the resource.", "x-presence": "implicit" }, "minValue": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Minimum numeric score value allowed by the score configuration.", "x-presence": "implicit" }, "maxValue": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Maximum numeric score value allowed by the score configuration.", "x-presence": "implicit" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/ScoreConfigCategory" }, "description": "Named score categories defined by the score configuration.", "x-presence": "collection" }, "isArchived": { "type": "boolean", "description": "Whether the score configuration is archived. Archived configurations are retained so\nhistorical scores remain interpretable.", "x-presence": "implicit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when this record was created.", "x-presence": "message" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time when this record was last updated.", "x-presence": "message" } }, "x-reference-model": { "title": "ScoreConfig", "url": "/api/models/score-config#response" } }, "ScoreConfigCategory": { "type": "object", "description": "Named category and associated numeric value in a categorical score definition.", "properties": { "label": { "type": "string", "description": "Label identifying the prompt version or score category.", "x-presence": "implicit" }, "value": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Numeric score value associated with this named category.", "x-presence": "implicit" } }, "x-reference-model": { "title": "ScoreConfigCategory", "url": "/api/models/score-config-category#response" } }, "ListScoresRequest": { "type": "object", "description": "Inputs for listing scores attached to evaluation objects.", "properties": { "pageSize": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100, "description": "Requested maximum number of entries in a result page.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 100, "gte": 0 } }, "x-validation-scope": "request" }, "targetType": { "oneOf": [ { "type": "string", "enum": [ "EVAL_TARGET_TYPE_TRACE", "EVAL_TARGET_TYPE_OBSERVATION", "EVAL_TARGET_TYPE_DATASET_RUN", "EVAL_TARGET_TYPE_SESSION" ], "x-enumDescriptions": { "EVAL_TARGET_TYPE_TRACE": "A complete trace identified by its trace identifier.", "EVAL_TARGET_TYPE_OBSERVATION": "A specific observation within a trace.", "EVAL_TARGET_TYPE_DATASET_RUN": "An evaluation run over a dataset.", "EVAL_TARGET_TYPE_SESSION": "A session grouping multiple traces; session scores are attached directly by the harness." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "EVAL_TARGET_TYPE_TRACE", "number": 1, "canonical": true, "description": "A complete trace identified by its trace identifier." }, { "name": "EVAL_TARGET_TYPE_OBSERVATION", "number": 2, "canonical": true, "description": "A specific observation within a trace." }, { "name": "EVAL_TARGET_TYPE_DATASET_RUN", "number": 3, "canonical": true, "description": "An evaluation run over a dataset." }, { "name": "EVAL_TARGET_TYPE_SESSION", "number": 4, "canonical": true, "description": "A session grouping multiple traces; session scores are attached directly by the harness." } ], "x-enum-description": "Kind of evaluation object a score or evaluation configuration addresses.", "description": "Kind of evaluation object targeted by the score or annotation.", "x-presence": "implicit" }, "targetId": { "type": "string", "description": "Identifier of the evaluation object targeted by the score or annotation.", "x-presence": "implicit" }, "name": { "type": "string", "maxLength": 256, "description": "Name used to restrict the evaluation record listing.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" }, "source": { "oneOf": [ { "type": "string", "enum": [ "SCORE_SOURCE_JUDGE", "SCORE_SOURCE_HUMAN", "SCORE_SOURCE_USER", "SCORE_SOURCE_HARNESS", "SCORE_SOURCE_EVAL" ], "x-enumDescriptions": { "SCORE_SOURCE_JUDGE": "A score produced by an automated judge.", "SCORE_SOURCE_HUMAN": "A score entered by a human reviewer through the annotation path.", "SCORE_SOURCE_USER": "Feedback supplied by an end user.", "SCORE_SOURCE_HARNESS": "A score written by an evaluation harness or another API-based producer.", "SCORE_SOURCE_EVAL": "A read-only score produced by the evaluation provider's managed evaluators; it cannot be\nwritten through the public score API." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "SCORE_SOURCE_JUDGE", "number": 1, "canonical": true, "description": "A score produced by an automated judge." }, { "name": "SCORE_SOURCE_HUMAN", "number": 2, "canonical": true, "description": "A score entered by a human reviewer through the annotation path." }, { "name": "SCORE_SOURCE_USER", "number": 3, "canonical": true, "description": "Feedback supplied by an end user." }, { "name": "SCORE_SOURCE_HARNESS", "number": 4, "canonical": true, "description": "A score written by an evaluation harness or another API-based producer." }, { "name": "SCORE_SOURCE_EVAL", "number": 5, "canonical": true, "description": "A read-only score produced by the evaluation provider's managed evaluators; it cannot be\nwritten through the public score API." } ], "x-enum-description": "Platform classification of who produced an evaluation score; the provider source label preserves\nits original vocabulary.", "description": "Origin of the evaluation scores selected by this query.", "x-presence": "implicit" }, "fromTime": { "type": "string", "format": "date-time", "description": "Beginning of the time range used to select evaluation records.", "x-presence": "message" }, "toTime": { "type": "string", "format": "date-time", "description": "End of the time range used to select evaluation records.", "x-presence": "message" }, "userId": { "type": "string", "maxLength": 256, "description": "Identifier of the end user associated with this operation or record.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" }, "profileId": { "type": "string", "maxLength": 256, "description": "Identifier of the agent profile associated with the operation or generation.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" }, "minValue": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Lower numeric bound for the score range.", "x-presence": "implicit" }, "maxValue": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Upper numeric bound for the score range.", "x-presence": "implicit" }, "conversationId": { "type": "string", "maxLength": 256, "description": "Identifier of the conversation associated with the evaluation record.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" }, "sessionId": { "type": "string", "maxLength": 256, "description": "Identifier of the evaluation session grouping related traces.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" }, "dataType": { "oneOf": [ { "type": "string", "enum": [ "SCORE_DATA_TYPE_NUMERIC", "SCORE_DATA_TYPE_CATEGORICAL", "SCORE_DATA_TYPE_BOOLEAN", "SCORE_DATA_TYPE_TEXT" ], "x-enumDescriptions": { "SCORE_DATA_TYPE_NUMERIC": "A numeric measurement or rating.", "SCORE_DATA_TYPE_CATEGORICAL": "A value chosen from a named set of categories.", "SCORE_DATA_TYPE_BOOLEAN": "A true-or-false evaluation result.", "SCORE_DATA_TYPE_TEXT": "Free-form text supplied by an evaluator or reviewer." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "SCORE_DATA_TYPE_NUMERIC", "number": 1, "canonical": true, "description": "A numeric measurement or rating." }, { "name": "SCORE_DATA_TYPE_CATEGORICAL", "number": 2, "canonical": true, "description": "A value chosen from a named set of categories." }, { "name": "SCORE_DATA_TYPE_BOOLEAN", "number": 3, "canonical": true, "description": "A true-or-false evaluation result." }, { "name": "SCORE_DATA_TYPE_TEXT", "number": 4, "canonical": true, "description": "Free-form text supplied by an evaluator or reviewer." } ], "x-enum-description": "Data representation of an evaluation score or score configuration.", "description": "Value type used to interpret the evaluation score.", "x-presence": "implicit" }, "traceId": { "type": "string", "description": "Identifier of the evaluation trace.", "x-presence": "implicit" }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/EvalFilter" }, "description": "Structured filters applied to the evaluation record query.", "x-presence": "collection" }, "cursor": { "type": "string", "maxLength": 4096, "description": "Opaque cursor from the previous response’s cursor_page.next_cursor. Leave empty for the first\npage.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "4096" } }, "x-validation-scope": "request" } } }, "ListScoresResponse": { "type": "object", "description": "Result of listing scores attached to evaluation objects.", "properties": { "scores": { "type": "array", "items": { "$ref": "#/components/schemas/Score" }, "description": "Evaluation scores included in this result page.", "x-presence": "collection" }, "filterNarrowed": { "type": "boolean", "description": "Whether additional filtering removed rows from this page. A narrowed page can contain fewer\nthan page_size results while cursor_page.next_cursor still identifies another page.", "x-presence": "implicit" }, "cursorPage": { "description": "Cursor pagination details accompanying this result page.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/CursorPageInfo" } ] } } }, "ListSessionsRequest": { "type": "object", "description": "Inputs for listing evaluation sessions grouping related traces.", "properties": { "pageSize": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100, "description": "Requested maximum number of entries in a result page.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 100, "gte": 0 } }, "x-validation-scope": "request" }, "fromTime": { "type": "string", "format": "date-time", "description": "Beginning of the time range used to select evaluation records.", "x-presence": "message" }, "toTime": { "type": "string", "format": "date-time", "description": "End of the time range used to select evaluation records.", "x-presence": "message" }, "environment": { "type": "string", "maxLength": 256, "description": "Environment label used to select evaluation records.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" }, "userId": { "type": "string", "maxLength": 256, "description": "Identifier of the end user associated with this operation or record.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/EvalFilter" }, "description": "Structured filters applied to the evaluation record query.", "x-presence": "collection" }, "cursor": { "type": "string", "maxLength": 4096, "description": "Opaque cursor from the previous response’s cursor_page.next_cursor. Leave empty for the first\npage.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "4096" } }, "x-validation-scope": "request" } } }, "ListSessionsResponse": { "type": "object", "description": "Result of listing evaluation sessions grouping related traces.", "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/SessionSummary" }, "description": "Evaluation session summaries included in this result page.", "x-presence": "collection" }, "cursorPage": { "description": "Cursor pagination details accompanying this result page.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/CursorPageInfo" } ] } } }, "ListTracesRequest": { "type": "object", "description": "Inputs for listing evaluation trace records.", "properties": { "pageSize": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100, "description": "Requested maximum number of entries in a result page.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 100, "gte": 0 } }, "x-validation-scope": "request" }, "conversationId": { "type": "string", "maxLength": 256, "description": "Identifier of the conversation associated with the evaluation record.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" }, "profileId": { "type": "string", "maxLength": 256, "description": "Identifier of the agent profile associated with the operation or generation.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" }, "userId": { "type": "string", "maxLength": 256, "description": "Identifier of the end user associated with this operation or record.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" }, "sessionId": { "type": "string", "maxLength": 256, "description": "Identifier of the evaluation session grouping related traces.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" }, "name": { "type": "string", "maxLength": 256, "description": "Name used to restrict the evaluation record listing.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" }, "environment": { "type": "string", "maxLength": 256, "description": "Environment label used to select evaluation records.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" }, "version": { "type": "string", "maxLength": 256, "description": "Version label used to select evaluation records.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" }, "release": { "type": "string", "maxLength": 256, "description": "Application release label attached to evaluation records.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags used to classify or filter the evaluation record.", "x-presence": "collection" }, "fromTime": { "type": "string", "format": "date-time", "description": "Beginning of the time range used to select evaluation records.", "x-presence": "message" }, "toTime": { "type": "string", "format": "date-time", "description": "End of the time range used to select evaluation records.", "x-presence": "message" }, "level": { "oneOf": [ { "type": "string", "enum": [ "OBSERVATION_LEVEL_DEBUG", "OBSERVATION_LEVEL_DEFAULT", "OBSERVATION_LEVEL_WARNING", "OBSERVATION_LEVEL_ERROR" ], "x-enumDescriptions": { "OBSERVATION_LEVEL_DEBUG": "Detailed diagnostic information intended for debugging.", "OBSERVATION_LEVEL_DEFAULT": "Ordinary observation information without an elevated warning or error level.", "OBSERVATION_LEVEL_WARNING": "A condition reported at warning severity.", "OBSERVATION_LEVEL_ERROR": "A condition reported at error severity." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "OBSERVATION_LEVEL_DEBUG", "number": 1, "canonical": true, "description": "Detailed diagnostic information intended for debugging." }, { "name": "OBSERVATION_LEVEL_DEFAULT", "number": 2, "canonical": true, "description": "Ordinary observation information without an elevated warning or error level." }, { "name": "OBSERVATION_LEVEL_WARNING", "number": 3, "canonical": true, "description": "A condition reported at warning severity." }, { "name": "OBSERVATION_LEVEL_ERROR", "number": 4, "canonical": true, "description": "A condition reported at error severity." } ], "x-enum-description": "Diagnostic severity attached to an evaluation observation.", "description": "Severity level used to restrict evaluation observations or traces.", "x-presence": "implicit" }, "orderBy": { "type": "string", "maxLength": 64, "description": "Ordering expression passed to the evaluation record query.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "64" } }, "x-validation-scope": "request" }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/EvalFilter" }, "description": "Structured filters applied to the evaluation record query.", "x-presence": "collection" }, "searchQuery": { "type": "string", "maxLength": 512, "description": "Text searched within evaluation trace records.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "512" } }, "x-validation-scope": "request" }, "searchType": { "type": "string", "maxLength": 32, "description": "Search mode applied to the evaluation trace query.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "32" } }, "x-validation-scope": "request" }, "cursor": { "type": "string", "maxLength": 4096, "description": "Opaque cursor from the previous response’s cursor_page.next_cursor. Leave empty for the first\npage.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "4096" } }, "x-validation-scope": "request" } } }, "ListTracesResponse": { "type": "object", "description": "Result of listing evaluation trace records.", "properties": { "traces": { "type": "array", "items": { "$ref": "#/components/schemas/TraceSummary" }, "description": "Evaluation trace summaries included in this result page.", "x-presence": "collection" }, "contentRedacted": { "type": "boolean", "description": "Whether returned trace content is redacted. Redaction occurs before the trace is recorded, so\nits text is not a faithful copy of the conversation store.", "x-presence": "implicit" }, "cursorPage": { "description": "Cursor pagination details accompanying this result page.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/CursorPageInfo" } ] } } }, "RecordDatasetRunRequest": { "type": "object", "description": "Records a dataset run. This is the RPC that motivated a public eval surface:\na harness executes a run and has to be able to post it, and until now the\nonly route in was the console's own admin edge.", "properties": { "datasetId": { "type": "string", "minLength": 1, "description": "Identifier of the evaluation dataset.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "runName": { "type": "string", "minLength": 1, "description": "Name assigned to the evaluation dataset run.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "profileRevisionHash": { "type": "string", "description": "Content hash identifying the agent profile revision recorded for the dataset run.", "x-presence": "implicit" }, "metadataJson": { "type": "string", "description": "Additional evaluation metadata serialized as JSON text.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Human-readable explanation of the evaluation record.", "x-presence": "implicit" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetRunItem" }, "minItems": 1, "description": "Dataset-item and generated-trace pairs included in the run.", "x-presence": "collection", "x-protovalidate": { "repeated": { "minItems": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "datasetId", "runName", "items" ], "required": [ "datasetId", "runName", "items" ] }, "DatasetRunItem": { "type": "object", "description": "One item of a dataset run: which dataset item was executed, and the trace it\nproduced.", "properties": { "datasetItemId": { "type": "string", "minLength": 1, "description": "Identifier of the dataset item used by this evaluation run.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "traceId": { "type": "string", "minLength": 1, "description": "Identifier of the evaluation trace.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "observationId": { "type": "string", "description": "Optional: pin the run to one observation inside the trace rather than the\nwhole turn, for a harness that scores a single generation.", "x-presence": "implicit" } }, "x-reference-model": { "title": "DatasetRunItem", "url": "/api/models/dataset-run-item#request" }, "x-request-required": [ "datasetItemId", "traceId" ], "required": [ "datasetItemId", "traceId" ] }, "RecordDatasetRunResponse": { "type": "object", "description": "Result of recording a named run against an evaluation dataset.", "properties": { "runId": { "type": "string", "description": "Identifier of the recorded evaluation dataset run.", "x-presence": "implicit" } } }, "RecordScoreRequest": { "type": "object", "description": "Inputs for recording an evaluation score. Supply exactly one target address: target_id,\nmessage_id, or both conversation_id and source_user_message_id. Authorship comes from the\nauthenticated caller; the score source is assigned for this reviewer operation.", "properties": { "targetType": { "oneOf": [ { "type": "string", "enum": [ "EVAL_TARGET_TYPE_TRACE", "EVAL_TARGET_TYPE_OBSERVATION", "EVAL_TARGET_TYPE_DATASET_RUN", "EVAL_TARGET_TYPE_SESSION" ], "x-enumDescriptions": { "EVAL_TARGET_TYPE_TRACE": "A complete trace identified by its trace identifier.", "EVAL_TARGET_TYPE_OBSERVATION": "A specific observation within a trace.", "EVAL_TARGET_TYPE_DATASET_RUN": "An evaluation run over a dataset.", "EVAL_TARGET_TYPE_SESSION": "A session grouping multiple traces; session scores are attached directly by the harness." } }, { "type": "integer", "format": "int32", "enum": [ 1, 2, 3, 4 ], "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "EVAL_TARGET_TYPE_TRACE", "number": 1, "canonical": true, "description": "A complete trace identified by its trace identifier." }, { "name": "EVAL_TARGET_TYPE_OBSERVATION", "number": 2, "canonical": true, "description": "A specific observation within a trace." }, { "name": "EVAL_TARGET_TYPE_DATASET_RUN", "number": 3, "canonical": true, "description": "An evaluation run over a dataset." }, { "name": "EVAL_TARGET_TYPE_SESSION", "number": 4, "canonical": true, "description": "A session grouping multiple traces; session scores are attached directly by the harness." } ], "x-enum-description": "Kind of evaluation object a score or evaluation configuration addresses.", "description": "Kind of evaluation object targeted by the score or annotation.", "x-presence": "implicit", "x-protovalidate": { "enum": { "definedOnly": true, "notIn": [ 0 ] } }, "x-validation-scope": "request" }, "targetId": { "type": "string", "description": "Not required — a caller may address by message or by turn instead.", "x-presence": "implicit" }, "name": { "type": "string", "minLength": 1, "description": "Name identifying the scoring dimension recorded for the evaluation target.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "dataType": { "oneOf": [ { "type": "string", "enum": [ "SCORE_DATA_TYPE_NUMERIC", "SCORE_DATA_TYPE_CATEGORICAL", "SCORE_DATA_TYPE_BOOLEAN", "SCORE_DATA_TYPE_TEXT" ], "x-enumDescriptions": { "SCORE_DATA_TYPE_NUMERIC": "A numeric measurement or rating.", "SCORE_DATA_TYPE_CATEGORICAL": "A value chosen from a named set of categories.", "SCORE_DATA_TYPE_BOOLEAN": "A true-or-false evaluation result.", "SCORE_DATA_TYPE_TEXT": "Free-form text supplied by an evaluator or reviewer." } }, { "type": "integer", "format": "int32", "enum": [ 1, 2, 3, 4 ], "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "SCORE_DATA_TYPE_NUMERIC", "number": 1, "canonical": true, "description": "A numeric measurement or rating." }, { "name": "SCORE_DATA_TYPE_CATEGORICAL", "number": 2, "canonical": true, "description": "A value chosen from a named set of categories." }, { "name": "SCORE_DATA_TYPE_BOOLEAN", "number": 3, "canonical": true, "description": "A true-or-false evaluation result." }, { "name": "SCORE_DATA_TYPE_TEXT", "number": 4, "canonical": true, "description": "Free-form text supplied by an evaluator or reviewer." } ], "x-enum-description": "Data representation of an evaluation score or score configuration.", "description": "Value type used to interpret the evaluation score.", "x-presence": "implicit", "x-protovalidate": { "enum": { "definedOnly": true, "notIn": [ 0 ] } }, "x-validation-scope": "request" }, "numericValue": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Numeric score value for a numeric score configuration.", "x-presence": "implicit" }, "stringValue": { "type": "string", "description": "Category value for a categorical evaluation score.", "x-presence": "implicit" }, "booleanValue": { "type": "boolean", "description": "Boolean value for a boolean evaluation score.", "x-presence": "implicit" }, "textValue": { "type": "string", "description": "Free-text value for a text evaluation score.", "x-presence": "implicit" }, "comment": { "type": "string", "description": "Explanatory note accompanying the evaluation score.", "x-presence": "implicit" }, "configId": { "type": "string", "description": "Score configuration selected from ListScoreConfigs. Required for this reviewer operation;\na missing configuration is rejected.", "x-presence": "implicit" }, "profileId": { "type": "string", "description": "Identifier of the agent profile associated with the operation or generation.", "x-presence": "implicit" }, "messageId": { "type": "string", "maxLength": 256, "description": "Identifier of the conversation message to score. Supply this instead of target_id or a\nconversation_id and source_user_message_id pair.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" }, "conversationId": { "type": "string", "maxLength": 256, "description": "Identifier of the conversation associated with the evaluation record.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" }, "sourceUserMessageId": { "type": "string", "maxLength": 256, "description": "Identifier of the user message that originated the evaluated generation.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" } }, "x-protovalidate": { "cel": [ { "id": "exactly_one_score_target", "message": "exactly one of target_id, message_id, or (conversation_id + source_user_message_id) must be set", "expression": "[this.target_id != '', this.message_id != '', this.conversation_id != '' && this.source_user_message_id != ''].filter(f, f).size() == 1" } ] }, "x-validation-scope": "request", "x-request-required": [ "targetType", "name", "dataType" ], "required": [ "targetType", "name", "dataType" ] }, "RecordScoreResponse": { "type": "object", "description": "Result of recording a score attached to an evaluation object.", "properties": { "scoreId": { "type": "string", "description": "Identifier of the recorded evaluation score.", "x-presence": "implicit" }, "targetId": { "type": "string", "description": "Resolved evaluation-object identifier, returned so a caller that addressed a message can use\nthe object identity in later requests.", "x-presence": "implicit" }, "targetType": { "oneOf": [ { "type": "string", "enum": [ "EVAL_TARGET_TYPE_TRACE", "EVAL_TARGET_TYPE_OBSERVATION", "EVAL_TARGET_TYPE_DATASET_RUN", "EVAL_TARGET_TYPE_SESSION" ], "x-enumDescriptions": { "EVAL_TARGET_TYPE_TRACE": "A complete trace identified by its trace identifier.", "EVAL_TARGET_TYPE_OBSERVATION": "A specific observation within a trace.", "EVAL_TARGET_TYPE_DATASET_RUN": "An evaluation run over a dataset.", "EVAL_TARGET_TYPE_SESSION": "A session grouping multiple traces; session scores are attached directly by the harness." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "EVAL_TARGET_TYPE_TRACE", "number": 1, "canonical": true, "description": "A complete trace identified by its trace identifier." }, { "name": "EVAL_TARGET_TYPE_OBSERVATION", "number": 2, "canonical": true, "description": "A specific observation within a trace." }, { "name": "EVAL_TARGET_TYPE_DATASET_RUN", "number": 3, "canonical": true, "description": "An evaluation run over a dataset." }, { "name": "EVAL_TARGET_TYPE_SESSION", "number": 4, "canonical": true, "description": "A session grouping multiple traces; session scores are attached directly by the harness." } ], "x-enum-description": "Kind of evaluation object a score or evaluation configuration addresses.", "description": "Kind of evaluation object targeted by the score or annotation.", "x-presence": "implicit" } } }, "UpdateDatasetItemRequest": { "type": "object", "description": "Inputs for updating an input and expected-output pair in an evaluation dataset.", "properties": { "itemId": { "type": "string", "minLength": 1, "description": "Identifier of the dataset item or annotation queue item being addressed.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "datasetId": { "type": "string", "minLength": 1, "description": "Identifier of the evaluation dataset.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "inputJson": { "type": "string", "description": "Dataset item input serialized as JSON text.", "x-presence": "implicit" }, "expectedOutputJson": { "type": "string", "description": "Expected dataset item output serialized as JSON text.", "x-presence": "implicit" }, "metadataJson": { "type": "string", "description": "Additional evaluation metadata serialized as JSON text.", "x-presence": "implicit" }, "status": { "oneOf": [ { "type": "string", "enum": [ "DATASET_ITEM_STATUS_ACTIVE", "DATASET_ITEM_STATUS_ARCHIVED" ], "x-enumDescriptions": { "DATASET_ITEM_STATUS_ACTIVE": "The dataset item is active.", "DATASET_ITEM_STATUS_ARCHIVED": "The dataset item is archived and retained as historical content." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "DATASET_ITEM_STATUS_ACTIVE", "number": 1, "canonical": true, "description": "The dataset item is active." }, { "name": "DATASET_ITEM_STATUS_ARCHIVED", "number": 2, "canonical": true, "description": "The dataset item is archived and retained as historical content." } ], "x-enum-description": "Whether a dataset item is active or retained as archived content.", "description": "Whether the evaluation dataset item is active or archived.", "x-presence": "implicit" } }, "x-request-required": [ "itemId", "datasetId" ], "required": [ "itemId", "datasetId" ] }, "UpdateDatasetItemResponse": { "type": "object", "description": "Result of updating an input and expected-output pair in an evaluation dataset.", "properties": { "itemId": { "type": "string", "description": "Identifier of the dataset item or annotation queue item being addressed.", "x-presence": "implicit" } } }, "UpdateScoreConfigRequest": { "type": "object", "description": "Partial update of a score configuration. Unset fields retain their values; is_archived changes\narchival state. The score data type and categories cannot be changed through this request.", "properties": { "configId": { "type": "string", "minLength": 1, "description": "Identifier of the evaluation score configuration.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "name": { "type": "string", "minLength": 1, "description": "Name assigned to, or used to filter, the evaluation record.", "x-presence": "explicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "description": { "type": "string", "description": "Human-readable explanation of the evaluation record.", "x-presence": "explicit" }, "minValue": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Lower numeric bound for the score range.", "x-presence": "explicit" }, "maxValue": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Upper numeric bound for the score range.", "x-presence": "explicit" }, "isArchived": { "type": "boolean", "description": "Whether the score configuration is marked as archived.", "x-presence": "explicit" } }, "x-request-required": [ "configId" ], "required": [ "configId" ] }, "UpdateScoreConfigResponse": { "type": "object", "description": "Result of updating the definition and allowed values of an evaluation score.", "properties": { "config": { "description": "Score configuration returned after the update.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ScoreConfig" } ] } } }, "CreateCustomMCPServerRequest": { "type": "object", "description": "Inputs for registering a tenant-owned MCP server and its connection configuration.", "properties": { "projectId": { "type": "string", "description": "Empty → \"default\"", "x-presence": "implicit" }, "server": { "description": "MCP server record supplied to or returned by the operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/CustomMCPServerInput" } ], "x-protovalidate": { "required": true }, "x-validation-scope": "request" } }, "x-request-required": [ "server" ], "required": [ "server" ] }, "CustomMCPServerInput": { "type": "object", "description": "A project-scoped, HTTP-only MCP server definition, keyed\n(tenant_id, project_id, server_id). Its wire ID is \"custom:{server_id}\".\n\nauth_type selects the required credential fields. Authenticated modes require auth_secret_ref;\nNONE requires it to be empty. HEADER requires auth_header_name and QUERY requires auth_query_param;\nthose names must be empty for every other mode. Inconsistent combinations are rejected before\nstorage. Inline credentials are not accepted.", "properties": { "serverId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,62}$", "description": "Unique within the project.", "x-presence": "implicit", "x-protovalidate": { "string": { "pattern": "^[a-z0-9][a-z0-9-]{0,62}$" } }, "x-validation-scope": "request" }, "displayName": { "type": "string", "maxLength": 200, "description": "Display name used for the registered MCP server.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "200" } }, "x-validation-scope": "request" }, "description": { "type": "string", "maxLength": 1024, "description": "Human-readable description of the resource.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "1024" } }, "x-validation-scope": "request" }, "endpoint": { "type": "string", "maxLength": 2048, "pattern": "^https://", "format": "uri", "description": "HTTPS endpoint for Streamable HTTP; local and standard-input/output transports are unsupported.\nThe egress guard also rejects prohibited destinations such as metadata, loopback, private-network\nand in-cluster addresses. HTTPS alone does not satisfy these destination checks.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "2048", "pattern": "^https://", "uri": true } }, "x-validation-scope": "request" }, "authType": { "oneOf": [ { "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" ], "x-enumDescriptions": { "CUSTOM_MCP_SERVER_AUTH_TYPE_NONE": "Send requests without attaching a secret for authentication.", "CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER": "Send the secret as a Bearer token in the Authorization header.", "CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER": "Send the secret in the configured custom header.", "CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY": "Add the secret as the configured URL query parameter when connecting; the stored endpoint\nremains the base URL." } }, { "type": "integer", "format": "int32", "enum": [ 1, 2, 3, 4 ], "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "CUSTOM_MCP_SERVER_AUTH_TYPE_NONE", "number": 1, "canonical": true, "description": "Send requests without attaching a secret for authentication." }, { "name": "CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER", "number": 2, "canonical": true, "description": "Send the secret as a Bearer token in the Authorization header." }, { "name": "CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER", "number": 3, "canonical": true, "description": "Send the secret in the configured custom header." }, { "name": "CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY", "number": 4, "canonical": true, "description": "Add the secret as the configured URL query parameter when connecting; the stored endpoint\nremains the base URL." } ], "x-enum-description": "How credentials are attached to requests to a tenant-configured MCP server.", "description": "Authentication mechanism configured for the MCP server.", "x-presence": "implicit", "x-protovalidate": { "enum": { "definedOnly": true } }, "x-validation-scope": "request" }, "authSecretRef": { "description": "Required credential reference for BEARER, HEADER and QUERY authentication. Resolves within\nthis server's tenant and project; only the secret name is returned, never its value.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/SecretRefInput" } ] }, "authHeaderName": { "type": "string", "pattern": "^([A-Za-z0-9!#$%&'*+.^_`|~-]{1,128})?$", "description": "Name of the custom authentication header. The egress guard also rejects protected header\nnames; satisfying the field's character pattern alone does not permit every header.", "x-presence": "implicit", "x-protovalidate": { "string": { "pattern": "^([A-Za-z0-9!#$%&'*+.^_`|~-]{1,128})?$" } }, "x-validation-scope": "request" }, "enabled": { "type": "boolean", "description": "Whether this configuration is enabled.", "x-presence": "implicit" }, "requestTimeout": { "type": "string", "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]{1,9})?s$", "description": "Time allowed for a remote request. Omission or a nonpositive duration uses 30 seconds;\npositive durations below one second are raised to one second. Long waits can delay the\nconversation while the remote server is unavailable.", "x-presence": "message", "x-protovalidate": { "duration": { "lte": "120s" } }, "x-validation-scope": "request" }, "version": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Output-only revision assigned by the store and incremented on updates. Ignored on writes.", "x-presence": "implicit" }, "createdBy": { "type": "string", "description": "Output-only identity of the caller that registered the server. Ignored on writes.", "x-presence": "implicit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Output-only creation time assigned by the store. Ignored on writes.", "x-presence": "message" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Output-only last-update time assigned by the store. Ignored on writes.", "x-presence": "message" }, "authQueryParam": { "type": "string", "pattern": "^([A-Za-z0-9._~-]{1,128})?$", "description": "Required for QUERY auth; the vendor's parameter name (e.g. \"tavilyApiKey\").\n\nEmpty is allowed — populated only for QUERY auth.", "x-presence": "implicit", "x-protovalidate": { "string": { "pattern": "^([A-Za-z0-9._~-]{1,128})?$" } }, "x-validation-scope": "request" } }, "x-reference-model": { "title": "CustomMCPServer", "url": "/api/models/custom-mcp-server#request" }, "x-request-required": [ "serverId", "endpoint" ], "required": [ "serverId", "endpoint" ] }, "SecretRefInput": { "type": "object", "description": "Reference to a secret within the same tenant and project as the resource that uses it.\nCross-project and cross-tenant secret references are not supported.", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,62}$", "description": "Name identifying the secret within its project.", "x-presence": "implicit", "x-protovalidate": { "string": { "pattern": "^[a-z0-9][a-z0-9._-]{0,62}$" } }, "x-validation-scope": "request" } }, "x-reference-model": { "title": "SecretRef", "url": "/api/models/secret-ref#request" }, "x-request-required": [ "name" ], "required": [ "name" ] }, "CreateCustomMCPServerResponse": { "type": "object", "description": "Result payload for registering a tenant-owned MCP server and its connection configuration.", "properties": { "server": { "description": "MCP server record supplied to or returned by the operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/CustomMCPServer" } ] } } }, "CustomMCPServer": { "type": "object", "description": "A project-scoped, HTTP-only MCP server definition, keyed\n(tenant_id, project_id, server_id). Its wire ID is \"custom:{server_id}\".\n\nauth_type selects the required credential fields. Authenticated modes require auth_secret_ref;\nNONE requires it to be empty. HEADER requires auth_header_name and QUERY requires auth_query_param;\nthose names must be empty for every other mode. Inconsistent combinations are rejected before\nstorage. Inline credentials are not accepted.", "properties": { "serverId": { "type": "string", "description": "Unique within the project.", "x-presence": "implicit", "x-protovalidate": { "string": { "pattern": "^[a-z0-9][a-z0-9-]{0,62}$" } }, "x-validation-scope": "request" }, "displayName": { "type": "string", "description": "Display name used for the registered MCP server.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "200" } }, "x-validation-scope": "request" }, "description": { "type": "string", "description": "Human-readable description of the resource.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "1024" } }, "x-validation-scope": "request" }, "endpoint": { "type": "string", "description": "HTTPS endpoint for Streamable HTTP; local and standard-input/output transports are unsupported.\nThe egress guard also rejects prohibited destinations such as metadata, loopback, private-network\nand in-cluster addresses. HTTPS alone does not satisfy these destination checks.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "2048", "pattern": "^https://", "uri": true } }, "x-validation-scope": "request" }, "authType": { "oneOf": [ { "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" ], "x-enumDescriptions": { "CUSTOM_MCP_SERVER_AUTH_TYPE_NONE": "Send requests without attaching a secret for authentication.", "CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER": "Send the secret as a Bearer token in the Authorization header.", "CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER": "Send the secret in the configured custom header.", "CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY": "Add the secret as the configured URL query parameter when connecting; the stored endpoint\nremains the base URL." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "CUSTOM_MCP_SERVER_AUTH_TYPE_NONE", "number": 1, "canonical": true, "description": "Send requests without attaching a secret for authentication." }, { "name": "CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER", "number": 2, "canonical": true, "description": "Send the secret as a Bearer token in the Authorization header." }, { "name": "CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER", "number": 3, "canonical": true, "description": "Send the secret in the configured custom header." }, { "name": "CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY", "number": 4, "canonical": true, "description": "Add the secret as the configured URL query parameter when connecting; the stored endpoint\nremains the base URL." } ], "x-enum-description": "How credentials are attached to requests to a tenant-configured MCP server.", "description": "Authentication mechanism configured for the MCP server.", "x-presence": "implicit", "x-protovalidate": { "enum": { "definedOnly": true } }, "x-validation-scope": "request" }, "authSecretRef": { "description": "Required credential reference for BEARER, HEADER and QUERY authentication. Resolves within\nthis server's tenant and project; only the secret name is returned, never its value.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/SecretRef" } ] }, "authHeaderName": { "type": "string", "description": "Name of the custom authentication header. The egress guard also rejects protected header\nnames; satisfying the field's character pattern alone does not permit every header.", "x-presence": "implicit", "x-protovalidate": { "string": { "pattern": "^([A-Za-z0-9!#$%&'*+.^_`|~-]{1,128})?$" } }, "x-validation-scope": "request" }, "enabled": { "type": "boolean", "description": "Whether this configuration is enabled.", "x-presence": "implicit" }, "requestTimeout": { "type": "string", "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]{1,9})?s$", "description": "Time allowed for a remote request. Omission or a nonpositive duration uses 30 seconds;\npositive durations below one second are raised to one second. Long waits can delay the\nconversation while the remote server is unavailable.", "x-presence": "message", "x-protovalidate": { "duration": { "lte": "120s" } }, "x-validation-scope": "request" }, "version": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Output-only revision assigned by the store and incremented on updates. Ignored on writes.", "x-presence": "implicit" }, "createdBy": { "type": "string", "description": "Output-only identity of the caller that registered the server. Ignored on writes.", "x-presence": "implicit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Output-only creation time assigned by the store. Ignored on writes.", "x-presence": "message" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Output-only last-update time assigned by the store. Ignored on writes.", "x-presence": "message" }, "authQueryParam": { "type": "string", "description": "Required for QUERY auth; the vendor's parameter name (e.g. \"tavilyApiKey\").\n\nEmpty is allowed — populated only for QUERY auth.", "x-presence": "implicit", "x-protovalidate": { "string": { "pattern": "^([A-Za-z0-9._~-]{1,128})?$" } }, "x-validation-scope": "request" } }, "x-reference-model": { "title": "CustomMCPServer", "url": "/api/models/custom-mcp-server#response" }, "x-request-required": [ "serverId", "endpoint" ] }, "SecretRef": { "type": "object", "description": "Reference to a secret within the same tenant and project as the resource that uses it.\nCross-project and cross-tenant secret references are not supported.", "properties": { "name": { "type": "string", "description": "Name identifying the secret within its project.", "x-presence": "implicit", "x-protovalidate": { "string": { "pattern": "^[a-z0-9][a-z0-9._-]{0,62}$" } }, "x-validation-scope": "request" } }, "x-reference-model": { "title": "SecretRef", "url": "/api/models/secret-ref#response" }, "x-request-required": [ "name" ] }, "GetCustomMCPServerRequest": { "type": "object", "description": "Inputs for reading a tenant-owned MCP server registration.", "properties": { "projectId": { "type": "string", "description": "Identifier of the project associated with the operation.", "x-presence": "implicit" }, "serverId": { "type": "string", "minLength": 1, "description": "Identifier of the MCP server associated with the operation or tool.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "serverId" ], "required": [ "serverId" ] }, "GetCustomMCPServerResponse": { "type": "object", "description": "Result payload for reading a tenant-owned MCP server registration.", "properties": { "server": { "description": "MCP server record supplied to or returned by the operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/CustomMCPServer" } ] } } }, "ListCustomMCPServersRequest": { "type": "object", "description": "Inputs for listing MCP server registrations belonging to the tenant.", "properties": { "projectId": { "type": "string", "description": "Identifier of the project associated with the operation.", "x-presence": "implicit" }, "authSecretNameFilter": { "type": "string", "description": "When set, return only MCP servers whose auth_secret_ref names this secret.", "x-presence": "implicit" }, "includeDisabled": { "type": "boolean", "description": "Default false → only enabled servers.", "x-presence": "implicit" } } }, "ListCustomMCPServersResponse": { "type": "object", "description": "Result payload for listing MCP server registrations belonging to the tenant.", "properties": { "servers": { "type": "array", "items": { "$ref": "#/components/schemas/CustomMCPServer" }, "description": "MCP server configurations or statuses returned by the operation.", "x-presence": "collection" }, "total": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Total number of entries reported by the listing.", "x-presence": "implicit" } } }, "UpdateCustomMCPServerRequest": { "type": "object", "description": "Inputs for changing a tenant-owned MCP server’s connection configuration.", "properties": { "projectId": { "type": "string", "description": "Identifier of the project associated with the operation.", "x-presence": "implicit" }, "serverId": { "type": "string", "minLength": 1, "description": "Identifier of the MCP server associated with the operation or tool.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "server": { "description": "MCP server record supplied to or returned by the operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/CustomMCPServerInput" } ], "x-protovalidate": { "required": true }, "x-validation-scope": "request" } }, "x-request-required": [ "serverId", "server" ], "required": [ "serverId", "server" ] }, "UpdateCustomMCPServerResponse": { "type": "object", "description": "Result payload for changing a tenant-owned MCP server’s connection configuration.", "properties": { "server": { "description": "MCP server record supplied to or returned by the operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/CustomMCPServer" } ] } } }, "DeleteCustomMCPServerRequest": { "type": "object", "description": "Inputs for removing a tenant-owned MCP server registration.", "properties": { "projectId": { "type": "string", "description": "Identifier of the project associated with the operation.", "x-presence": "implicit" }, "serverId": { "type": "string", "minLength": 1, "description": "Identifier of the MCP server associated with the operation or tool.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "serverId" ], "required": [ "serverId" ] }, "DeleteCustomMCPServerResponse": { "type": "object", "description": "Result payload for removing a tenant-owned MCP server registration.", "properties": { "deleted": { "type": "boolean", "description": "False when the server did not exist; the call still succeeds.", "x-presence": "implicit" } } }, "TestCustomMCPServerConnectionRequest": { "type": "object", "description": "Inputs for testing connectivity and tool discovery for a tenant-owned MCP server.", "properties": { "projectId": { "type": "string", "description": "Identifier of the project associated with the operation.", "x-presence": "implicit" }, "serverId": { "type": "string", "minLength": 1, "description": "Identifier of the MCP server associated with the operation or tool.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "serverId" ], "required": [ "serverId" ] }, "TestCustomMCPServerConnectionResponse": { "type": "object", "description": "Result payload for testing connectivity and tool discovery for a tenant-owned MCP server.", "properties": { "success": { "type": "boolean", "description": "Whether the operation reports a successful result.", "x-presence": "implicit" }, "toolCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of tools reported by the MCP server.", "x-presence": "implicit" }, "latencyMs": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Measured MCP connection-test latency, in milliseconds.", "x-presence": "implicit" }, "error": { "type": "string", "description": "Sanitized failure reason. Never contains the resolved credential, the auth\nheader, or internal path details.", "x-presence": "implicit" } } }, "RegisterPushDeviceRequest": { "type": "object", "description": "Caller user_id derived from auth headers by gateway.", "properties": { "fcmToken": { "type": "string", "minLength": 1, "description": "Firebase Cloud Messaging token identifying the push delivery target.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "platform": { "oneOf": [ { "type": "string", "enum": [ "PLATFORM_IOS", "PLATFORM_ANDROID", "PLATFORM_WEB" ], "x-enumDescriptions": { "PLATFORM_IOS": "An Apple iOS device registration.", "PLATFORM_ANDROID": "An Android device registration.", "PLATFORM_WEB": "A web-browser push registration." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "PLATFORM_IOS", "number": 1, "canonical": true, "description": "An Apple iOS device registration." }, { "name": "PLATFORM_ANDROID", "number": 2, "canonical": true, "description": "An Android device registration." }, { "name": "PLATFORM_WEB", "number": 3, "canonical": true, "description": "A web-browser push registration." } ], "x-enum-description": "Client platform associated with a push-notification device registration.", "description": "Device platform associated with the registered push token.", "x-presence": "implicit" }, "deviceId": { "type": "string", "description": "Client-provided identifier of the device being registered.", "x-presence": "implicit" } }, "x-request-required": [ "fcmToken" ], "required": [ "fcmToken" ] }, "RegisterPushDeviceResponse": { "type": "object", "description": "Result payload for registering an FCM token as a user’s push notification delivery target.", "properties": { "success": { "type": "boolean", "description": "Whether the operation reports a successful result.", "x-presence": "implicit" }, "subscriberId": { "type": "string", "description": "Identifier of the notification subscriber.", "x-presence": "implicit" } } }, "UnregisterPushDeviceRequest": { "type": "object", "description": "Caller user_id derived from auth headers by gateway.", "properties": { "fcmToken": { "type": "string", "minLength": 1, "description": "Firebase Cloud Messaging token identifying the push delivery target.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "fcmToken" ], "required": [ "fcmToken" ] }, "UnregisterPushDeviceResponse": { "type": "object", "description": "Result payload for removing an FCM token from the user’s registered push delivery targets.", "properties": { "subscriberId": { "type": "string", "description": "Identifier of the notification subscriber.", "x-presence": "implicit" }, "remainingCredentialCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of push credentials remaining after unregistering the device.", "x-presence": "implicit" } } }, "GetRegisteredChannelsRequest": { "type": "object", "description": "Caller user_id derived from auth headers by gateway.", "properties": {} }, "GetRegisteredChannelsResponse": { "type": "object", "description": "Result payload for reading the notification channels with registered delivery credentials.", "properties": { "channels": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelRegistration" }, "description": "Registration status and credential counts for the subscriber’s delivery channels.", "x-presence": "collection" } } }, "ChannelRegistration": { "type": "object", "description": "Registration state and credential count for one notification channel.", "properties": { "channel": { "oneOf": [ { "type": "string", "enum": [ "CHANNEL_PUSH", "CHANNEL_IN_APP", "CHANNEL_EMAIL", "CHANNEL_SMS", "CHANNEL_CHAT" ], "x-enumDescriptions": { "CHANNEL_PUSH": "Deliver a device push notification through the configured push provider.", "CHANNEL_IN_APP": "Deliver the notification to the in-app inbox.", "CHANNEL_EMAIL": "Send a one-way email notification through the configured email provider.", "CHANNEL_SMS": "Send a one-way SMS notification, such as an alert or authentication message.", "CHANNEL_CHAT": "Send a one-way message to an integrated chat destination." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "CHANNEL_PUSH", "number": 1, "canonical": true, "description": "Deliver a device push notification through the configured push provider." }, { "name": "CHANNEL_IN_APP", "number": 2, "canonical": true, "description": "Deliver the notification to the in-app inbox." }, { "name": "CHANNEL_EMAIL", "number": 3, "canonical": true, "description": "Send a one-way email notification through the configured email provider." }, { "name": "CHANNEL_SMS", "number": 4, "canonical": true, "description": "Send a one-way SMS notification, such as an alert or authentication message." }, { "name": "CHANNEL_CHAT", "number": 5, "canonical": true, "description": "Send a one-way message to an integrated chat destination." } ], "x-enum-description": "Delivery channel requested or reported for a notification.", "description": "Notification channel represented by this registration.", "x-presence": "implicit" }, "registered": { "type": "boolean", "description": "Whether the subscriber has a registration for this channel.", "x-presence": "implicit" }, "credentialCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of delivery credentials registered for the channel.", "x-presence": "implicit" } }, "x-reference-model": { "title": "ChannelRegistration", "url": "/api/models/channel-registration#response" } }, "GetInboxSessionRequest": { "type": "object", "description": "Caller user_id derived from auth headers by gateway.", "properties": {} }, "GetInboxSessionResponse": { "type": "object", "description": "Result payload for issuing connection details for a subscriber’s inbox session.", "properties": { "token": { "type": "string", "description": "Token issued for the subscriber’s inbox session.", "x-presence": "implicit" }, "socketUrl": { "type": "string", "description": "WebSocket endpoint provided for the inbox session.", "x-presence": "implicit" }, "expiresIn": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Remaining lifetime of the inbox session token, in seconds.", "x-presence": "implicit" } } }, "GetInboxFeedRequest": { "type": "object", "description": "Caller user_id derived from auth headers by gateway.", "properties": { "page": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Page number used by this listing operation, starting at 1.", "x-presence": "implicit" }, "pageSize": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100, "description": "Number of entries requested per page. Zero or omission lets the server choose its default.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 100, "gte": 0 } }, "x-validation-scope": "request" }, "filter": { "description": "Selection criteria applied to the listing.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/InboxFeedFilter" } ] } } }, "InboxFeedFilter": { "type": "object", "description": "Read-state, category, tag, and archive criteria selecting inbox entries.", "properties": { "unseenOnly": { "type": "boolean", "description": "Whether the inbox filter selects only unseen messages.", "x-presence": "implicit" }, "unreadOnly": { "type": "boolean", "description": "Whether the inbox filter selects only unread messages.", "x-presence": "implicit" }, "feedIds": { "type": "array", "items": { "type": "string" }, "description": "Filter by Novu feed identifiers.", "x-presence": "collection" }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Categories used to select inbox messages.", "x-presence": "collection" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Filter by workflow tags (OR logic per Novu semantics).", "x-presence": "collection" }, "archived": { "type": "boolean", "description": "When true, include archived messages. False or omission selects the live inbox\nand excludes archived messages.", "x-presence": "implicit" } }, "x-reference-model": { "title": "InboxFeedFilter", "url": "/api/models/inbox-feed-filter#request" } }, "GetInboxFeedResponse": { "type": "object", "description": "Result payload for paging through a subscriber’s inbox with read-state and category filters.", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/InboxMessage" }, "description": "Inbox messages returned after applying the selected query or state change.", "x-presence": "collection" }, "totalCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Total number of matching entries reported by the operation.", "x-presence": "implicit" }, "page": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Page number reported for the returned inbox feed.", "x-presence": "implicit" }, "pageSize": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Page size reported for the returned inbox feed.", "x-presence": "implicit" }, "hasMore": { "type": "boolean", "description": "Whether the listing reports additional entries beyond this page.", "x-presence": "implicit" } } }, "InboxMessage": { "type": "object", "description": "Notification content and interaction state displayed in a subscriber’s inbox.", "properties": { "messageId": { "type": "string", "description": "Identifier of the message represented by this inbox entry.", "x-presence": "implicit" }, "notificationId": { "type": "string", "description": "Identifier of the notification represented by this inbox entry.", "x-presence": "implicit" }, "title": { "type": "string", "description": "Title displayed for the inbox notification.", "x-presence": "implicit" }, "body": { "type": "string", "description": "Body text of the inbox message.", "x-presence": "implicit" }, "data": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional key-value attributes attached to the inbox notification.", "x-presence": "collection" }, "deepLink": { "type": "string", "description": "Application deep link associated with the inbox message.", "x-presence": "implicit" }, "imageUrl": { "type": "string", "description": "Image URL associated with the inbox message.", "x-presence": "implicit" }, "status": { "oneOf": [ { "type": "string", "enum": [ "MESSAGE_STATUS_UNSEEN", "MESSAGE_STATUS_SEEN", "MESSAGE_STATUS_READ", "MESSAGE_STATUS_UNREAD", "MESSAGE_STATUS_ARCHIVED" ], "x-enumDescriptions": { "MESSAGE_STATUS_UNSEEN": "The message has not been marked seen or read.", "MESSAGE_STATUS_SEEN": "The message has been marked seen and is not marked read or archived.", "MESSAGE_STATUS_READ": "The message has been marked read and is not archived.", "MESSAGE_STATUS_UNREAD": "Request clearing the read state; this is an update action rather than a distinct status\nemitted by message reads.", "MESSAGE_STATUS_ARCHIVED": "The message has been archived; this state takes precedence over seen and read when reported." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "MESSAGE_STATUS_UNSEEN", "number": 1, "canonical": true, "description": "The message has not been marked seen or read." }, { "name": "MESSAGE_STATUS_SEEN", "number": 2, "canonical": true, "description": "The message has been marked seen and is not marked read or archived." }, { "name": "MESSAGE_STATUS_READ", "number": 3, "canonical": true, "description": "The message has been marked read and is not archived." }, { "name": "MESSAGE_STATUS_UNREAD", "number": 4, "canonical": true, "description": "Request clearing the read state; this is an update action rather than a distinct status\nemitted by message reads." }, { "name": "MESSAGE_STATUS_ARCHIVED", "number": 5, "canonical": true, "description": "The message has been archived; this state takes precedence over seen and read when reported." } ], "x-enum-description": "Inbox state or requested state transition for a notification message.", "description": "Read, seen, or archived state recorded for the inbox message.", "x-presence": "implicit" }, "category": { "type": "string", "description": "Category assigned to the inbox message or workflow.", "x-presence": "implicit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when this record was created.", "x-presence": "message" }, "seenAt": { "type": "string", "format": "date-time", "description": "Time when the inbox message was marked seen.", "x-presence": "message" }, "readAt": { "type": "string", "format": "date-time", "description": "Time when the inbox message was marked read.", "x-presence": "message" }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/InboxMessageAction" }, "description": "Interactive actions attached to the inbox message.", "x-presence": "collection" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Workflow tags for tab assignment (OR-filtered in feed).", "x-presence": "collection" }, "archived": { "type": "boolean", "description": "Whether this inbox notification is archived.", "x-presence": "implicit" }, "archivedAt": { "type": "string", "format": "date-time", "description": "Time when the inbox message was archived.", "x-presence": "message" } }, "x-reference-model": { "title": "InboxMessage", "url": "/api/models/inbox-message#response" } }, "InboxMessageAction": { "type": "object", "description": "Interactive action attached to an inbox message, including completion state.", "properties": { "actionId": { "type": "string", "description": "Identifier of an action attached to the inbox message.", "x-presence": "implicit" }, "label": { "type": "string", "description": "Display label for the inbox action.", "x-presence": "implicit" }, "url": { "type": "string", "description": "Destination URL opened by this inbox action.", "x-presence": "implicit" }, "isPrimary": { "type": "boolean", "description": "Whether the inbox action is designated as the primary action.", "x-presence": "implicit" }, "completed": { "type": "boolean", "description": "Whether the user has completed this action via CompleteInboxAction.", "x-presence": "implicit" }, "completedAt": { "type": "string", "format": "date-time", "description": "Time when this inbox action was marked complete.", "x-presence": "message" } }, "x-reference-model": { "title": "InboxMessageAction", "url": "/api/models/inbox-message-action#response" } }, "GetInboxUnseenCountRequest": { "type": "object", "description": "Caller user_id derived from auth headers by gateway.", "properties": { "feedIds": { "type": "array", "items": { "type": "string" }, "description": "Feed identifiers used to select inbox messages.", "x-presence": "collection" } } }, "GetInboxUnseenCountResponse": { "type": "object", "description": "Result payload for counting unseen inbox notifications in selected feeds.", "properties": { "unseenCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of inbox messages reported unseen, capped at 10. Check has_more_unseen\nbefore treating this count as an exact total.", "x-presence": "implicit" }, "unreadCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of inbox messages reported unread, capped at 10. Check has_more_unread\nbefore treating this count as an exact total.", "x-presence": "implicit" }, "hasMoreUnseen": { "type": "boolean", "description": "Whether unseen messages exceed the capped count. When true, a badge can display \"9+\".", "x-presence": "implicit" }, "hasMoreUnread": { "type": "boolean", "description": "Whether unread messages exceed the capped count. When true, a badge can display \"9+\".", "x-presence": "implicit" } } }, "MarkInboxMessageAsRequest": { "type": "object", "description": "Caller user_id derived from auth headers by gateway.", "properties": { "messageId": { "type": "string", "minLength": 1, "description": "Identifier of the inbox message to read or modify.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "markAs": { "oneOf": [ { "type": "string", "enum": [ "MESSAGE_STATUS_UNSEEN", "MESSAGE_STATUS_SEEN", "MESSAGE_STATUS_READ", "MESSAGE_STATUS_UNREAD", "MESSAGE_STATUS_ARCHIVED" ], "x-enumDescriptions": { "MESSAGE_STATUS_UNSEEN": "The message has not been marked seen or read.", "MESSAGE_STATUS_SEEN": "The message has been marked seen and is not marked read or archived.", "MESSAGE_STATUS_READ": "The message has been marked read and is not archived.", "MESSAGE_STATUS_UNREAD": "Request clearing the read state; this is an update action rather than a distinct status\nemitted by message reads.", "MESSAGE_STATUS_ARCHIVED": "The message has been archived; this state takes precedence over seen and read when reported." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "MESSAGE_STATUS_UNSEEN", "number": 1, "canonical": true, "description": "The message has not been marked seen or read." }, { "name": "MESSAGE_STATUS_SEEN", "number": 2, "canonical": true, "description": "The message has been marked seen and is not marked read or archived." }, { "name": "MESSAGE_STATUS_READ", "number": 3, "canonical": true, "description": "The message has been marked read and is not archived." }, { "name": "MESSAGE_STATUS_UNREAD", "number": 4, "canonical": true, "description": "Request clearing the read state; this is an update action rather than a distinct status\nemitted by message reads." }, { "name": "MESSAGE_STATUS_ARCHIVED", "number": 5, "canonical": true, "description": "The message has been archived; this state takes precedence over seen and read when reported." } ], "x-enum-description": "Inbox state or requested state transition for a notification message.", "description": "Inbox state to apply to the selected message or messages.", "x-presence": "implicit" } }, "x-request-required": [ "messageId" ], "required": [ "messageId" ] }, "MarkInboxMessageAsResponse": { "type": "object", "description": "Result payload for changing an inbox message’s read or seen state.", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/InboxMessageSummary" }, "description": "Inbox messages returned after applying the selected query or state change.", "x-presence": "collection" } } }, "InboxMessageSummary": { "type": "object", "description": "Summary of an inbox message after a mark operation.", "properties": { "messageId": { "type": "string", "description": "Identifier of the inbox message represented by this summary.", "x-presence": "implicit" }, "channel": { "type": "string", "description": "Delivery channel reported for this inbox message.", "x-presence": "implicit" }, "read": { "type": "boolean", "description": "Whether the inbox message has been marked read.", "x-presence": "implicit" }, "seen": { "type": "boolean", "description": "Whether the inbox message has been marked seen.", "x-presence": "implicit" }, "archived": { "type": "boolean", "description": "Whether this inbox message is archived.", "x-presence": "implicit" }, "content": { "type": "string", "description": "Rendered notification content.", "x-presence": "implicit" }, "subject": { "type": "string", "description": "Subject text for the notification message.", "x-presence": "implicit" }, "status": { "type": "string", "description": "Status reported by the notification provider.", "x-presence": "implicit" }, "createdAt": { "type": "string", "description": "Time when this record was created.", "x-presence": "implicit" }, "lastReadDate": { "type": "string", "description": "Most recent timestamp recorded for reading inbox messages.", "x-presence": "implicit" }, "lastSeenDate": { "type": "string", "description": "Most recent timestamp recorded for seeing inbox messages.", "x-presence": "implicit" } }, "x-reference-model": { "title": "InboxMessageSummary", "url": "/api/models/inbox-message-summary#response" } }, "MarkAllInboxMessagesAsRequest": { "type": "object", "description": "Caller user_id derived from auth headers by gateway.", "properties": { "markAs": { "oneOf": [ { "type": "string", "enum": [ "MESSAGE_STATUS_UNSEEN", "MESSAGE_STATUS_SEEN", "MESSAGE_STATUS_READ", "MESSAGE_STATUS_UNREAD", "MESSAGE_STATUS_ARCHIVED" ], "x-enumDescriptions": { "MESSAGE_STATUS_UNSEEN": "The message has not been marked seen or read.", "MESSAGE_STATUS_SEEN": "The message has been marked seen and is not marked read or archived.", "MESSAGE_STATUS_READ": "The message has been marked read and is not archived.", "MESSAGE_STATUS_UNREAD": "Request clearing the read state; this is an update action rather than a distinct status\nemitted by message reads.", "MESSAGE_STATUS_ARCHIVED": "The message has been archived; this state takes precedence over seen and read when reported." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "MESSAGE_STATUS_UNSEEN", "number": 1, "canonical": true, "description": "The message has not been marked seen or read." }, { "name": "MESSAGE_STATUS_SEEN", "number": 2, "canonical": true, "description": "The message has been marked seen and is not marked read or archived." }, { "name": "MESSAGE_STATUS_READ", "number": 3, "canonical": true, "description": "The message has been marked read and is not archived." }, { "name": "MESSAGE_STATUS_UNREAD", "number": 4, "canonical": true, "description": "Request clearing the read state; this is an update action rather than a distinct status\nemitted by message reads." }, { "name": "MESSAGE_STATUS_ARCHIVED", "number": 5, "canonical": true, "description": "The message has been archived; this state takes precedence over seen and read when reported." } ], "x-enum-description": "Inbox state or requested state transition for a notification message.", "description": "Inbox state to apply to the selected message or messages.", "x-presence": "implicit" }, "feedIds": { "type": "array", "items": { "type": "string" }, "description": "Feed identifiers used to select inbox messages.", "x-presence": "collection" } } }, "MarkAllInboxMessagesAsResponse": { "type": "object", "description": "Result payload for changing the read or seen state of selected inbox messages.", "properties": { "updatedCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of preference entries reported updated.", "x-presence": "implicit" } } }, "DeleteInboxMessageRequest": { "type": "object", "description": "Caller user_id derived from auth headers by gateway.", "properties": { "messageId": { "type": "string", "minLength": 1, "description": "Identifier of the inbox message to read or modify.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "messageId" ], "required": [ "messageId" ] }, "DeleteInboxMessageResponse": { "type": "object", "description": "Result payload for removing an identified message from the subscriber’s notification inbox.", "properties": { "status": { "description": "Status reported by the notification provider.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/OperationStatus" } ] } } }, "OperationStatus": { "type": "object", "description": "Mirrors Novu's common delete/mutate acknowledgement response.", "properties": { "acknowledged": { "type": "boolean", "description": "Whether the provider acknowledged the requested operation.", "x-presence": "implicit" }, "status": { "type": "string", "description": "Status reported by the notification provider.", "x-presence": "implicit" } }, "x-reference-model": { "title": "OperationStatus", "url": "/api/models/operation-status#response" } }, "ArchiveInboxMessageRequest": { "type": "object", "description": "Caller user_id derived from auth headers by gateway.", "properties": { "notificationId": { "type": "string", "minLength": 1, "description": "Identifier of the notification whose inbox entry is being modified.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "notificationId" ], "required": [ "notificationId" ] }, "ArchiveInboxMessageResponse": { "type": "object", "description": "Result payload for archiving one inbox notification while retaining its provider record.", "properties": { "status": { "description": "Status reported by the notification provider.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/OperationStatus" } ] } } }, "UnarchiveInboxMessageRequest": { "type": "object", "description": "Inputs for restoring an archived notification to the subscriber’s inbox feed.", "properties": { "notificationId": { "type": "string", "minLength": 1, "description": "Identifier of the notification whose inbox entry is being modified.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "notificationId" ], "required": [ "notificationId" ] }, "UnarchiveInboxMessageResponse": { "type": "object", "description": "Result payload for restoring an archived notification to the subscriber’s inbox feed.", "properties": { "status": { "description": "Status reported by the notification provider.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/OperationStatus" } ] } } }, "ArchiveAllInboxMessagesRequest": { "type": "object", "description": "Inputs for archiving inbox notifications selected by the supplied tag filter.", "properties": { "tags": { "type": "array", "items": { "type": "string" }, "description": "Labels associated with the resource for organization or filtering.", "x-presence": "collection" } } }, "ArchiveAllInboxMessagesResponse": { "type": "object", "description": "Result payload for archiving inbox notifications selected by the supplied tag filter.", "properties": { "archivedCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of inbox entries reported archived by the operation.", "x-presence": "implicit" } } }, "ArchiveAllReadInboxMessagesRequest": { "type": "object", "description": "Inputs for archiving read inbox notifications selected by the supplied tag filter.", "properties": { "tags": { "type": "array", "items": { "type": "string" }, "description": "Labels associated with the resource for organization or filtering.", "x-presence": "collection" } } }, "ArchiveAllReadInboxMessagesResponse": { "type": "object", "description": "Mirrors ArchiveAllInboxMessagesResponse — same shape, distinct type so the\ntwo bulk-archive RPC contracts can evolve independently.", "properties": { "archivedCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of inbox entries reported archived by the operation.", "x-presence": "implicit" } } }, "CompleteInboxActionRequest": { "type": "object", "description": "Inputs for marking an inbox notification’s action completed.", "properties": { "notificationId": { "type": "string", "minLength": 1, "description": "Identifier of the notification whose inbox entry is being modified.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "actionType": { "oneOf": [ { "type": "string", "enum": [ "ACTION_TYPE_PRIMARY", "ACTION_TYPE_SECONDARY" ], "x-enumDescriptions": { "ACTION_TYPE_PRIMARY": "The notification's primary action button or action slot.", "ACTION_TYPE_SECONDARY": "The notification's secondary action button or action slot." } }, { "type": "integer", "format": "int32", "enum": [ 1, 2 ], "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "ACTION_TYPE_PRIMARY", "number": 1, "canonical": true, "description": "The notification's primary action button or action slot." }, { "name": "ACTION_TYPE_SECONDARY", "number": 2, "canonical": true, "description": "The notification's secondary action button or action slot." } ], "x-enum-description": "Which configured notification action a completion or reversal refers to.", "description": "Action selector used when completing or reverting an inbox action.", "x-presence": "implicit", "x-protovalidate": { "enum": { "definedOnly": true, "notIn": [ 0 ] } }, "x-validation-scope": "request" } }, "x-request-required": [ "notificationId", "actionType" ], "required": [ "notificationId", "actionType" ] }, "CompleteInboxActionResponse": { "type": "object", "description": "Result payload for marking an inbox notification’s action completed.", "properties": { "status": { "description": "Status reported by the notification provider.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/OperationStatus" } ] } } }, "RevertInboxActionRequest": { "type": "object", "description": "Inputs for undoing completion of an inbox notification’s action.", "properties": { "notificationId": { "type": "string", "minLength": 1, "description": "Identifier of the notification whose inbox entry is being modified.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "actionType": { "oneOf": [ { "type": "string", "enum": [ "ACTION_TYPE_PRIMARY", "ACTION_TYPE_SECONDARY" ], "x-enumDescriptions": { "ACTION_TYPE_PRIMARY": "The notification's primary action button or action slot.", "ACTION_TYPE_SECONDARY": "The notification's secondary action button or action slot." } }, { "type": "integer", "format": "int32", "enum": [ 1, 2 ], "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "ACTION_TYPE_PRIMARY", "number": 1, "canonical": true, "description": "The notification's primary action button or action slot." }, { "name": "ACTION_TYPE_SECONDARY", "number": 2, "canonical": true, "description": "The notification's secondary action button or action slot." } ], "x-enum-description": "Which configured notification action a completion or reversal refers to.", "description": "Action selector used when completing or reverting an inbox action.", "x-presence": "implicit", "x-protovalidate": { "enum": { "definedOnly": true, "notIn": [ 0 ] } }, "x-validation-scope": "request" } }, "x-request-required": [ "notificationId", "actionType" ], "required": [ "notificationId", "actionType" ] }, "RevertInboxActionResponse": { "type": "object", "description": "Result payload for undoing completion of an inbox notification’s action.", "properties": { "status": { "description": "Status reported by the notification provider.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/OperationStatus" } ] } } }, "GetPreferencesRequest": { "type": "object", "description": "Caller user_id derived from auth headers by gateway.", "properties": {} }, "GetPreferencesResponse": { "type": "object", "description": "Result payload for reading global and workflow-specific channel preferences for a subscriber.", "properties": { "global": { "description": "Subscriber preferences that apply across notification workflows.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GlobalPreferences" } ] }, "workflows": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowPreferences" }, "description": "Subscriber channel preferences for individual notification workflows.", "x-presence": "collection" } } }, "GlobalPreferences": { "type": "object", "description": "Subscriber's global (all-workflow) notification preferences.", "properties": { "enabled": { "type": "boolean", "description": "Master switch — false disables all non-critical notifications.", "x-presence": "implicit" }, "channels": { "description": "Channel switches recorded for these subscriber preferences.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ChannelToggles" } ] } }, "x-reference-model": { "title": "GlobalPreferences", "url": "/api/models/global-preferences#response" } }, "ChannelToggles": { "type": "object", "description": "Per-channel notification toggles. All fields are optional so that callers\ncan patch only the channels they want to change (omitted = leave unchanged).", "properties": { "inApp": { "type": "boolean", "description": "Whether in-app notification delivery is enabled.", "x-presence": "explicit" }, "push": { "type": "boolean", "description": "Whether push notification delivery is enabled.", "x-presence": "explicit" }, "email": { "type": "boolean", "description": "Whether email notification delivery is enabled.", "x-presence": "explicit" }, "sms": { "type": "boolean", "description": "Whether SMS notification delivery is enabled.", "x-presence": "explicit" }, "chat": { "type": "boolean", "description": "Whether chat notification delivery is enabled.", "x-presence": "explicit" } }, "x-reference-model": { "title": "ChannelToggles", "url": "/api/models/channel-toggles#response" } }, "WorkflowPreferences": { "type": "object", "description": "Per-workflow notification channel preferences for a subscriber.", "properties": { "workflowId": { "type": "string", "description": "Novu workflow identifier (slug).", "x-presence": "implicit" }, "workflowName": { "type": "string", "description": "Human-readable display name.", "x-presence": "implicit" }, "critical": { "type": "boolean", "description": "If true, subscriber cannot opt out (admin-enforced).", "x-presence": "implicit" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Workflow tags for grouping in settings UI.", "x-presence": "collection" }, "channels": { "description": "Channel switches recorded for these subscriber preferences.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ChannelToggles" } ] } }, "x-reference-model": { "title": "WorkflowPreferences", "url": "/api/models/workflow-preferences#response" } }, "UpdateGlobalPreferenceRequest": { "type": "object", "description": "Inputs for changing the subscriber’s channel preferences across notification workflows.", "properties": { "channels": { "description": "Channel switches to update for the subscriber.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ChannelTogglesInput" } ] } } }, "ChannelTogglesInput": { "type": "object", "description": "Per-channel notification toggles. All fields are optional so that callers\ncan patch only the channels they want to change (omitted = leave unchanged).", "properties": { "inApp": { "type": "boolean", "description": "Whether in-app notification delivery is enabled.", "x-presence": "explicit" }, "push": { "type": "boolean", "description": "Whether push notification delivery is enabled.", "x-presence": "explicit" }, "email": { "type": "boolean", "description": "Whether email notification delivery is enabled.", "x-presence": "explicit" }, "sms": { "type": "boolean", "description": "Whether SMS notification delivery is enabled.", "x-presence": "explicit" }, "chat": { "type": "boolean", "description": "Whether chat notification delivery is enabled.", "x-presence": "explicit" } }, "x-reference-model": { "title": "ChannelToggles", "url": "/api/models/channel-toggles#request" } }, "ProtobufEmpty": { "type": "object", "properties": {}, "description": "An empty JSON object." }, "UpdateWorkflowPreferenceRequest": { "type": "object", "description": "Inputs for changing the subscriber’s channel preferences for one notification workflow.", "properties": { "workflowId": { "type": "string", "minLength": 1, "description": "Identifier of the notification workflow to execute or configure.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "channels": { "description": "Channel switches to update for the subscriber.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ChannelTogglesInput" } ] } }, "x-reference-model": { "title": "UpdateWorkflowPreferenceRequest", "url": "/api/models/update-workflow-preference-request#request" }, "x-request-required": [ "workflowId" ], "required": [ "workflowId" ] }, "BulkUpdatePreferencesRequest": { "type": "object", "description": "Inputs for applying channel-preference changes across selected notification workflows.", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/UpdateWorkflowPreferenceRequest" }, "maxItems": 100, "description": "Workflow-specific preference updates submitted together.", "x-presence": "collection", "x-protovalidate": { "repeated": { "maxItems": "100" } }, "x-validation-scope": "request" } } }, "BulkUpdatePreferencesResponse": { "type": "object", "description": "Result payload for applying channel-preference changes across selected notification workflows.", "properties": { "updatedCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of preference entries reported updated.", "x-presence": "implicit" } } }, "SendNotificationRequest": { "type": "object", "description": "user_id is the recipient, not the caller.", "properties": { "workflowId": { "type": "string", "minLength": 1, "description": "Identifier of the notification workflow to execute or configure.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "userId": { "type": "string", "minLength": 1, "description": "Identifier of the notification's intended recipient.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "payload": { "type": "object", "additionalProperties": true, "description": "Template variables and event data passed to the notification workflow.", "x-presence": "message" }, "overrides": { "type": "object", "additionalProperties": true, "description": "Provider-specific overrides passed through to delivery, such as an FCM data payload.", "x-presence": "message" }, "transactionId": { "type": "string", "description": "Identifier correlating a notification trigger with later status or cancellation requests.", "x-presence": "implicit" } }, "x-request-required": [ "workflowId", "userId" ], "required": [ "workflowId", "userId" ] }, "SendNotificationResponse": { "type": "object", "description": "Result payload for triggering a notification workflow for a selected user.", "properties": { "acknowledged": { "type": "boolean", "description": "Whether the notification provider acknowledged the trigger.", "x-presence": "implicit" }, "status": { "type": "string", "description": "Descriptive status reported by the notification provider, not a fixed set of states.\n\"processed\" means the workflow was accepted for processing; it does not confirm delivery.", "x-presence": "implicit" }, "transactionId": { "type": "string", "description": "Identifier correlating a notification trigger with later status or cancellation requests.", "x-presence": "implicit" }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Errors reported while processing notification requests.", "x-presence": "collection" } } }, "SendBulkNotificationRequest": { "type": "object", "description": "events contain recipient user_ids, not the caller.", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/BulkTriggerEvent" }, "description": "Notification trigger events submitted together. Submit at most 100 events per batch.", "x-presence": "collection" } } }, "BulkTriggerEvent": { "type": "object", "description": "One notification workflow trigger included in a bulk submission.", "properties": { "workflowId": { "type": "string", "minLength": 1, "description": "Identifier of the notification workflow to execute or configure.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "userId": { "type": "string", "minLength": 1, "description": "Identifier of the user associated with the operation.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "payload": { "type": "object", "additionalProperties": true, "description": "Template variables and event data passed to the notification workflow.", "x-presence": "message" }, "overrides": { "type": "object", "additionalProperties": true, "description": "Provider-specific overrides applied to the notification trigger.", "x-presence": "message" }, "transactionId": { "type": "string", "description": "Identifier correlating a notification trigger with later status or cancellation requests.", "x-presence": "implicit" } }, "x-reference-model": { "title": "BulkTriggerEvent", "url": "/api/models/bulk-trigger-event#request" }, "x-request-required": [ "workflowId", "userId" ], "required": [ "workflowId", "userId" ] }, "SendBulkNotificationResponse": { "type": "object", "description": "Result payload for triggering multiple notification workflow events together.", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/BulkTriggerResult" }, "description": "Provider acknowledgements and errors for the submitted notification triggers.", "x-presence": "collection" } } }, "BulkTriggerResult": { "type": "object", "description": "Provider acknowledgement and errors for one bulk notification trigger.", "properties": { "acknowledged": { "type": "boolean", "description": "Whether the notification provider acknowledged the trigger.", "x-presence": "implicit" }, "status": { "type": "string", "description": "Status reported by the notification provider.", "x-presence": "implicit" }, "transactionId": { "type": "string", "description": "Identifier correlating a notification trigger with later status or cancellation requests.", "x-presence": "implicit" }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Errors reported while processing notification requests.", "x-presence": "collection" } }, "x-reference-model": { "title": "BulkTriggerResult", "url": "/api/models/bulk-trigger-result#response" } }, "CancelNotificationRequest": { "type": "object", "description": "Inputs for cancelling a pending notification by transaction identifier.", "properties": { "transactionId": { "type": "string", "minLength": 1, "description": "Identifier correlating a notification trigger with later status or cancellation requests.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "transactionId" ], "required": [ "transactionId" ] }, "CancelNotificationResponse": { "type": "object", "description": "Result payload for cancelling a pending notification by transaction identifier.", "properties": { "cancelled": { "type": "boolean", "description": "Whether the notification cancellation was acknowledged.", "x-presence": "implicit" }, "message": { "type": "string", "description": "Diagnostic or descriptive text returned by the operation.", "x-presence": "implicit" } } }, "CreateTopicRequest": { "type": "object", "description": "Inputs for creating a named notification topic with a caller-selected key.", "properties": { "topicKey": { "type": "string", "minLength": 1, "description": "Caller-facing key identifying a notification topic.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "name": { "type": "string", "description": "Display name assigned to the notification topic.", "x-presence": "implicit" } }, "x-request-required": [ "topicKey" ], "required": [ "topicKey" ] }, "CreateTopicResponse": { "type": "object", "description": "Result payload for creating a named notification topic with a caller-selected key.", "properties": { "topicKey": { "type": "string", "description": "Caller-facing key identifying a notification topic.", "x-presence": "implicit" }, "topicId": { "type": "string", "description": "Provider-assigned identifier of the notification topic.", "x-presence": "implicit" } } }, "DeleteTopicRequest": { "type": "object", "description": "Inputs for removing an identified notification topic.", "properties": { "topicKey": { "type": "string", "minLength": 1, "description": "Caller-facing key identifying a notification topic.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "topicKey" ], "required": [ "topicKey" ] }, "DeleteTopicResponse": { "type": "object", "description": "Result payload for removing an identified notification topic.", "properties": { "status": { "description": "Status reported by the notification provider.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/OperationStatus" } ] } } }, "AddSubscribersToTopicRequest": { "type": "object", "description": "Inputs for adding selected users to a notification topic’s recipient membership.", "properties": { "topicKey": { "type": "string", "minLength": 1, "description": "Caller-facing key identifying a notification topic.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "userIds": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Identifiers of the users selected by the operation.", "x-presence": "collection", "x-protovalidate": { "repeated": { "maxItems": "100" } }, "x-validation-scope": "request" } }, "x-request-required": [ "topicKey" ], "required": [ "topicKey" ] }, "AddSubscribersToTopicResponse": { "type": "object", "description": "Result payload for adding selected users to a notification topic’s recipient membership.", "properties": { "result": { "description": "Accepted and failed subscriber counts with per-subscriber errors from the membership change.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/TopicSubscriptionResult" } ] } } }, "TopicSubscriptionResult": { "type": "object", "description": "Result of a topic subscription operation (add/remove subscribers).\nNovu returns partial success — some subscribers may fail while others succeed.", "properties": { "totalCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Total number of matching entries reported by the operation.", "x-presence": "implicit" }, "successful": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of subscribers accepted by the topic subscription operation.", "x-presence": "implicit" }, "failed": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of subscribers rejected by the topic subscription operation.", "x-presence": "implicit" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/TopicSubscriptionError" }, "description": "Errors reported while processing notification requests.", "x-presence": "collection" } }, "x-reference-model": { "title": "TopicSubscriptionResult", "url": "/api/models/topic-subscription-result#response" } }, "TopicSubscriptionError": { "type": "object", "description": "Subscriber-specific failure reported while changing notification-topic membership.", "properties": { "subscriberId": { "type": "string", "description": "Identifier of the notification subscriber.", "x-presence": "implicit" }, "code": { "type": "string", "description": "Provider error code for the topic subscription failure.", "x-presence": "implicit" }, "message": { "type": "string", "description": "Diagnostic or descriptive text returned by the operation.", "x-presence": "implicit" } }, "x-reference-model": { "title": "TopicSubscriptionError", "url": "/api/models/topic-subscription-error#response" } }, "RemoveSubscribersFromTopicRequest": { "type": "object", "description": "Inputs for removing selected users from a notification topic’s recipient membership.", "properties": { "topicKey": { "type": "string", "minLength": 1, "description": "Caller-facing key identifying a notification topic.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "userIds": { "type": "array", "items": { "type": "string" }, "description": "Identifiers of the users selected by the operation.", "x-presence": "collection" } }, "x-request-required": [ "topicKey" ], "required": [ "topicKey" ] }, "RemoveSubscribersFromTopicResponse": { "type": "object", "description": "Result payload for removing selected users from a notification topic’s recipient membership.", "properties": { "result": { "description": "Accepted and failed subscriber counts with per-subscriber errors from the membership change.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/TopicSubscriptionResult" } ] } } }, "ListTopicSubscribersRequest": { "type": "object", "description": "Inputs for paging through members of a selected notification topic.", "properties": { "topicKey": { "type": "string", "minLength": 1, "description": "Caller-facing key identifying a notification topic.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "page": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Page number used by this listing operation.", "x-presence": "implicit" }, "pageSize": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100, "description": "Number of entries requested per page. Zero or omission lets the server choose its default.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 100, "gte": 0 } }, "x-validation-scope": "request" } }, "x-request-required": [ "topicKey" ], "required": [ "topicKey" ] }, "ListTopicSubscribersResponse": { "type": "object", "description": "Result payload for paging through members of a selected notification topic.", "properties": { "userIds": { "type": "array", "items": { "type": "string" }, "description": "Identifiers of the users selected by the operation.", "x-presence": "collection" }, "totalCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Total number of matching entries reported by the operation.", "x-presence": "implicit" }, "hasMore": { "type": "boolean", "description": "Whether the listing reports additional entries beyond this page.", "x-presence": "implicit" } } }, "CheckTopicSubscriptionRequest": { "type": "object", "description": "user_id is a query target, not the caller.", "properties": { "topicKey": { "type": "string", "minLength": 1, "description": "Caller-facing key identifying a notification topic.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "userId": { "type": "string", "minLength": 1, "description": "Identifier of the user associated with the operation.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "topicKey", "userId" ], "required": [ "topicKey", "userId" ] }, "CheckTopicSubscriptionResponse": { "type": "object", "description": "Result payload for checking whether a user belongs to a notification topic.", "properties": { "isSubscribed": { "type": "boolean", "description": "Whether the user is subscribed to the selected topic.", "x-presence": "implicit" } } }, "SendToTopicRequest": { "type": "object", "description": "exclude_user_id is an exclusion target, not the caller.", "properties": { "workflowId": { "type": "string", "minLength": 1, "description": "Identifier of the notification workflow to execute or configure.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "topicKey": { "type": "string", "minLength": 1, "description": "Caller-facing key identifying a notification topic.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "payload": { "type": "object", "additionalProperties": true, "description": "Template variables and event data passed to the notification workflow.", "x-presence": "message" }, "overrides": { "type": "object", "additionalProperties": true, "description": "Provider-specific overrides applied to the notification trigger.", "x-presence": "message" }, "transactionId": { "type": "string", "description": "Identifier correlating a notification trigger with later status or cancellation requests.", "x-presence": "implicit" }, "excludeUserId": { "type": "string", "description": "User identifier to omit from the topic notification’s recipients.", "x-presence": "implicit" } }, "x-request-required": [ "workflowId", "topicKey" ], "required": [ "workflowId", "topicKey" ] }, "SendToTopicResponse": { "type": "object", "description": "Result payload for triggering a notification workflow for the subscribers of a topic.", "properties": { "acknowledged": { "type": "boolean", "description": "Whether the notification provider acknowledged the trigger.", "x-presence": "implicit" }, "status": { "type": "string", "description": "Status reported by the notification provider.", "x-presence": "implicit" }, "transactionId": { "type": "string", "description": "Identifier correlating a notification trigger with later status or cancellation requests.", "x-presence": "implicit" }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Errors reported while processing notification requests.", "x-presence": "collection" } } }, "SendWithDigestRequest": { "type": "object", "description": "user_id is the recipient, not the caller.", "properties": { "workflowId": { "type": "string", "minLength": 1, "description": "Identifier of the notification workflow to execute or configure.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "userId": { "type": "string", "minLength": 1, "description": "Identifier of the user associated with the operation.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "payload": { "type": "object", "additionalProperties": true, "description": "Template variables and event data passed to the notification workflow.", "x-presence": "message" }, "overrides": { "type": "object", "additionalProperties": true, "description": "Provider-specific overrides applied to the notification trigger.", "x-presence": "message" }, "transactionId": { "type": "string", "description": "Identifier correlating a notification trigger with later status or cancellation requests.", "x-presence": "implicit" } }, "x-request-required": [ "workflowId", "userId" ], "required": [ "workflowId", "userId" ] }, "SendWithDigestResponse": { "type": "object", "description": "Result payload for submitting a notification event for digest processing.", "properties": { "acknowledged": { "type": "boolean", "description": "Whether the notification provider acknowledged the trigger.", "x-presence": "implicit" }, "status": { "type": "string", "description": "Status reported by the notification provider.", "x-presence": "implicit" }, "transactionId": { "type": "string", "description": "Identifier correlating a notification trigger with later status or cancellation requests.", "x-presence": "implicit" }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Errors reported while processing notification requests.", "x-presence": "collection" } } }, "CancelDigestEventRequest": { "type": "object", "description": "Inputs for cancelling a queued notification digest event.", "properties": { "transactionId": { "type": "string", "minLength": 1, "description": "Identifier correlating a notification trigger with later status or cancellation requests.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "transactionId" ], "required": [ "transactionId" ] }, "CancelDigestEventResponse": { "type": "object", "description": "Result payload for cancelling a queued notification digest event.", "properties": { "cancelled": { "type": "boolean", "description": "Whether the notification cancellation was acknowledged.", "x-presence": "implicit" }, "message": { "type": "string", "description": "Diagnostic or descriptive text returned by the operation.", "x-presence": "implicit" } } }, "CreateSubscriberRequest": { "type": "object", "description": "tenant_id and environment derived from auth headers by gateway.", "properties": { "subscriberId": { "type": "string", "minLength": 1, "description": "Identifier of the notification subscriber.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "email": { "type": "string", "description": "Email address used for subscriber contact and delivery.", "x-presence": "implicit" }, "phone": { "type": "string", "description": "Phone number used for subscriber contact and delivery.", "x-presence": "implicit" }, "firstName": { "type": "string", "description": "Subscriber’s given name.", "x-presence": "implicit" }, "lastName": { "type": "string", "description": "Subscriber’s family name.", "x-presence": "implicit" }, "avatarUrl": { "type": "string", "description": "URL of the subscriber’s avatar image.", "x-presence": "implicit" }, "locale": { "type": "string", "description": "Subscriber locale used when rendering notifications.", "x-presence": "implicit" }, "data": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom key-value attributes to attach to the new subscriber.", "x-presence": "collection" } }, "x-request-required": [ "subscriberId" ], "required": [ "subscriberId" ] }, "CreateSubscriberResponse": { "type": "object", "description": "Result payload for creating a notification subscriber with contact and locale attributes.", "properties": { "novuSubscriberId": { "type": "string", "description": "Subscriber identifier returned by Novu.", "x-presence": "implicit" }, "subscriberId": { "type": "string", "description": "Identifier of the notification subscriber.", "x-presence": "implicit" } } }, "GetSubscriberRequest": { "type": "object", "description": "Caller user_id derived from auth headers by gateway.", "properties": {} }, "GetSubscriberResponse": { "type": "object", "description": "Result payload for retrieving a notification subscriber’s contact and custom attributes.", "properties": { "subscriberId": { "type": "string", "description": "Identifier of the notification subscriber.", "x-presence": "implicit" }, "data": { "description": "Contact, locale, and custom attributes returned for the subscriber.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/SubscriberData" } ] }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelRegistration" }, "description": "Registration status and credential counts for the subscriber’s delivery channels.", "x-presence": "collection" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when this record was created.", "x-presence": "message" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time when this record was last updated.", "x-presence": "message" }, "globalPreferences": { "description": "Subscriber preferences that apply across notification workflows.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GlobalPreferences" } ] }, "workflowPreferences": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowPreferences" }, "description": "Subscriber preferences scoped to individual notification workflows.", "x-presence": "collection" } } }, "SubscriberData": { "type": "object", "description": "Contact, locale, and custom attributes used by notification delivery.", "properties": { "firstName": { "type": "string", "description": "Subscriber’s given name.", "x-presence": "implicit" }, "lastName": { "type": "string", "description": "Subscriber’s family name.", "x-presence": "implicit" }, "email": { "type": "string", "description": "Email address used for subscriber contact and delivery.", "x-presence": "implicit" }, "phone": { "type": "string", "description": "Phone number used for subscriber contact and delivery.", "x-presence": "implicit" }, "avatarUrl": { "type": "string", "description": "URL of the subscriber’s avatar image.", "x-presence": "implicit" }, "locale": { "type": "string", "description": "Subscriber locale used when rendering notifications.", "x-presence": "implicit" }, "timezone": { "type": "string", "description": "Subscriber time zone used for notification presentation.", "x-presence": "implicit" }, "customData": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional template variables.", "x-presence": "collection" } }, "x-reference-model": { "title": "SubscriberData", "url": "/api/models/subscriber-data#response" } }, "UpdateSubscriberDataRequest": { "type": "object", "description": "Caller user_id derived from auth headers by gateway.", "properties": { "data": { "description": "Contact, locale, and custom subscriber attributes to update.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/SubscriberDataInput" } ], "x-protovalidate": { "required": true }, "x-validation-scope": "request" } }, "x-request-required": [ "data" ], "required": [ "data" ] }, "SubscriberDataInput": { "type": "object", "description": "Contact, locale, and custom attributes used by notification delivery.", "properties": { "firstName": { "type": "string", "description": "Subscriber’s given name.", "x-presence": "implicit" }, "lastName": { "type": "string", "description": "Subscriber’s family name.", "x-presence": "implicit" }, "email": { "type": "string", "description": "Email address used for subscriber contact and delivery.", "x-presence": "implicit" }, "phone": { "type": "string", "description": "Phone number used for subscriber contact and delivery.", "x-presence": "implicit" }, "avatarUrl": { "type": "string", "description": "URL of the subscriber’s avatar image.", "x-presence": "implicit" }, "locale": { "type": "string", "description": "Subscriber locale used when rendering notifications.", "x-presence": "implicit" }, "timezone": { "type": "string", "description": "Subscriber time zone used for notification presentation.", "x-presence": "implicit" }, "customData": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional template variables.", "x-presence": "collection" } }, "x-reference-model": { "title": "SubscriberData", "url": "/api/models/subscriber-data#request" } }, "UpdateSubscriberDataResponse": { "type": "object", "description": "Result payload for changing contact, locale, or custom attributes used for notification delivery.", "properties": { "data": { "description": "Contact, locale, and custom attributes returned for the subscriber.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/SubscriberData" } ] }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time when this record was last updated.", "x-presence": "message" } } }, "DeleteSubscriberRequest": { "type": "object", "description": "Caller user_id derived from auth headers by gateway.", "properties": {} }, "DeleteSubscriberResponse": { "type": "object", "description": "Result payload for removing the subscriber’s notification-provider record.", "properties": { "status": { "description": "Status reported by the notification provider.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/OperationStatus" } ] } } }, "ListSubscribersRequest": { "type": "object", "description": "tenant_id and environment derived from auth headers by gateway.", "properties": { "page": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Page number used by this listing operation.", "x-presence": "implicit" }, "pageSize": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100, "description": "Number of entries requested per page. Zero or omission lets the server choose its default.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 100, "gte": 0 } }, "x-validation-scope": "request" } } }, "ListSubscribersResponse": { "type": "object", "description": "Result payload for paging through notification subscribers and their presence summaries.", "properties": { "subscribers": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriberSummary" }, "description": "Subscriber records returned by the listing.", "x-presence": "collection" }, "totalCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Total number of matching entries reported by the operation.", "x-presence": "implicit" }, "hasMore": { "type": "boolean", "description": "Whether the listing reports additional entries beyond this page.", "x-presence": "implicit" } } }, "SubscriberSummary": { "type": "object", "description": "Contact and presence information returned in a subscriber listing.", "properties": { "subscriberId": { "type": "string", "description": "Identifier of the notification subscriber.", "x-presence": "implicit" }, "email": { "type": "string", "description": "Email address used for subscriber contact and delivery.", "x-presence": "implicit" }, "firstName": { "type": "string", "description": "Subscriber’s given name.", "x-presence": "implicit" }, "lastName": { "type": "string", "description": "Subscriber’s family name.", "x-presence": "implicit" }, "isOnline": { "type": "boolean", "description": "Whether the provider reports the subscriber currently online.", "x-presence": "implicit" }, "lastOnlineAt": { "type": "string", "format": "date-time", "description": "Time when the provider last observed the subscriber online.", "x-presence": "message" } }, "x-reference-model": { "title": "SubscriberSummary", "url": "/api/models/subscriber-summary#response" } }, "GetDeliveryStatusRequest": { "type": "object", "description": "Inputs for reading provider activity for a notification transaction.", "properties": { "transactionId": { "type": "string", "minLength": 1, "description": "Identifier correlating a notification trigger with later status or cancellation requests.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "transactionId" ], "required": [ "transactionId" ] }, "GetDeliveryStatusResponse": { "type": "object", "description": "Result payload for reading provider activity for a notification transaction.", "properties": { "activity": { "type": "object", "additionalProperties": true, "description": "Notification activity entries returned by the provider.", "x-presence": "message" } } }, "GetNotificationActivityRequest": { "type": "object", "description": "Caller user_id derived from auth headers by gateway.", "properties": { "page": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Page number used by this listing operation.", "x-presence": "implicit" }, "pageSize": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100, "description": "Number of entries requested per page. Zero or omission lets the server choose its default.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 100, "gte": 0 } }, "x-validation-scope": "request" }, "channels": { "type": "array", "items": { "type": "string" }, "description": "Provider delivery-channel names used to restrict the query, such as \"in_app\" and\n\"push\". These are provider strings, not CHANNEL_* enum names.", "x-presence": "collection" }, "from": { "type": "string", "format": "date-time", "description": "Lower time bound for the notification activity query.", "x-presence": "message" }, "to": { "type": "string", "format": "date-time", "description": "Upper time bound for the notification activity query.", "x-presence": "message" }, "subscriberIds": { "type": "array", "items": { "type": "string" }, "description": "When supplied, restrict notification activity to these subscriber identifiers.", "x-presence": "collection" } } }, "GetNotificationActivityResponse": { "type": "object", "description": "Result payload for querying delivery activity for a user across a selected time range.", "properties": { "entries": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Notification delivery activity entries returned for the selected query.", "x-presence": "collection" }, "hasMore": { "type": "boolean", "description": "Whether the listing reports additional entries beyond this page.", "x-presence": "implicit" } } }, "ConfigureProviderRequest": { "type": "object", "description": "tenant_id and environment derived from auth headers by gateway.", "properties": { "provider": { "oneOf": [ { "type": "string", "enum": [ "PROVIDER_TYPE_FCM", "PROVIDER_TYPE_APNS", "PROVIDER_TYPE_SENDGRID", "PROVIDER_TYPE_SES", "PROVIDER_TYPE_TWILIO", "PROVIDER_TYPE_SLACK", "PROVIDER_TYPE_DISCORD" ], "x-enumDescriptions": { "PROVIDER_TYPE_FCM": "Firebase Cloud Messaging for device or web push delivery.", "PROVIDER_TYPE_APNS": "Apple Push Notification service for Apple-device push delivery.", "PROVIDER_TYPE_SENDGRID": "SendGrid for email delivery.", "PROVIDER_TYPE_SES": "Amazon Simple Email Service for email delivery.", "PROVIDER_TYPE_TWILIO": "Twilio for SMS delivery.", "PROVIDER_TYPE_SLACK": "Slack for chat-message delivery.", "PROVIDER_TYPE_DISCORD": "Discord for chat-message delivery." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "PROVIDER_TYPE_FCM", "number": 1, "canonical": true, "description": "Firebase Cloud Messaging for device or web push delivery." }, { "name": "PROVIDER_TYPE_APNS", "number": 2, "canonical": true, "description": "Apple Push Notification service for Apple-device push delivery." }, { "name": "PROVIDER_TYPE_SENDGRID", "number": 3, "canonical": true, "description": "SendGrid for email delivery." }, { "name": "PROVIDER_TYPE_SES", "number": 4, "canonical": true, "description": "Amazon Simple Email Service for email delivery." }, { "name": "PROVIDER_TYPE_TWILIO", "number": 5, "canonical": true, "description": "Twilio for SMS delivery." }, { "name": "PROVIDER_TYPE_SLACK", "number": 6, "canonical": true, "description": "Slack for chat-message delivery." }, { "name": "PROVIDER_TYPE_DISCORD", "number": 7, "canonical": true, "description": "Discord for chat-message delivery." } ], "x-enum-description": "Service used to deliver a notification through its selected channel.", "description": "Notification delivery provider being configured or reported.", "x-presence": "implicit" }, "credentials": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Provider-specific credentials supplied when configuring delivery.", "x-presence": "collection" }, "active": { "type": "boolean", "description": "Whether the resource is marked active.", "x-presence": "implicit" } } }, "ConfigureProviderResponse": { "type": "object", "description": "Result payload for configuring credentials and activation for a notification delivery provider.", "properties": { "integrationId": { "type": "string", "description": "Identifier of the provider integration in Novu.", "x-presence": "implicit" }, "active": { "type": "boolean", "description": "Whether the resource is marked active.", "x-presence": "implicit" } } }, "GetProvidersRequest": { "type": "object", "description": "tenant_id and environment derived from auth headers by gateway.", "properties": {} }, "GetProvidersResponse": { "type": "object", "description": "Result payload for reading the configured notification delivery providers.", "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderInfo" }, "description": "Configured notification delivery providers.", "x-presence": "collection" } } }, "ProviderInfo": { "type": "object", "description": "Configured notification provider and its integration identifier and active state.", "properties": { "provider": { "oneOf": [ { "type": "string", "enum": [ "PROVIDER_TYPE_FCM", "PROVIDER_TYPE_APNS", "PROVIDER_TYPE_SENDGRID", "PROVIDER_TYPE_SES", "PROVIDER_TYPE_TWILIO", "PROVIDER_TYPE_SLACK", "PROVIDER_TYPE_DISCORD" ], "x-enumDescriptions": { "PROVIDER_TYPE_FCM": "Firebase Cloud Messaging for device or web push delivery.", "PROVIDER_TYPE_APNS": "Apple Push Notification service for Apple-device push delivery.", "PROVIDER_TYPE_SENDGRID": "SendGrid for email delivery.", "PROVIDER_TYPE_SES": "Amazon Simple Email Service for email delivery.", "PROVIDER_TYPE_TWILIO": "Twilio for SMS delivery.", "PROVIDER_TYPE_SLACK": "Slack for chat-message delivery.", "PROVIDER_TYPE_DISCORD": "Discord for chat-message delivery." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "PROVIDER_TYPE_FCM", "number": 1, "canonical": true, "description": "Firebase Cloud Messaging for device or web push delivery." }, { "name": "PROVIDER_TYPE_APNS", "number": 2, "canonical": true, "description": "Apple Push Notification service for Apple-device push delivery." }, { "name": "PROVIDER_TYPE_SENDGRID", "number": 3, "canonical": true, "description": "SendGrid for email delivery." }, { "name": "PROVIDER_TYPE_SES", "number": 4, "canonical": true, "description": "Amazon Simple Email Service for email delivery." }, { "name": "PROVIDER_TYPE_TWILIO", "number": 5, "canonical": true, "description": "Twilio for SMS delivery." }, { "name": "PROVIDER_TYPE_SLACK", "number": 6, "canonical": true, "description": "Slack for chat-message delivery." }, { "name": "PROVIDER_TYPE_DISCORD", "number": 7, "canonical": true, "description": "Discord for chat-message delivery." } ], "x-enum-description": "Service used to deliver a notification through its selected channel.", "description": "Notification delivery provider being configured or reported.", "x-presence": "implicit" }, "integrationId": { "type": "string", "description": "Identifier of the provider integration in Novu.", "x-presence": "implicit" }, "active": { "type": "boolean", "description": "Whether the resource is marked active.", "x-presence": "implicit" } }, "x-reference-model": { "title": "ProviderInfo", "url": "/api/models/provider-info#response" } }, "CreateWorkflowRequest": { "type": "object", "description": "tenant_id and environment derived from auth headers by gateway.", "properties": { "workflow": { "type": "object", "additionalProperties": true, "description": "Notification workflow definition supplied to or returned by the provider.", "x-presence": "message" } } }, "CreateWorkflowResponse": { "type": "object", "description": "Result payload for registering a notification workflow definition with the provider.", "properties": { "workflow": { "type": "object", "additionalProperties": true, "description": "Notification workflow definition supplied to or returned by the provider.", "x-presence": "message" } } }, "UpdateWorkflowRequest": { "type": "object", "description": "tenant_id and environment derived from auth headers by gateway.", "properties": { "workflowId": { "type": "string", "description": "Identifier of the notification workflow to execute or configure.", "x-presence": "implicit" }, "workflow": { "type": "object", "additionalProperties": true, "description": "Notification workflow definition supplied to or returned by the provider.", "x-presence": "message" } } }, "UpdateWorkflowResponse": { "type": "object", "description": "Result payload for changing a registered notification workflow definition.", "properties": { "workflow": { "type": "object", "additionalProperties": true, "description": "Notification workflow definition supplied to or returned by the provider.", "x-presence": "message" } } }, "GetWorkflowRequest": { "type": "object", "description": "tenant_id and environment derived from auth headers by gateway.", "properties": { "workflowId": { "type": "string", "description": "Identifier of the notification workflow to execute or configure.", "x-presence": "implicit" }, "triggerIdentifier": { "type": "string", "description": "Trigger identifier used to address a notification workflow.", "x-presence": "implicit" } } }, "GetWorkflowResponse": { "type": "object", "description": "Result payload for retrieving a notification workflow by identifier or trigger name.", "properties": { "workflow": { "type": "object", "additionalProperties": true, "description": "Notification workflow definition supplied to or returned by the provider.", "x-presence": "message" } } }, "ListWorkflowsRequest": { "type": "object", "description": "tenant_id and environment derived from auth headers by gateway.", "properties": { "page": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Page number used by this listing operation.", "x-presence": "implicit" }, "pageSize": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100, "description": "Number of entries requested per page. Zero or omission lets the server choose its default.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 100, "gte": 0 } }, "x-validation-scope": "request" } } }, "ListWorkflowsResponse": { "type": "object", "description": "Result payload for paging through available notification workflow definitions.", "properties": { "workflows": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Notification workflow definitions returned by the listing.", "x-presence": "collection" }, "totalCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Total number of matching entries reported by the operation.", "x-presence": "implicit" }, "hasMore": { "type": "boolean", "description": "Whether the listing reports additional entries beyond this page.", "x-presence": "implicit" } } }, "DeleteWorkflowRequest": { "type": "object", "description": "tenant_id and environment derived from auth headers by gateway.", "properties": { "workflowId": { "type": "string", "description": "Identifier of the notification workflow to execute or configure.", "x-presence": "implicit" }, "triggerIdentifier": { "type": "string", "description": "Trigger identifier used to address a notification workflow.", "x-presence": "implicit" } } }, "DeleteWorkflowResponse": { "type": "object", "description": "Result payload for removing an identified notification workflow definition.", "properties": { "workflowId": { "type": "string", "description": "Identifier of the notification workflow to execute or configure.", "x-presence": "implicit" } } }, "GetPendingChangesRequest": { "type": "object", "description": "tenant_id derived from auth headers by gateway.", "properties": {} }, "GetPendingChangesResponse": { "type": "object", "description": "Result payload for listing notification configuration changes awaiting promotion.", "properties": { "changes": { "type": "array", "items": { "$ref": "#/components/schemas/PendingChange" }, "description": "Pending notification configuration changes returned by the provider.", "x-presence": "collection" }, "totalCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Total number of matching entries reported by the operation.", "x-presence": "implicit" } } }, "PendingChange": { "type": "object", "description": "Notification configuration change awaiting promotion to another provider environment.", "properties": { "changeId": { "type": "string", "description": "Identifier of a pending notification configuration change.", "x-presence": "implicit" }, "type": { "type": "string", "description": "Kind of notification resource affected by the pending configuration change.", "x-presence": "implicit" }, "entityName": { "type": "string", "description": "Name of the notification resource affected by the pending change.", "x-presence": "implicit" }, "entityId": { "type": "string", "description": "Identifier of the notification resource affected by the pending change.", "x-presence": "implicit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when this record was created.", "x-presence": "message" }, "createdBy": { "type": "string", "description": "Identifier of the actor that created the pending change.", "x-presence": "implicit" } }, "x-reference-model": { "title": "PendingChange", "url": "/api/models/pending-change#response" } }, "PromoteChangeRequest": { "type": "object", "description": "tenant_id derived from auth headers by gateway.", "properties": { "changeId": { "type": "string", "minLength": 1, "description": "Identifier of a pending notification configuration change.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "changeId" ], "required": [ "changeId" ] }, "PromoteChangeResponse": { "type": "object", "description": "Result payload for promoting a notification configuration change between provider environments.", "properties": { "success": { "type": "boolean", "description": "Whether the operation reports a successful result.", "x-presence": "implicit" }, "productionEntityId": { "type": "string", "description": "Identifier assigned to the promoted resource in the target environment.", "x-presence": "implicit" } } }, "PromoteAllChangesRequest": { "type": "object", "description": "tenant_id derived from auth headers by gateway.", "properties": { "changeIds": { "type": "array", "items": { "type": "string" }, "description": "Identifiers of notification configuration changes selected for promotion.", "x-presence": "collection" } } }, "PromoteAllChangesResponse": { "type": "object", "description": "Result payload for promoting selected notification configuration changes between provider environments.", "properties": { "promotedCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of configuration changes reported promoted.", "x-presence": "implicit" }, "promotedIds": { "type": "array", "items": { "type": "string" }, "description": "Identifiers of configuration changes reported promoted.", "x-presence": "collection" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/PromotionError" }, "description": "Errors reported while processing notification requests.", "x-presence": "collection" } } }, "PromotionError": { "type": "object", "description": "Failure associated with promotion of one notification configuration change.", "properties": { "changeId": { "type": "string", "description": "Identifier of a pending notification configuration change.", "x-presence": "implicit" }, "error": { "type": "string", "description": "Error information reported for this operation or item.", "x-presence": "implicit" } }, "x-reference-model": { "title": "PromotionError", "url": "/api/models/promotion-error#response" } }, "CreateJobRequest": { "type": "object", "description": "Inputs for creating a scheduled job and its trigger settings.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Human-readable name assigned to the scheduled job.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1", "maxLen": "256" } }, "x-validation-scope": "request" }, "description": { "type": "string", "description": "Human-readable explanation of the scheduled job.", "x-presence": "implicit" }, "scheduleType": { "oneOf": [ { "type": "string", "enum": [ "SCHEDULE_TYPE_CRON", "SCHEDULE_TYPE_ONCE", "SCHEDULE_TYPE_RECURRING_INTERVAL" ], "x-enumDescriptions": { "SCHEDULE_TYPE_CRON": "Fire according to the configured cron expression and timezone.", "SCHEDULE_TYPE_ONCE": "Fire once at the configured scheduled timestamp.", "SCHEDULE_TYPE_RECURRING_INTERVAL": "Fire repeatedly at the configured interval in seconds." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "SCHEDULE_TYPE_CRON", "number": 1, "canonical": true, "description": "Fire according to the configured cron expression and timezone." }, { "name": "SCHEDULE_TYPE_ONCE", "number": 2, "canonical": true, "description": "Fire once at the configured scheduled timestamp." }, { "name": "SCHEDULE_TYPE_RECURRING_INTERVAL", "number": 3, "canonical": true, "description": "Fire repeatedly at the configured interval in seconds." } ], "x-enum-description": "Expression format that determines when a scheduled job fires.", "description": "Selects which schedule expression to supply. For SCHEDULE_TYPE_CRON, set\ncron_expression and optionally timezone; for SCHEDULE_TYPE_ONCE, set scheduled_at;\nfor SCHEDULE_TYPE_RECURRING_INTERVAL, set interval_seconds. Supply exactly one\nexpression matching the chosen type.", "x-presence": "implicit" }, "cronExpression": { "type": "string", "maxLength": 128, "pattern": "^$|^@\\w+(\\s.+)?$|^\\S+(\\s+\\S+){4,5}$", "description": "Cron expression evaluated in timezone. Accepts 5 or 6 fields and supported shorthand\nexpressions. Examples: `0 9 * * 1-5` for weekdays at 09:00, `*/15 * * * *` for every\n15 minutes, and `0 0 1 * *` for the first day of each month at midnight.\n`@daily` means `0 0 * * *`; `@hourly` means `0 * * * *`.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "128", "pattern": "^$|^@\\w+(\\s.+)?$|^\\S+(\\s+\\S+){4,5}$" } }, "x-validation-scope": "request" }, "timezone": { "type": "string", "description": "IANA timezone for cron evaluation, such as \"America/New_York\". Defaults to \"UTC\".", "x-presence": "implicit" }, "scheduledAt": { "type": "string", "format": "date-time", "description": "Instant at which a one-time scheduled job should run.", "x-presence": "message" }, "intervalSeconds": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Interval between scheduled triggers, in seconds.", "x-presence": "implicit", "x-protovalidate": { "cel": [ { "id": "interval_seconds.min", "message": "interval_seconds must be 0 (unset) or at least 60", "expression": "this == 0 || this >= 60" } ] }, "x-validation-scope": "request" }, "target": { "description": "Destination and invocation settings for the scheduled job.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ScheduleTargetInput" } ], "x-protovalidate": { "required": true }, "x-validation-scope": "request" }, "retryPolicy": { "description": "Attempt limits and backoff settings for the scheduled target.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/RetryPolicyInput" } ] }, "metadata": { "type": "object", "additionalProperties": true, "description": "Application-defined JSON metadata attached to the scheduled job.", "x-presence": "message" }, "autoPauseThreshold": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Consecutive failure threshold used to pause the scheduled job.", "x-presence": "implicit", "x-protovalidate": { "cel": [ { "id": "auto_pause_threshold.range", "message": "auto_pause_threshold must be 0 (disabled) or in [3, 100]", "expression": "this == 0 || (this >= 3 && this <= 100)" } ] }, "x-validation-scope": "request" }, "ownerSubject": { "type": "string", "description": "Owner subject. When omitted, defaults to the caller derived from headers.", "x-presence": "implicit" }, "externalId": { "type": "string", "maxLength": 255, "description": "Optional client-supplied identifier, unique within (tenant, project)\namong live schedules. Immutable once set. Must not start with \"sched_\".", "x-presence": "implicit", "x-protovalidate": { "cel": [ { "id": "external_id_not_reserved", "message": "external_id must not start with the reserved system-id prefix 'sched_'", "expression": "this == '' || !this.startsWith('sched_')" } ], "string": { "maxLen": "255" } }, "x-validation-scope": "request" } }, "x-request-required": [ "name", "target" ], "required": [ "name", "target" ] }, "ScheduleTargetInput": { "type": "object", "description": "ScheduleTarget describes the HTTP endpoint that receives each job invocation.", "properties": { "url": { "type": "string", "minLength": 1, "format": "uri", "description": "Destination URL. Must be a valid absolute URI.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1", "uri": true } }, "x-validation-scope": "request" }, "method": { "type": "string", "description": "HTTP method to use. Defaults to \"POST\".", "x-presence": "implicit" }, "kind": { "type": "string", "minLength": 1, "description": "Logical kind used for routing and observability (e.g., \"notification\",\n\"llm_conversation\", \"metering\"). Required.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "payload": { "type": "object", "additionalProperties": true, "description": "Arbitrary JSON payload forwarded verbatim to the target.", "x-presence": "message" } }, "x-reference-model": { "title": "ScheduleTarget", "url": "/api/models/schedule-target#request" }, "x-request-required": [ "url", "kind" ], "required": [ "url", "kind" ] }, "RetryPolicyInput": { "type": "object", "description": "RetryPolicy controls how failed executions are retried.", "properties": { "maxAttempts": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum delivery attempts (including the initial attempt). Default 10.", "x-presence": "implicit" }, "initialBackoffMs": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Initial backoff before the first retry, in milliseconds. Default 5000.", "x-presence": "implicit" }, "maxBackoffMs": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum backoff cap, in milliseconds. Default 1800000 (30 min).", "x-presence": "implicit" } }, "x-reference-model": { "title": "RetryPolicy", "url": "/api/models/retry-policy#request" } }, "Schedule": { "type": "object", "description": "Schedule is the canonical representation of a scheduled job.\n\nCreating any schedule type returns the `Schedule` resource directly, with the same shape used by get, pause and resume operations.\n\n[`triggerCount`](/api/models/schedule#response-field-triggercount): Cumulative firings.\n\n[`failureCount`](/api/models/schedule#response-field-failurecount): Cumulative failed first attempts; a later successful retry does not erase the earlier failure.\n\n[`consecutiveFailureCount`](/api/models/schedule#response-field-consecutivefailurecount): Current sequence of failed firings; a successful attempt resets it. This counter drives auto-pause.\n\nZero-valued counters can be omitted. Nonzero 64-bit counters are decimal JSON strings; preserve their integer precision.", "properties": { "scheduleId": { "type": "string", "description": "Server-assigned identifier of the scheduled job, prefixed with \"sched_\".", "x-presence": "implicit" }, "tenantId": { "type": "string", "description": "Identifier of the tenant that owns or scopes this record.", "x-presence": "implicit" }, "projectId": { "type": "string", "description": "Identifier of the project within the tenant that scopes this record.", "x-presence": "implicit" }, "ownerSubject": { "type": "string", "description": "Subject identifier of the owning user or service account.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Human-readable name assigned to the scheduled job.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Human-readable explanation of the scheduled job.", "x-presence": "implicit" }, "scheduleType": { "oneOf": [ { "type": "string", "enum": [ "SCHEDULE_TYPE_CRON", "SCHEDULE_TYPE_ONCE", "SCHEDULE_TYPE_RECURRING_INTERVAL" ], "x-enumDescriptions": { "SCHEDULE_TYPE_CRON": "Fire according to the configured cron expression and timezone.", "SCHEDULE_TYPE_ONCE": "Fire once at the configured scheduled timestamp.", "SCHEDULE_TYPE_RECURRING_INTERVAL": "Fire repeatedly at the configured interval in seconds." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "SCHEDULE_TYPE_CRON", "number": 1, "canonical": true, "description": "Fire according to the configured cron expression and timezone." }, { "name": "SCHEDULE_TYPE_ONCE", "number": 2, "canonical": true, "description": "Fire once at the configured scheduled timestamp." }, { "name": "SCHEDULE_TYPE_RECURRING_INTERVAL", "number": 3, "canonical": true, "description": "Fire repeatedly at the configured interval in seconds." } ], "x-enum-description": "Expression format that determines when a scheduled job fires.", "description": "Schedule type and expression.", "x-presence": "implicit" }, "cronExpression": { "type": "string", "description": "Cron expression. Populated when schedule_type is SCHEDULE_TYPE_CRON.", "x-presence": "implicit" }, "timezone": { "type": "string", "description": "IANA timezone for cron evaluation. Default \"UTC\".", "x-presence": "implicit" }, "scheduledAt": { "type": "string", "format": "date-time", "description": "Exact fire time. Populated when schedule_type is SCHEDULE_TYPE_ONCE.", "x-presence": "message" }, "intervalSeconds": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Interval between firings in seconds. Populated when schedule_type is\nSCHEDULE_TYPE_RECURRING_INTERVAL.", "x-presence": "implicit" }, "target": { "description": "Destination and invocation settings for the scheduled job.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ScheduleTarget" } ] }, "state": { "oneOf": [ { "type": "string", "enum": [ "SCHEDULE_STATUS_ACTIVE", "SCHEDULE_STATUS_PAUSED", "SCHEDULE_STATUS_DELETED" ], "x-enumDescriptions": { "SCHEDULE_STATUS_ACTIVE": "The schedule is active and can trigger at its next matching time.", "SCHEDULE_STATUS_PAUSED": "The schedule is paused and does not trigger until resumed.", "SCHEDULE_STATUS_DELETED": "The schedule has been deleted; this is a schedule condition, not an execution outcome." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "SCHEDULE_STATUS_ACTIVE", "number": 1, "canonical": true, "description": "The schedule is active and can trigger at its next matching time." }, { "name": "SCHEDULE_STATUS_PAUSED", "number": 2, "canonical": true, "description": "The schedule is paused and does not trigger until resumed." }, { "name": "SCHEDULE_STATUS_DELETED", "number": 3, "canonical": true, "description": "The schedule has been deleted; this is a schedule condition, not an execution outcome." } ], "x-enum-description": "Lifecycle condition that determines whether a scheduled job may trigger.", "description": "Lifecycle status controlling whether the scheduled job can trigger.", "x-presence": "implicit" }, "retryPolicy": { "description": "Attempt limits and backoff settings for the scheduled target.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/RetryPolicy" } ] }, "metadata": { "type": "object", "additionalProperties": true, "description": "Application-defined JSON metadata attached to the scheduled job.", "x-presence": "message" }, "autoPauseThreshold": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "If consecutive_failure_count reaches this threshold the job is\nauto-paused (state PAUSED, paused_by_subject \"system:auto-pause\").\n\nIt is compared against consecutive_failure_count, NOT failure_count.\nfailure_count is cumulative for the schedule's whole life, so a healthy\nschedule that collects scattered failures over months would eventually\nexceed any threshold and pause itself forever.\n\n0 disables auto-pause; otherwise must be in the range [3, 100]. Default 10.", "x-presence": "implicit" }, "externalId": { "type": "string", "description": "Client-supplied external id. Echoed back when set; empty otherwise.\nOptional, immutable, unique within (tenant_id, project_id) among live\nschedules. Never starts with the reserved system-id prefix \"sched_\".", "x-presence": "implicit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time at which the scheduled job was created.", "x-presence": "message" }, "createdBySubject": { "type": "string", "description": "Subject identifier recorded when the schedule was created.", "x-presence": "implicit" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time this record was most recently updated.", "x-presence": "message" }, "updatedBySubject": { "type": "string", "description": "Subject identifier recorded when the schedule was last updated.", "x-presence": "implicit" }, "pausedAt": { "type": "string", "format": "date-time", "description": "Time at which the schedule was paused.", "x-presence": "message" }, "pausedBySubject": { "type": "string", "description": "Subject identifier recorded for the schedule pause.", "x-presence": "implicit" }, "pausedReason": { "type": "string", "description": "Explanation recorded for the schedule pause.", "x-presence": "implicit" }, "resumedAt": { "type": "string", "format": "date-time", "description": "Time at which the schedule was most recently resumed.", "x-presence": "message" }, "resumedBySubject": { "type": "string", "description": "Subject identifier recorded for the schedule resume.", "x-presence": "implicit" }, "deletedAt": { "type": "string", "format": "date-time", "description": "Time at which the schedule was deleted.", "x-presence": "message" }, "deletedBySubject": { "type": "string", "description": "Subject identifier recorded for the schedule deletion.", "x-presence": "implicit" }, "lastTriggeredAt": { "type": "string", "format": "date-time", "description": "Time when the schedule was last triggered.", "x-presence": "message" }, "nextTriggerAt": { "type": "string", "format": "date-time", "description": "Time calculated for the next scheduled trigger.", "x-presence": "message" }, "triggerCount": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Scheduled times that ran, cumulative for the schedule's whole life.", "x-presence": "implicit" }, "failureCount": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Scheduled times whose first attempt failed, cumulative for the\nschedule's whole life. A firing that fails on attempt 1 and succeeds on\nretry still counts here — a failure was observed.\n\nThis counter does NOT drive auto-pause. See consecutive_failure_count.", "x-presence": "implicit" }, "consecutiveFailureCount": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Current run of consecutive failed firings. This is the counter\nauto_pause_threshold is compared against.\n\nIncremented when a firing's first attempt fails; reset to 0 as soon as\nany attempt of any firing succeeds. So a firing that fails on attempt 1\nand succeeds on retry has net zero effect here while still advancing\nfailure_count — the target recovered, so the run is over.\n\nA non-success terminal outcome counts as a failure, including a firing\ncancelled on a terminal 4xx.", "x-presence": "implicit" } }, "x-reference-model": { "title": "Schedule", "url": "/api/models/schedule#response" } }, "ScheduleTarget": { "type": "object", "description": "ScheduleTarget describes the HTTP endpoint that receives each job invocation.", "properties": { "url": { "type": "string", "description": "Destination URL. Must be a valid absolute URI.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1", "uri": true } }, "x-validation-scope": "request" }, "method": { "type": "string", "description": "HTTP method to use. Defaults to \"POST\".", "x-presence": "implicit" }, "kind": { "type": "string", "description": "Logical kind used for routing and observability (e.g., \"notification\",\n\"llm_conversation\", \"metering\"). Required.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "payload": { "type": "object", "additionalProperties": true, "description": "Arbitrary JSON payload forwarded verbatim to the target.", "x-presence": "message" } }, "x-reference-model": { "title": "ScheduleTarget", "url": "/api/models/schedule-target#response" }, "x-request-required": [ "url", "kind" ] }, "RetryPolicy": { "type": "object", "description": "RetryPolicy controls how failed executions are retried.", "properties": { "maxAttempts": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum delivery attempts (including the initial attempt). Default 10.", "x-presence": "implicit" }, "initialBackoffMs": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Initial backoff before the first retry, in milliseconds. Default 5000.", "x-presence": "implicit" }, "maxBackoffMs": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum backoff cap, in milliseconds. Default 1800000 (30 min).", "x-presence": "implicit" } }, "x-reference-model": { "title": "RetryPolicy", "url": "/api/models/retry-policy#response" } }, "GetJobRequest": { "type": "object", "description": "Inputs for retrieving a scheduled job and its trigger settings.", "properties": { "scheduleId": { "type": "string", "description": "Identifier of the scheduled job.", "x-presence": "implicit" }, "externalId": { "type": "string", "description": "Caller-assigned correlation identifier for the scheduled job.", "x-presence": "implicit" } }, "x-protovalidate": { "cel": [ { "id": "exactly_one_ref", "message": "provide exactly one of schedule_id or external_id", "expression": "(this.schedule_id != '') != (this.external_id != '')" } ] }, "x-validation-scope": "request" }, "ListJobsRequest": { "type": "object", "description": "Inputs for listing scheduled jobs and their trigger settings.", "properties": { "pageSize": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100, "description": "Number of entries requested per page. Zero or omission lets the server choose its default.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 100, "gte": 0 } }, "x-validation-scope": "request" }, "pageToken": { "type": "string", "description": "Continuation token from a previous response; leave empty to start the listing.", "x-presence": "implicit" }, "stateFilter": { "oneOf": [ { "type": "string", "enum": [ "SCHEDULE_STATUS_ACTIVE", "SCHEDULE_STATUS_PAUSED", "SCHEDULE_STATUS_DELETED" ], "x-enumDescriptions": { "SCHEDULE_STATUS_ACTIVE": "The schedule is active and can trigger at its next matching time.", "SCHEDULE_STATUS_PAUSED": "The schedule is paused and does not trigger until resumed.", "SCHEDULE_STATUS_DELETED": "The schedule has been deleted; this is a schedule condition, not an execution outcome." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "SCHEDULE_STATUS_ACTIVE", "number": 1, "canonical": true, "description": "The schedule is active and can trigger at its next matching time." }, { "name": "SCHEDULE_STATUS_PAUSED", "number": 2, "canonical": true, "description": "The schedule is paused and does not trigger until resumed." }, { "name": "SCHEDULE_STATUS_DELETED", "number": 3, "canonical": true, "description": "The schedule has been deleted; this is a schedule condition, not an execution outcome." } ], "x-enum-description": "Lifecycle condition that determines whether a scheduled job may trigger.", "description": "Schedule lifecycle status used to restrict the job listing.", "x-presence": "implicit" }, "targetKindFilter": { "type": "string", "description": "Target kind used to restrict the scheduled job listing.", "x-presence": "implicit" } } }, "ListJobsResponse": { "type": "object", "description": "Result of listing scheduled jobs and their trigger settings.", "properties": { "schedules": { "type": "array", "items": { "$ref": "#/components/schemas/Schedule" }, "description": "Scheduled jobs included in this result page.", "x-presence": "collection" }, "nextPageToken": { "type": "string", "description": "Opaque cursor token for the next page. Empty when no further pages exist.", "x-presence": "implicit" }, "totalCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Total number of records reported for this listing.", "x-presence": "implicit" } } }, "UpdateJobRequest": { "type": "object", "description": "Inputs for updating a scheduled job and its trigger settings.", "properties": { "scheduleId": { "type": "string", "description": "Identifier of the scheduled job.", "x-presence": "implicit" }, "name": { "type": "string", "maxLength": 256, "description": "Human-readable name assigned to the scheduled job.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "256" } }, "x-validation-scope": "request" }, "description": { "type": "string", "description": "Human-readable explanation of the scheduled job.", "x-presence": "implicit" }, "cronExpression": { "type": "string", "maxLength": 128, "pattern": "^$|^@\\w+(\\s.+)?$|^\\S+(\\s+\\S+){4,5}$", "description": "Cron expression defining when the scheduled job runs.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "128", "pattern": "^$|^@\\w+(\\s.+)?$|^\\S+(\\s+\\S+){4,5}$" } }, "x-validation-scope": "request" }, "timezone": { "type": "string", "description": "IANA time zone associated with the record or schedule.", "x-presence": "implicit" }, "scheduledAt": { "type": "string", "format": "date-time", "description": "Instant at which a one-time scheduled job should run.", "x-presence": "message" }, "intervalSeconds": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Interval between scheduled triggers, in seconds.", "x-presence": "implicit", "x-protovalidate": { "cel": [ { "id": "interval_seconds.min", "message": "interval_seconds must be 0 (no change) or at least 60", "expression": "this == 0 || this >= 60" } ] }, "x-validation-scope": "request" }, "target": { "description": "Destination and invocation settings for the scheduled job.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ScheduleTargetInput" } ] }, "retryPolicy": { "description": "Attempt limits and backoff settings for the scheduled target.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/RetryPolicyInput" } ] }, "metadata": { "type": "object", "additionalProperties": true, "description": "Application-defined JSON metadata attached to the scheduled job.", "x-presence": "message" }, "autoPauseThreshold": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Consecutive failure threshold used to pause the scheduled job.", "x-presence": "implicit", "x-protovalidate": { "cel": [ { "id": "auto_pause_threshold.range", "message": "auto_pause_threshold must be 0 (disabled) or in [3, 100]", "expression": "this == 0 || (this >= 3 && this <= 100)" } ] }, "x-validation-scope": "request" }, "externalId": { "type": "string", "description": "Lookup reference only. Exactly one of schedule_id / external_id must be set.", "x-presence": "implicit" } }, "x-protovalidate": { "cel": [ { "id": "exactly_one_ref", "message": "provide exactly one of schedule_id or external_id", "expression": "(this.schedule_id != '') != (this.external_id != '')" } ] }, "x-validation-scope": "request" }, "UpdateJobResponse": { "type": "object", "description": "UpdateJob keeps a dedicated response wrapper (rather than the bare Schedule\nthe other mutations return) because it carries response-only metadata that\nis not part of the persisted resource.", "properties": { "schedule": { "description": "Scheduled job returned by the operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/Schedule" } ] }, "effectiveAt": { "type": "string", "description": "When the update takes effect. Current updates return immediate; next_resync and\nnext_worker_deployment are legacy values that are no longer emitted. The returned schedule’s\nnext_trigger_at identifies its next firing.", "x-presence": "implicit" } } }, "PauseJobRequest": { "type": "object", "description": "Inputs for pausing a scheduled job and its trigger settings.", "properties": { "scheduleId": { "type": "string", "description": "Identifier of the scheduled job.", "x-presence": "implicit" }, "reason": { "type": "string", "description": "Explanation recorded for pausing the scheduled job.", "x-presence": "implicit" }, "externalId": { "type": "string", "description": "Caller-assigned correlation identifier for the scheduled job.", "x-presence": "implicit" } }, "x-protovalidate": { "cel": [ { "id": "exactly_one_ref", "message": "provide exactly one of schedule_id or external_id", "expression": "(this.schedule_id != '') != (this.external_id != '')" } ] }, "x-validation-scope": "request" }, "ResumeJobRequest": { "type": "object", "description": "Inputs for resuming a scheduled job and its trigger settings.", "properties": { "scheduleId": { "type": "string", "description": "Identifier of the scheduled job.", "x-presence": "implicit" }, "externalId": { "type": "string", "description": "Caller-assigned correlation identifier for the scheduled job.", "x-presence": "implicit" } }, "x-protovalidate": { "cel": [ { "id": "exactly_one_ref", "message": "provide exactly one of schedule_id or external_id", "expression": "(this.schedule_id != '') != (this.external_id != '')" } ] }, "x-validation-scope": "request" }, "DeleteJobRequest": { "type": "object", "description": "Inputs for deleting a scheduled job and its trigger settings.", "properties": { "scheduleId": { "type": "string", "description": "Identifier of the scheduled job.", "x-presence": "implicit" }, "externalId": { "type": "string", "description": "Caller-assigned correlation identifier for the scheduled job.", "x-presence": "implicit" } }, "x-protovalidate": { "cel": [ { "id": "exactly_one_ref", "message": "provide exactly one of schedule_id or external_id", "expression": "(this.schedule_id != '') != (this.external_id != '')" } ] }, "x-validation-scope": "request" }, "DeleteJobResponse": { "type": "object", "description": "Result of deleting a scheduled job and its trigger settings.", "properties": { "scheduleId": { "type": "string", "description": "Identifier of the scheduled job.", "x-presence": "implicit" } } }, "DeleteJobsForProjectRequest": { "type": "object", "description": "Tenant/project come from the ingress headers — the request body carries no\nfields.", "properties": {} }, "DeleteJobsForProjectResponse": { "type": "object", "description": "Result of deleting scheduled jobs within the selected project.", "properties": { "deletedCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of scheduled jobs deleted by the operation.", "x-presence": "implicit" } } }, "DeleteJobsForOwnerRequest": { "type": "object", "description": "Tenant/project come from the ingress headers. The owner is the caller\nitself (derived from x-user-id) — there are no body fields.", "properties": {} }, "DeleteJobsForOwnerResponse": { "type": "object", "description": "Result of deleting scheduled jobs belonging to the selected owner.", "properties": { "deletedCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of scheduled jobs deleted by the operation.", "x-presence": "implicit" } } }, "ListExecutionsRequest": { "type": "object", "description": "Inputs for listing the execution history of a scheduled job.", "properties": { "scheduleId": { "type": "string", "minLength": 1, "description": "Identifier of the scheduled job.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "pageSize": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100, "description": "Number of entries requested per page. Zero or omission lets the server choose its default.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 100, "gte": 0 } }, "x-validation-scope": "request" }, "pageToken": { "type": "string", "description": "Continuation token from a previous response; leave empty to start the listing.", "x-presence": "implicit" }, "statusFilter": { "oneOf": [ { "type": "string", "enum": [ "EXECUTION_STATUS_COMPLETED", "EXECUTION_STATUS_FAILED", "EXECUTION_STATUS_CANCELLED" ], "x-enumDescriptions": { "EXECUTION_STATUS_COMPLETED": "The scheduled HTTP dispatch received a status below 400; this does not establish completion of\ndownstream asynchronous work.", "EXECUTION_STATUS_FAILED": "The firing failed, including exhausted delivery attempts; inspect end_reason.", "EXECUTION_STATUS_CANCELLED": "The firing was cancelled rather than completed, for example by an operator or a non-HTTP\ncancellation condition." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "EXECUTION_STATUS_COMPLETED", "number": 1, "canonical": true, "description": "The scheduled HTTP dispatch received a status below 400; this does not establish completion of\ndownstream asynchronous work." }, { "name": "EXECUTION_STATUS_FAILED", "number": 2, "canonical": true, "description": "The firing failed, including exhausted delivery attempts; inspect end_reason." }, { "name": "EXECUTION_STATUS_CANCELLED", "number": 5, "canonical": true, "description": "The firing was cancelled rather than completed, for example by an operator or a non-HTTP\ncancellation condition." } ], "x-enum-description": "Terminal result of one scheduled-job firing; end_reason gives the reason for a non-successful\nresult.", "description": "Execution status used to restrict the execution history.", "x-presence": "implicit" } }, "x-request-required": [ "scheduleId" ], "required": [ "scheduleId" ] }, "ListExecutionsResponse": { "type": "object", "description": "Result of listing the execution history of a scheduled job.", "properties": { "executions": { "type": "array", "items": { "$ref": "#/components/schemas/Execution" }, "description": "Scheduled execution records included in this result page.", "x-presence": "collection" }, "nextPageToken": { "type": "string", "description": "Opaque cursor token for the next page. Empty when no further pages exist.", "x-presence": "implicit" } } }, "Execution": { "type": "object", "description": "Execution is a single firing record for a scheduled job.\n\nExecution records include:\n\n[`status`](/api/models/execution#response-field-status): `EXECUTION_STATUS_COMPLETED`, `EXECUTION_STATUS_FAILED`, or `EXECUTION_STATUS_CANCELLED` (cancellation, including operator or non-HTTP cancellation conditions).\n\n[`endReason`](/api/models/execution#response-field-endreason): Why a `FAILED` run failed, when the status alone does not say. `\"discarded\"` means the job exhausted [`maxAttempts`](/api/models/retry-policy#request-field-maxattempts) and will not be retried. Empty otherwise.\n\n[`httpStatus`](/api/models/execution#response-field-httpstatus): HTTP status code returned by the target.\n\n[`attempt`](/api/models/execution#response-field-attempt): Attempt number (1-based) within this firing.\n\n[`durationMs`](/api/models/execution#response-field-durationms): End-to-end duration of the delivery attempt.\n\n[`error`](/api/models/execution#response-field-error): Error message on `FAILED` outcomes.\n\n[`scheduledTime`](/api/models/execution#response-field-scheduledtime): When the execution was supposed to fire.\n\n[`startedAt`](/api/models/execution#response-field-startedat) / [`completedAt`](/api/models/execution#response-field-completedat): Actual start and completion times.\n\n[`responseBody`](/api/models/execution#response-field-responsebody): Truncated HTTP response body captured on failed dispatches (4 KiB cap). Empty for successful dispatches.\n\n[`responseHeaders`](/api/models/execution#response-field-responseheaders): Allowlisted response headers from the failed dispatch: `content-type`, `content-length`, `retry-after`, `x-request-id`, `date`.\n\n[`responseTruncated`](/api/models/execution#response-field-responsetruncated): `true` when [`responseBody`](/api/models/execution#response-field-responsebody) was clipped at the 4 KiB cap.\n\n[`responseSizeBytes`](/api/models/execution#response-field-responsesizebytes): Original response size in bytes (from `Content-Length` when present, else total bytes read before truncation).", "properties": { "executionId": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Identifier of the scheduled job execution record.", "x-presence": "implicit" }, "scheduleId": { "type": "string", "description": "Identifier of the scheduled job.", "x-presence": "implicit" }, "tenantId": { "type": "string", "description": "Identifier of the tenant that owns or scopes this record.", "x-presence": "implicit" }, "projectId": { "type": "string", "description": "Identifier of the project within the tenant that scopes this record.", "x-presence": "implicit" }, "scheduledTime": { "type": "string", "format": "date-time", "description": "Instant for which this execution or trigger was scheduled.", "x-presence": "message" }, "startedAt": { "type": "string", "format": "date-time", "description": "Time at which the subscription or execution started.", "x-presence": "message" }, "completedAt": { "type": "string", "format": "date-time", "description": "Time at which the scheduled execution completed.", "x-presence": "message" }, "status": { "oneOf": [ { "type": "string", "enum": [ "EXECUTION_STATUS_COMPLETED", "EXECUTION_STATUS_FAILED", "EXECUTION_STATUS_CANCELLED" ], "x-enumDescriptions": { "EXECUTION_STATUS_COMPLETED": "The scheduled HTTP dispatch received a status below 400; this does not establish completion of\ndownstream asynchronous work.", "EXECUTION_STATUS_FAILED": "The firing failed, including exhausted delivery attempts; inspect end_reason.", "EXECUTION_STATUS_CANCELLED": "The firing was cancelled rather than completed, for example by an operator or a non-HTTP\ncancellation condition." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "EXECUTION_STATUS_COMPLETED", "number": 1, "canonical": true, "description": "The scheduled HTTP dispatch received a status below 400; this does not establish completion of\ndownstream asynchronous work." }, { "name": "EXECUTION_STATUS_FAILED", "number": 2, "canonical": true, "description": "The firing failed, including exhausted delivery attempts; inspect end_reason." }, { "name": "EXECUTION_STATUS_CANCELLED", "number": 5, "canonical": true, "description": "The firing was cancelled rather than completed, for example by an operator or a non-HTTP\ncancellation condition." } ], "x-enum-description": "Terminal result of one scheduled-job firing; end_reason gives the reason for a non-successful\nresult.", "description": "Execution outcome recorded for this scheduled attempt.", "x-presence": "implicit" }, "httpStatus": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "HTTP status code returned by the target.", "x-presence": "implicit" }, "attempt": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Attempt number (1-based).", "x-presence": "implicit" }, "durationMs": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "End-to-end duration in milliseconds.", "x-presence": "implicit" }, "targetKind": { "type": "string", "description": "Kind of target invoked by the scheduled execution.", "x-presence": "implicit" }, "error": { "type": "string", "description": "Error message when status is FAILED.", "x-presence": "implicit" }, "riverJobId": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Identifier of the underlying queue job that produced this scheduled execution, for correlating\nexecution diagnostics.", "x-presence": "implicit" }, "responseBody": { "type": "string", "description": "Truncated HTTP response body captured on failed dispatches. Empty for\nsuccessful dispatches by design — only error responses are stored. May\nalso be empty for binary content types or transport-level errors (see\nresponse_size_bytes / error).", "x-presence": "implicit" }, "responseHeaders": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Allowlisted response headers from the failed dispatch. Allowlist:\ncontent-type, content-length, retry-after, x-request-id, date.", "x-presence": "collection" }, "responseTruncated": { "type": "boolean", "description": "True when response_body was clipped at the 4 KiB cap.", "x-presence": "implicit" }, "responseSizeBytes": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Original response size in bytes (from Content-Length when present,\nelse total bytes read before truncation).", "x-presence": "implicit" }, "endReason": { "type": "string", "description": "Explanation of an execution failure when status alone is insufficient, such as discarded after\nretry attempts were exhausted. Empty when there is no additional reason.", "x-presence": "implicit" } }, "x-reference-model": { "title": "Execution", "url": "/api/models/execution#response" } }, "PutSecretRequest": { "type": "object", "description": "Inputs for writing a project secret and its metadata.", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,62}$", "description": "Name identifying the secret within its project.", "x-presence": "implicit", "x-protovalidate": { "string": { "pattern": "^[a-z0-9][a-z0-9._-]{0,62}$" } }, "x-validation-scope": "request" }, "value": { "type": "string", "minLength": 1, "description": "Secret value, limited to 64 KiB of UTF-8 bytes. Binary material is supplied as base64 by\ncaller convention. Read operations return metadata without the secret value.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1", "maxBytes": "65536" } }, "x-validation-scope": "request" }, "description": { "type": "string", "maxLength": 1024, "description": "Human-readable explanation of the secret.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "1024" } }, "x-validation-scope": "request" }, "labels": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Free-form labels used to organize and identify secrets.", "x-presence": "collection" } }, "x-request-required": [ "name", "value" ], "required": [ "name", "value" ] }, "PutSecretResponse": { "type": "object", "description": "Stored metadata returned after writing a project secret; the secret value is not returned.", "properties": { "metadata": { "description": "Stored secret metadata; the secret value is not returned.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/SecretMetadata" } ] } } }, "SecretMetadata": { "type": "object", "description": "SecretMetadata is the only thing read APIs return. No message in this file\ncarries a secret value out of the service.", "properties": { "name": { "type": "string", "description": "Name identifying the secret within its project.", "x-presence": "implicit" }, "projectId": { "type": "string", "description": "Identifier of the project within the tenant that scopes this record. \"default\" until Projects\nships.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Human-readable explanation of the secret.", "x-presence": "implicit" }, "labels": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Free-form labels used to organize and identify secrets. Free-form, e.g. {\"kind\": \"mcp-auth\"}.", "x-presence": "collection" }, "version": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Version number of the stored secret metadata. Increments on every PutSecret.", "x-presence": "implicit" }, "createdBy": { "type": "string", "description": "Subject identifier recorded for the creator of this record. Subject from the X-User-ID header,\nwhen present.", "x-presence": "implicit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time this record was created.", "x-presence": "message" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time this record was most recently updated.", "x-presence": "message" } }, "x-reference-model": { "title": "SecretMetadata", "url": "/api/models/secret-metadata#response" } }, "GetSecretMetadataRequest": { "type": "object", "description": "Selects a project secret whose metadata is returned without its value.", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,62}$", "description": "Name identifying the secret within its project.", "x-presence": "implicit", "x-protovalidate": { "string": { "pattern": "^[a-z0-9][a-z0-9._-]{0,62}$" } }, "x-validation-scope": "request" } }, "x-request-required": [ "name" ], "required": [ "name" ] }, "GetSecretMetadataResponse": { "type": "object", "description": "Result of retrieving metadata for a project secret without its secret value.", "properties": { "metadata": { "description": "Stored secret metadata; the secret value is not returned.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/SecretMetadata" } ] } } }, "ListSecretsRequest": { "type": "object", "description": "Pagination settings for listing secret metadata within the current project.", "properties": { "page": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 2147483647, "description": "Page number requested from the backing service.", "x-presence": "implicit", "x-protovalidate": { "int32": { "gte": 0 } }, "x-validation-scope": "request" }, "pageSize": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100, "description": "Number of secret metadata entries requested per page. Zero or omission lets the server choose\nthe page size.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 100, "gte": 0 } }, "x-validation-scope": "request" } } }, "ListSecretsResponse": { "type": "object", "description": "Page of metadata for project secrets, without their values.", "properties": { "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/SecretMetadata" }, "description": "Secret metadata records returned by the listing; secret values are excluded.", "x-presence": "collection" }, "total": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Total number of records reported for this listing.", "x-presence": "implicit" } } }, "DeleteSecretRequest": { "type": "object", "description": "Selects a project secret to delete and whether to override reference checks.", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,62}$", "description": "Name identifying the secret within its project.", "x-presence": "implicit", "x-protovalidate": { "string": { "pattern": "^[a-z0-9][a-z0-9._-]{0,62}$" } }, "x-validation-scope": "request" }, "force": { "type": "boolean", "description": "Delete even when custom MCP servers still reference this secret. Those\nservers then fail closed the next time they try to resolve it.", "x-presence": "implicit" } }, "x-request-required": [ "name" ], "required": [ "name" ] }, "DeleteSecretResponse": { "type": "object", "description": "Result of deleting a project secret.", "properties": { "deleted": { "type": "boolean", "description": "False when the secret did not exist; the call still succeeds.", "x-presence": "implicit" } } }, "CreateFolderRequest": { "type": "object", "description": "Inputs for creating a folder entry in the user’s storage namespace.", "properties": { "folderPath": { "type": "string", "description": "Path of the folder within the user’s storage namespace.", "x-presence": "implicit" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional attributes associated with the resource.", "x-presence": "collection" } } }, "CreateFolderResponse": { "type": "object", "description": "Result payload for creating a folder entry in the user’s storage namespace.", "properties": { "folder": { "description": "Metadata for the folder affected by the operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/FolderInfo" } ] }, "created": { "type": "boolean", "description": "Whether this operation created a new folder.", "x-presence": "implicit" } } }, "FolderInfo": { "type": "object", "description": "FolderInfo contains metadata about a folder", "properties": { "folderId": { "type": "string", "description": "Unique folder ID.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Name of the folder within its parent folder.", "x-presence": "implicit" }, "path": { "type": "string", "description": "Full path (e.g., \"/documents/work\").", "x-presence": "implicit" }, "parentPath": { "type": "string", "description": "Parent folder path.", "x-presence": "implicit" }, "createdAt": { "type": "string", "description": "RFC3339 timestamp.", "x-presence": "implicit" }, "modifiedAt": { "type": "string", "description": "RFC3339 timestamp.", "x-presence": "implicit" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom metadata.", "x-presence": "collection" }, "fileCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of files (direct children).", "x-presence": "implicit" }, "subfolderCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of subfolders.", "x-presence": "implicit" }, "totalSizeBytes": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Total size of all files in folder (recursive).", "x-presence": "implicit" } }, "x-reference-model": { "title": "FolderInfo", "url": "/api/models/folder-info#response" } }, "DeleteFolderRequest": { "type": "object", "description": "Inputs for removing a folder entry and optionally its descendant content.", "properties": { "folderPath": { "type": "string", "description": "Path of the folder within the user’s storage namespace.", "x-presence": "implicit" }, "recursive": { "type": "boolean", "description": "Whether the operation includes descendant folders and their contents.", "x-presence": "implicit" } } }, "DeleteFolderResponse": { "type": "object", "description": "Result payload for removing a folder entry and optionally its descendant content.", "properties": { "deleted": { "type": "boolean", "description": "Whether the deletion operation reports the resource removed.", "x-presence": "implicit" }, "filesDeleted": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of files reported deleted by the operation.", "x-presence": "implicit" }, "foldersDeleted": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of folders reported deleted by the operation.", "x-presence": "implicit" } } }, "ListFilesRequest": { "type": "object", "description": "Inputs for paging through files and subfolders with metadata filters.", "properties": { "folderPath": { "type": "string", "description": "Path of the folder within the user’s storage namespace.", "x-presence": "implicit" }, "recursive": { "type": "boolean", "description": "Whether the operation includes descendant folders and their contents.", "x-presence": "implicit" }, "pageSize": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum number of entries requested per page.", "x-presence": "implicit" }, "pageToken": { "type": "string", "description": "Continuation token from a preceding page of results.", "x-presence": "implicit" }, "filter": { "description": "Selection criteria applied to the listing.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/FileFilter" } ] } } }, "FileFilter": { "type": "object", "description": "Name, extension, tag, size, and upload-time criteria selecting stored files.", "properties": { "extensions": { "type": "array", "items": { "type": "string" }, "description": "File extensions used to restrict matching files.", "x-presence": "collection" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Labels associated with the resource for organization or filtering.", "x-presence": "collection" }, "minSizeBytes": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Minimum file size included by the filter, in bytes.", "x-presence": "implicit" }, "maxSizeBytes": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Maximum file size included by the filter, in bytes.", "x-presence": "implicit" }, "uploadedAfter": { "type": "string", "description": "Lower timestamp bound for files selected by upload time.", "x-presence": "implicit" }, "uploadedBefore": { "type": "string", "description": "Upper timestamp bound for files selected by upload time.", "x-presence": "implicit" }, "nameContains": { "type": "string", "description": "Text that must occur in the selected file’s name.", "x-presence": "implicit" } }, "x-reference-model": { "title": "FileFilter", "url": "/api/models/file-filter#request" } }, "ListFilesResponse": { "type": "object", "description": "Result payload for paging through files and subfolders with metadata filters.", "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/FileInfo" }, "description": "File metadata records returned by the listing or search.", "x-presence": "collection" }, "folders": { "type": "array", "items": { "$ref": "#/components/schemas/FolderInfo" }, "description": "Folder metadata records returned by the listing.", "x-presence": "collection" }, "nextPageToken": { "type": "string", "description": "Continuation token returned for retrieving the next page.", "x-presence": "implicit" }, "totalCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Total number of matching entries reported by the operation.", "x-presence": "implicit" } } }, "FileInfo": { "type": "object", "description": "FileInfo contains metadata about a file", "properties": { "fileId": { "type": "string", "description": "Stable identifier of the stored file.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Name of the file within its containing folder.", "x-presence": "implicit" }, "path": { "type": "string", "description": "Full path (e.g., \"/documents/report.pdf\").", "x-presence": "implicit" }, "folderPath": { "type": "string", "description": "Parent folder path.", "x-presence": "implicit" }, "sizeBytes": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Size of the file content, in bytes.", "x-presence": "implicit" }, "contentType": { "type": "string", "description": "Media type describing the file or response body.", "x-presence": "implicit" }, "uploadedAt": { "type": "string", "description": "RFC3339 timestamp.", "x-presence": "implicit" }, "modifiedAt": { "type": "string", "description": "RFC3339 timestamp.", "x-presence": "implicit" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom metadata.", "x-presence": "collection" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "User-defined tags.", "x-presence": "collection" }, "description": { "type": "string", "description": "Optional description.", "x-presence": "implicit" }, "storageRef": { "description": "Reference to actual storage location.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ObjectRef" } ] }, "checksum": { "type": "string", "description": "File checksum (SHA256).", "x-presence": "implicit" }, "version": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Version number (for versioning support).", "x-presence": "implicit" } }, "x-reference-model": { "title": "FileInfo", "url": "/api/models/file-info#response" } }, "ObjectRef": { "type": "object", "description": "ObjectRef references an object in storage", "properties": { "bucket": { "type": "string", "description": "Storage bucket containing the object.", "x-presence": "implicit" }, "key": { "type": "string", "description": "Object key within the selected storage bucket.", "x-presence": "implicit" }, "provider": { "oneOf": [ { "type": "string", "enum": [ "STORAGE_PROVIDER_GCS", "STORAGE_PROVIDER_S3", "STORAGE_PROVIDER_FILESYSTEM", "STORAGE_PROVIDER_AZURE_BLOB" ], "x-enumDescriptions": { "STORAGE_PROVIDER_GCS": "Google Cloud Storage.", "STORAGE_PROVIDER_S3": "Amazon S3 or a storage service implementing the S3 interface.", "STORAGE_PROVIDER_FILESYSTEM": "A filesystem accessible to the storage service.", "STORAGE_PROVIDER_AZURE_BLOB": "Azure Blob Storage." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "STORAGE_PROVIDER_GCS", "number": 1, "canonical": true, "description": "Google Cloud Storage." }, { "name": "STORAGE_PROVIDER_S3", "number": 2, "canonical": true, "description": "Amazon S3 or a storage service implementing the S3 interface." }, { "name": "STORAGE_PROVIDER_FILESYSTEM", "number": 3, "canonical": true, "description": "A filesystem accessible to the storage service." }, { "name": "STORAGE_PROVIDER_AZURE_BLOB", "number": 4, "canonical": true, "description": "Azure Blob Storage." } ], "x-enum-description": "Backend that stores the file bytes associated with a storage record.", "description": "Storage provider used to access the object.", "x-presence": "implicit" } }, "x-reference-model": { "title": "ObjectRef", "url": "/api/models/object-ref#response" } }, "UploadFileRequest": { "type": "object", "description": "Inputs for uploading file content and recording its metadata in the selected folder.", "properties": { "folderPath": { "type": "string", "description": "Path of the folder within the user’s storage namespace.", "x-presence": "implicit" }, "fileName": { "type": "string", "description": "File name to use within the selected folder.", "x-presence": "implicit" }, "content": { "type": "string", "format": "byte", "description": "Raw bytes of the object being uploaded or downloaded.", "x-presence": "implicit" }, "contentType": { "type": "string", "description": "Media type describing the file or response body.", "x-presence": "implicit" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional attributes associated with the resource.", "x-presence": "collection" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Labels associated with the resource for organization or filtering.", "x-presence": "collection" } } }, "UploadFileResponse": { "type": "object", "description": "Result payload for uploading file content and recording its metadata in the selected folder.", "properties": { "file": { "description": "Metadata for the file affected or retrieved by the operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/FileInfo" } ] }, "uploaded": { "type": "boolean", "description": "Whether the file upload operation reports completion.", "x-presence": "implicit" } } }, "DeleteFileRequest": { "type": "object", "description": "Inputs for removing a stored file and its tracked metadata.", "properties": { "fileId": { "type": "string", "description": "Stable identifier of the stored file.", "x-presence": "implicit" } } }, "DeleteFileResponse": { "type": "object", "description": "Result payload for removing a stored file and its tracked metadata.", "properties": { "deleted": { "type": "boolean", "description": "Whether the deletion operation reports the resource removed.", "x-presence": "implicit" }, "spaceFreedBytes": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Storage capacity reported freed by deletion, in bytes.", "x-presence": "implicit" } } }, "MoveFileRequest": { "type": "object", "description": "MoveFileRequest moves/renames a file (identity is the file_id; path is a label)", "properties": { "fileId": { "type": "string", "description": "Stable identifier of the stored file.", "x-presence": "implicit" }, "destinationFolder": { "type": "string", "description": "Destination folder path for the file move.", "x-presence": "implicit" }, "newName": { "type": "string", "description": "Replacement file name for the moved file. Omit to preserve its current name.", "x-presence": "implicit" } } }, "MoveFileResponse": { "type": "object", "description": "Result payload for changing a stored file’s folder location and optional name.", "properties": { "file": { "description": "Metadata for the file affected or retrieved by the operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/FileInfo" } ] }, "moved": { "type": "boolean", "description": "Whether the file move operation reports completion.", "x-presence": "implicit" } } }, "SearchFilesRequest": { "type": "object", "description": "Inputs for finding stored files by query text and metadata constraints.", "properties": { "query": { "type": "string", "description": "Search expression used to select matching entries.", "x-presence": "implicit" }, "filter": { "description": "Selection criteria applied to the listing.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/FileFilter" } ] }, "maxResults": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum number of file matches requested.", "x-presence": "implicit" } } }, "SearchFilesResponse": { "type": "object", "description": "Result payload for finding stored files by query text and metadata constraints.", "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/FileInfo" }, "description": "File metadata records returned by the listing or search.", "x-presence": "collection" }, "totalMatches": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of files reported to match the search criteria.", "x-presence": "implicit" } } }, "GetFileMetadataRequest": { "type": "object", "description": "Inputs for reading a stored file’s attributes without downloading its content.", "properties": { "fileId": { "type": "string", "description": "Stable identifier of the stored file.", "x-presence": "implicit" } } }, "GetFileMetadataResponse": { "type": "object", "description": "Result payload for reading a stored file’s attributes without downloading its content.", "properties": { "file": { "description": "Metadata for the file affected or retrieved by the operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/FileInfo" } ] } } }, "UpdateFileMetadataRequest": { "type": "object", "description": "Inputs for changing labels, description, or custom attributes of a stored file.", "properties": { "fileId": { "type": "string", "description": "Stable identifier of the stored file.", "x-presence": "implicit" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional attributes associated with the resource.", "x-presence": "collection" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Labels associated with the resource for organization or filtering.", "x-presence": "collection" }, "description": { "type": "string", "description": "Human-readable description of the resource.", "x-presence": "implicit" } } }, "UpdateFileMetadataResponse": { "type": "object", "description": "Result payload for changing labels, description, or custom attributes of a stored file.", "properties": { "file": { "description": "Metadata for the file affected or retrieved by the operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/FileInfo" } ] }, "updated": { "type": "boolean", "description": "Whether the file metadata update reports a change.", "x-presence": "implicit" } } }, "GenerateUploadUrlRequest": { "type": "object", "description": "Inputs for issuing a signed URL for a direct file upload.", "properties": { "folderPath": { "type": "string", "description": "Path of the folder within the user’s storage namespace.", "x-presence": "implicit" }, "fileName": { "type": "string", "description": "File name to use within the selected folder.", "x-presence": "implicit" }, "contentType": { "type": "string", "description": "Media type describing the file or response body.", "x-presence": "implicit" }, "expiresSeconds": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Requested lifetime of the signed URL, in seconds.", "x-presence": "implicit" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional attributes associated with the resource.", "x-presence": "collection" }, "sizeBytes": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Declared upload size in bytes. Required (> 0): pre-checked against quota and\nbound into the signed URL via x-goog-content-length-range so GCS itself\nrejects larger uploads.", "x-presence": "implicit", "x-protovalidate": { "int64": { "gt": "0" } }, "x-validation-scope": "request" } }, "x-request-required": [ "sizeBytes" ], "required": [ "sizeBytes" ] }, "GenerateUploadUrlResponse": { "type": "object", "description": "Result payload for issuing a signed URL for a direct file upload.", "properties": { "url": { "type": "string", "description": "URL associated with the resource or outbound request.", "x-presence": "implicit" }, "fileId": { "type": "string", "description": "Stable identifier of the stored file.", "x-presence": "implicit" }, "fullPath": { "type": "string", "description": "Complete object path allocated for the upload.", "x-presence": "implicit" }, "requiredHeaders": { "type": "object", "additionalProperties": { "type": "string" }, "description": "HTTP headers the client must send with the signed upload request.", "x-presence": "collection" } } }, "RegisterUploadedFileRequest": { "type": "object", "description": "RegisterUploadedFileRequest completes the signed-URL upload flow (step 3 of 3):\nafter PUTting bytes to the URL from GenerateUploadUrl, register the object so it\nbecomes visible to ListFiles/GetFileMetadata/GenerateDownloadUrl.", "properties": { "fileId": { "type": "string", "pattern": "^[a-f0-9]{32}$", "description": "file_id returned by GenerateUploadUrl (32 lowercase hex chars). The GCS key is\nrecomputed server-side from the caller-scoped folder_path + file_id, so a\ncaller can only ever register objects under its own prefix.", "x-presence": "implicit", "x-protovalidate": { "string": { "pattern": "^[a-f0-9]{32}$" } }, "x-validation-scope": "request" }, "folderPath": { "type": "string", "description": "Must match the folder_path passed to GenerateUploadUrl.", "x-presence": "implicit" }, "fileName": { "type": "string", "minLength": 1, "description": "File name to use within the selected folder.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional attributes associated with the resource.", "x-presence": "collection" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Labels associated with the resource for organization or filtering.", "x-presence": "collection" } }, "x-request-required": [ "fileId", "fileName" ], "required": [ "fileId", "fileName" ] }, "RegisterUploadedFileResponse": { "type": "object", "description": "Result payload for recording metadata for a file uploaded directly to storage.", "properties": { "file": { "description": "Metadata for the file affected or retrieved by the operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/FileInfo" } ] }, "registered": { "type": "boolean", "description": "true when newly registered; false when the file_id was already registered\n(idempotent retry — the existing FileInfo is returned unchanged).", "x-presence": "implicit" } } }, "GenerateDownloadUrlRequest": { "type": "object", "description": "Inputs for issuing a signed URL for downloading a stored file.", "properties": { "fileId": { "type": "string", "description": "Stable file ID to resolve to a signed URL.", "x-presence": "implicit" }, "expiresSeconds": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Requested lifetime of the signed URL, in seconds.", "x-presence": "implicit" }, "responseContentDisposition": { "type": "string", "description": "Content-Disposition override requested for the signed download response. Use attachment with\na filename to request a download under that name.", "x-presence": "implicit" } } }, "GenerateDownloadUrlResponse": { "type": "object", "description": "Result payload for issuing a signed URL for downloading a stored file.", "properties": { "url": { "type": "string", "description": "URL associated with the resource or outbound request.", "x-presence": "implicit" }, "file": { "description": "Metadata for the file affected or retrieved by the operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/FileInfo" } ] } } }, "BatchGenerateDownloadUrlsRequest": { "type": "object", "description": "Inputs for issuing signed download URLs for a collection of files.", "properties": { "fileIds": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "File IDs to resolve (1-50 per batch).", "x-presence": "collection", "x-protovalidate": { "repeated": { "minItems": "1", "maxItems": "50" } }, "x-validation-scope": "request" }, "expiresSeconds": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Requested lifetime of the signed URL, in seconds.", "x-presence": "implicit" } }, "x-request-required": [ "fileIds" ], "required": [ "fileIds" ] }, "BatchGenerateDownloadUrlsResponse": { "type": "object", "description": "Result payload for issuing signed download URLs for a collection of files.", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/FileUrlResult" }, "description": "Signed download URL or item-specific error for each requested file.", "x-presence": "collection" } } }, "FileUrlResult": { "type": "object", "description": "Signed download URL or item-specific error for one requested file.", "properties": { "fileId": { "type": "string", "description": "Stable identifier of the stored file.", "x-presence": "implicit" }, "url": { "type": "string", "description": "URL associated with the resource or outbound request.", "x-presence": "implicit" }, "success": { "type": "boolean", "description": "Whether the operation reports a successful result.", "x-presence": "implicit" }, "error": { "type": "string", "description": "Error information reported for this operation or item.", "x-presence": "implicit" }, "contentType": { "type": "string", "description": "MIME type (e.g. \"image/jpeg\"); lets consumers pick the right content-part shape (IMAGE_URL vs FILE_URL). Empty when success = false or unknown.", "x-presence": "implicit" } }, "x-reference-model": { "title": "FileUrlResult", "url": "/api/models/file-url-result#response" } }, "GetStorageQuotaRequest": { "type": "object", "description": "Inputs for reading the user’s allocated capacity and current storage usage.", "properties": {} }, "GetStorageQuotaResponse": { "type": "object", "description": "Result payload for reading the user’s allocated capacity and current storage usage.", "properties": { "usedBytes": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Storage capacity currently attributed to the user, in bytes.", "x-presence": "implicit" }, "quotaBytes": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Storage capacity allocated to the user, in bytes.", "x-presence": "implicit" }, "fileCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of files represented by this folder or quota snapshot.", "x-presence": "implicit" }, "folderCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of folders represented by the quota snapshot.", "x-presence": "implicit" }, "usagePercentage": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Storage usage expressed as a percentage of the quota.", "x-presence": "implicit" } } }, "GetStateRequest": { "type": "object", "description": "Inputs for reading the file and folder registry state in object storage.", "properties": {} }, "GetStateResponse": { "type": "object", "description": "Result payload for reading the file and folder registry state in object storage.", "properties": { "state": { "description": "State snapshot returned by the actor or workflow.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/StorageManagerState" } ] } } }, "StorageManagerState": { "type": "object", "description": "Durable actor state for StorageManager", "properties": { "userId": { "type": "string", "description": "Identifier of the user associated with the operation.", "x-presence": "implicit" }, "folders": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/FolderInfo" }, "description": "Path -> FolderInfo.", "x-presence": "collection" }, "files": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/FileInfo" }, "description": "Path -> FileInfo.", "x-presence": "collection" }, "totalSizeBytes": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Combined size of the represented files, in bytes.", "x-presence": "implicit" }, "quotaBytes": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Storage capacity allocated to the user, in bytes.", "x-presence": "implicit" }, "totalFileCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of files tracked in the storage state.", "x-presence": "implicit" }, "totalFolderCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of folders tracked in the storage state.", "x-presence": "implicit" }, "createdAt": { "type": "string", "description": "When user's storage was initialized.", "x-presence": "implicit" }, "lastModified": { "type": "string", "description": "Last modification timestamp.", "x-presence": "implicit" } }, "x-reference-model": { "title": "StorageManagerState", "url": "/api/models/storage-manager-state#response" } }, "CreateWebhookEndpointRequest": { "type": "object", "description": "Inputs for registering a tenant webhook destination and its initial event subscription.", "properties": { "name": { "type": "string", "minLength": 1, "description": "Display name of the tenant’s webhook delivery destination.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "url": { "type": "string", "format": "uri", "description": "URL associated with the resource or outbound request.", "x-presence": "implicit", "x-protovalidate": { "string": { "uri": true } }, "x-validation-scope": "request" }, "description": { "type": "string", "description": "Human-readable description of the resource.", "x-presence": "implicit" }, "eventTypes": { "type": "array", "items": { "type": "string" }, "description": "Convenience: auto-create subscription.", "x-presence": "collection" } }, "x-request-required": [ "name", "url" ], "required": [ "name", "url" ] }, "CreateWebhookEndpointResponse": { "type": "object", "description": "Result payload for registering a tenant webhook destination and its initial event subscription.", "properties": { "endpoint": { "description": "Webhook endpoint returned by the provider operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/Endpoint" } ] }, "subscription": { "description": "If event_types provided.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/Subscription" } ] } } }, "Endpoint": { "type": "object", "description": "Provider record describing a webhook delivery destination and its delivery settings.", "properties": { "id": { "type": "string", "description": "Identifier of the endpoint record.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Display name of the webhook delivery destination.", "x-presence": "implicit" }, "url": { "type": "string", "description": "URL associated with the resource or outbound request.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Human-readable description of the resource.", "x-presence": "implicit" }, "status": { "oneOf": [ { "type": "string", "enum": [ "ENDPOINT_STATUS_ACTIVE", "ENDPOINT_STATUS_INACTIVE", "ENDPOINT_STATUS_PAUSED", "ENDPOINT_STATUS_PENDING" ], "x-enumDescriptions": { "ENDPOINT_STATUS_ACTIVE": "The endpoint is marked active for webhook delivery.", "ENDPOINT_STATUS_INACTIVE": "The endpoint is marked inactive by the delivery backend.", "ENDPOINT_STATUS_PAUSED": "Delivery to the endpoint is paused.", "ENDPOINT_STATUS_PENDING": "The endpoint is pending activation in the delivery backend." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "ENDPOINT_STATUS_ACTIVE", "number": 1, "canonical": true, "description": "The endpoint is marked active for webhook delivery." }, { "name": "ENDPOINT_STATUS_INACTIVE", "number": 2, "canonical": true, "description": "The endpoint is marked inactive by the delivery backend." }, { "name": "ENDPOINT_STATUS_PAUSED", "number": 3, "canonical": true, "description": "Delivery to the endpoint is paused." }, { "name": "ENDPOINT_STATUS_PENDING", "number": 4, "canonical": true, "description": "The endpoint is pending activation in the delivery backend." } ], "x-enum-description": "Lifecycle condition reported for a webhook delivery endpoint.", "description": "Current state of the webhook endpoint.", "x-presence": "implicit" }, "secret": { "type": "string", "description": "Secret associated with the webhook endpoint or deployed trigger.", "x-presence": "implicit" }, "httpTimeout": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Timeout for an individual webhook HTTP delivery, in seconds.", "x-presence": "implicit" }, "rateLimit": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum delivery rate configured for the webhook endpoint.", "x-presence": "implicit" }, "rateLimitDuration": { "type": "string", "description": "Delivery-rate window returned as a seconds-suffixed duration string (for example, 60s).", "x-presence": "implicit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when this record was created.", "x-presence": "message" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time when this record was last updated.", "x-presence": "message" } }, "x-reference-model": { "title": "Endpoint", "url": "/api/models/endpoint#response" } }, "Subscription": { "type": "object", "description": "Webhook event selection and retry settings associated with an endpoint.", "properties": { "id": { "type": "string", "description": "Identifier of the subscription record.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Display name of the webhook event subscription.", "x-presence": "implicit" }, "endpointId": { "type": "string", "description": "Identifier of the webhook endpoint receiving deliveries.", "x-presence": "implicit" }, "eventTypes": { "type": "array", "items": { "type": "string" }, "description": "Event type names selected for the webhook subscription.", "x-presence": "collection" }, "filter": { "description": "Selection criteria applied to the listing.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/SubscriptionFilter" } ] }, "retryConfig": { "description": "Retry policy applied to the webhook subscription.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/RetryConfig" } ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when this record was created.", "x-presence": "message" }, "externalId": { "type": "string", "description": "Client-supplied external subscription identifier. Empty when none was supplied.", "x-presence": "implicit" } }, "x-reference-model": { "title": "Subscription", "url": "/api/models/subscription#response" } }, "SubscriptionFilter": { "type": "object", "description": "Event-body and header conditions selecting webhook events for a subscription.", "properties": { "body": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Event-body matching rules used by the webhook subscription filter.", "x-presence": "collection" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Header-matching rules used to select events for the webhook subscription.", "x-presence": "collection" } }, "x-reference-model": { "title": "SubscriptionFilter", "url": "/api/models/subscription-filter#response" } }, "RetryConfig": { "type": "object", "description": "Retry strategy, attempt limit, and interval for failed webhook deliveries.", "properties": { "strategy": { "oneOf": [ { "type": "string", "enum": [ "RETRY_STRATEGY_LINEAR", "RETRY_STRATEGY_EXPONENTIAL" ], "x-enumDescriptions": { "RETRY_STRATEGY_LINEAR": "Retry using the configured linear interval strategy.", "RETRY_STRATEGY_EXPONENTIAL": "Increase the delay between retries using exponential backoff." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "RETRY_STRATEGY_LINEAR", "number": 1, "canonical": true, "description": "Retry using the configured linear interval strategy." }, { "name": "RETRY_STRATEGY_EXPONENTIAL", "number": 2, "canonical": true, "description": "Increase the delay between retries using exponential backoff." } ], "x-enum-description": "Backoff strategy applied between webhook delivery attempts.", "description": "Webhook retry strategy selected in the provider configuration.", "x-presence": "implicit" }, "retryCount": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum retry count configured for webhook delivery.", "x-presence": "implicit" }, "intervalSeconds": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Delay between webhook delivery retries, in seconds.", "x-presence": "implicit" } }, "x-reference-model": { "title": "RetryConfig", "url": "/api/models/retry-config#response" } }, "ListWebhookEndpointsRequest": { "type": "object", "description": "Inputs for listing webhook destinations registered for the tenant.", "properties": { "page": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Page number used by this listing operation.", "x-presence": "implicit" }, "perPage": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of entries requested per page.", "x-presence": "implicit" } } }, "ListWebhookEndpointsResponse": { "type": "object", "description": "Result payload for listing webhook destinations registered for the tenant.", "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/Endpoint" }, "description": "Webhook endpoints returned by the listing.", "x-presence": "collection" }, "pagination": { "description": "Page position and total counts reported with the listing.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PaginationInfo" } ] } } }, "PaginationInfo": { "type": "object", "description": "Page position and aggregate counts accompanying a paginated provider listing.", "properties": { "total": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Total number of entries reported by the listing.", "x-presence": "implicit" }, "page": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Page number used by this listing operation.", "x-presence": "implicit" }, "perPage": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of entries requested per page.", "x-presence": "implicit" }, "totalPages": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Total number of pages reported for the current query.", "x-presence": "implicit" } }, "x-reference-model": { "title": "PaginationInfo", "url": "/api/models/pagination-info#response" } }, "UpdateWebhookEndpointRequest": { "type": "object", "description": "Inputs for changing the address or descriptive metadata of a tenant webhook destination.", "properties": { "endpointId": { "type": "string", "minLength": 1, "description": "Identifier of the webhook endpoint receiving deliveries.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "name": { "type": "string", "description": "Display name of the tenant’s webhook delivery destination.", "x-presence": "implicit" }, "url": { "type": "string", "description": "URL associated with the resource or outbound request.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Human-readable description of the resource.", "x-presence": "implicit" } }, "x-request-required": [ "endpointId" ], "required": [ "endpointId" ] }, "UpdateWebhookEndpointResponse": { "type": "object", "description": "Result payload for changing the address or descriptive metadata of a tenant webhook destination.", "properties": { "endpoint": { "description": "Webhook endpoint returned by the provider operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/Endpoint" } ] } } }, "DeleteWebhookEndpointRequest": { "type": "object", "description": "Inputs for removing a tenant’s webhook delivery destination.", "properties": { "endpointId": { "type": "string", "minLength": 1, "description": "Identifier of the webhook endpoint receiving deliveries.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "endpointId" ], "required": [ "endpointId" ] }, "DeleteWebhookEndpointResponse": { "type": "object", "description": "Response schema for removing a tenant’s webhook delivery destination; no response fields are declared.", "properties": {} }, "CreateWebhookSubscriptionRequest": { "type": "object", "description": "Inputs for subscribing a tenant webhook endpoint to selected event types.", "properties": { "endpointId": { "type": "string", "minLength": 1, "description": "Identifier of the webhook endpoint receiving deliveries.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "eventTypes": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Event type names selected for the webhook subscription.", "x-presence": "collection", "x-protovalidate": { "repeated": { "minItems": "1" } }, "x-validation-scope": "request" }, "externalId": { "type": "string", "maxLength": 255, "description": "Optional client-supplied identifier, unique among the tenant’s live subscriptions. Use it to\naddress deletion by a name your application manages; it becomes reusable after deletion.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "255" } }, "x-validation-scope": "request" } }, "x-request-required": [ "endpointId", "eventTypes" ], "required": [ "endpointId", "eventTypes" ] }, "CreateWebhookSubscriptionResponse": { "type": "object", "description": "Result payload for subscribing a tenant webhook endpoint to selected event types.", "properties": { "subscription": { "description": "Webhook subscription returned by the provider operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/Subscription" } ] } } }, "ListWebhookSubscriptionsRequest": { "type": "object", "description": "Inputs for listing event subscriptions registered for tenant webhook destinations.", "properties": { "endpointId": { "type": "string", "description": "Optional: filter by endpoint.", "x-presence": "implicit" }, "page": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Page number used by this listing operation.", "x-presence": "implicit" }, "perPage": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of entries requested per page.", "x-presence": "implicit" } } }, "ListWebhookSubscriptionsResponse": { "type": "object", "description": "Result payload for listing event subscriptions registered for tenant webhook destinations.", "properties": { "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" }, "description": "Webhook subscriptions returned by the listing.", "x-presence": "collection" }, "pagination": { "description": "Page position and total counts reported with the listing.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PaginationInfo" } ] } } }, "DeleteWebhookSubscriptionRequest": { "type": "object", "description": "Inputs for removing a tenant webhook subscription by its external identifier.", "properties": { "subscriptionId": { "type": "string", "description": "Identifier of the subscription to delete. Supply exactly one of subscription_id or\nexternal_id.", "x-presence": "implicit" }, "externalId": { "type": "string", "maxLength": 255, "description": "Stable external identifier used to address the webhook subscription.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "255" } }, "x-validation-scope": "request" } }, "x-protovalidate": { "cel": [ { "id": "exactly_one_ref", "message": "exactly one of subscription_id or external_id must be set", "expression": "(this.subscription_id != '') != (this.external_id != '')" } ] }, "x-validation-scope": "request" }, "DeleteWebhookSubscriptionResponse": { "type": "object", "description": "Response schema for removing a tenant webhook subscription by its external identifier; no response fields are declared.", "properties": {} }, "ListWebhookDeliveriesRequest": { "type": "object", "description": "Inputs for querying delivery attempts visible through the tenant webhook gateway.", "properties": { "endpointId": { "type": "string", "description": "Optional: filter by endpoint.", "x-presence": "implicit" }, "subscriptionId": { "type": "string", "description": "Optional: filter by subscription.", "x-presence": "implicit" }, "eventId": { "type": "string", "description": "Optional: filter by event.", "x-presence": "implicit" }, "status": { "oneOf": [ { "type": "string", "enum": [ "DELIVERY_STATUS_SCHEDULED", "DELIVERY_STATUS_PROCESSING", "DELIVERY_STATUS_COMPLETED", "DELIVERY_STATUS_RETRY", "DELIVERY_STATUS_FAILED", "DELIVERY_STATUS_DISCARDED" ], "x-enumDescriptions": { "DELIVERY_STATUS_SCHEDULED": "The delivery is scheduled and waiting for processing.", "DELIVERY_STATUS_PROCESSING": "The delivery backend is processing a delivery attempt.", "DELIVERY_STATUS_COMPLETED": "The webhook delivery completed successfully.", "DELIVERY_STATUS_RETRY": "The delivery is awaiting another attempt after a retryable failure.", "DELIVERY_STATUS_FAILED": "The delivery is reported as failed by the backend.", "DELIVERY_STATUS_DISCARDED": "The delivery backend discarded the event instead of completing delivery." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "DELIVERY_STATUS_SCHEDULED", "number": 1, "canonical": true, "description": "The delivery is scheduled and waiting for processing." }, { "name": "DELIVERY_STATUS_PROCESSING", "number": 2, "canonical": true, "description": "The delivery backend is processing a delivery attempt." }, { "name": "DELIVERY_STATUS_COMPLETED", "number": 3, "canonical": true, "description": "The webhook delivery completed successfully." }, { "name": "DELIVERY_STATUS_RETRY", "number": 4, "canonical": true, "description": "The delivery is awaiting another attempt after a retryable failure." }, { "name": "DELIVERY_STATUS_FAILED", "number": 5, "canonical": true, "description": "The delivery is reported as failed by the backend." }, { "name": "DELIVERY_STATUS_DISCARDED", "number": 6, "canonical": true, "description": "The delivery backend discarded the event instead of completing delivery." } ], "x-enum-description": "Delivery-backend state of a webhook event sent to an endpoint.", "description": "Delivery status used to restrict the tenant webhook-delivery query.", "x-presence": "implicit" }, "createdAfter": { "type": "string", "format": "date-time", "description": "Optional: filter by creation time.", "x-presence": "message" }, "createdBefore": { "type": "string", "format": "date-time", "description": "Optional: filter by creation time.", "x-presence": "message" }, "page": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Page number used by this listing operation.", "x-presence": "implicit" }, "perPage": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of entries requested per page.", "x-presence": "implicit" } } }, "ListWebhookDeliveriesResponse": { "type": "object", "description": "Result payload for querying delivery attempts visible through the tenant webhook gateway.", "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/EventDelivery" }, "description": "Webhook delivery records matching the listing query.", "x-presence": "collection" }, "pagination": { "description": "Page position and total counts reported with the listing.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PaginationInfo" } ] } } }, "EventDelivery": { "type": "object", "description": "Delivery-attempt state and response information for a webhook event.", "properties": { "id": { "type": "string", "description": "Identifier of the event delivery record.", "x-presence": "implicit" }, "eventId": { "type": "string", "description": "Identifier of the webhook event being delivered.", "x-presence": "implicit" }, "endpointId": { "type": "string", "description": "Identifier of the webhook endpoint receiving deliveries.", "x-presence": "implicit" }, "status": { "oneOf": [ { "type": "string", "enum": [ "DELIVERY_STATUS_SCHEDULED", "DELIVERY_STATUS_PROCESSING", "DELIVERY_STATUS_COMPLETED", "DELIVERY_STATUS_RETRY", "DELIVERY_STATUS_FAILED", "DELIVERY_STATUS_DISCARDED" ], "x-enumDescriptions": { "DELIVERY_STATUS_SCHEDULED": "The delivery is scheduled and waiting for processing.", "DELIVERY_STATUS_PROCESSING": "The delivery backend is processing a delivery attempt.", "DELIVERY_STATUS_COMPLETED": "The webhook delivery completed successfully.", "DELIVERY_STATUS_RETRY": "The delivery is awaiting another attempt after a retryable failure.", "DELIVERY_STATUS_FAILED": "The delivery is reported as failed by the backend.", "DELIVERY_STATUS_DISCARDED": "The delivery backend discarded the event instead of completing delivery." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "DELIVERY_STATUS_SCHEDULED", "number": 1, "canonical": true, "description": "The delivery is scheduled and waiting for processing." }, { "name": "DELIVERY_STATUS_PROCESSING", "number": 2, "canonical": true, "description": "The delivery backend is processing a delivery attempt." }, { "name": "DELIVERY_STATUS_COMPLETED", "number": 3, "canonical": true, "description": "The webhook delivery completed successfully." }, { "name": "DELIVERY_STATUS_RETRY", "number": 4, "canonical": true, "description": "The delivery is awaiting another attempt after a retryable failure." }, { "name": "DELIVERY_STATUS_FAILED", "number": 5, "canonical": true, "description": "The delivery is reported as failed by the backend." }, { "name": "DELIVERY_STATUS_DISCARDED", "number": 6, "canonical": true, "description": "The delivery backend discarded the event instead of completing delivery." } ], "x-enum-description": "Delivery-backend state of a webhook event sent to an endpoint.", "description": "Current delivery status reported for this webhook event attempt.", "x-presence": "implicit" }, "attempts": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of delivery attempts reported for the webhook event.", "x-presence": "implicit" }, "eventType": { "type": "string", "description": "Type of the webhook event represented by this delivery.", "x-presence": "implicit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when this record was created.", "x-presence": "message" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time when this record was last updated.", "x-presence": "message" }, "httpStatus": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "HTTP response status reported for the delivery attempt.", "x-presence": "implicit" }, "responseData": { "type": "string", "description": "Response body reported by the webhook delivery target.", "x-presence": "implicit" }, "error": { "type": "string", "description": "Error information reported for this operation or item.", "x-presence": "implicit" } }, "x-reference-model": { "title": "EventDelivery", "url": "/api/models/event-delivery#response" } }, "RetryWebhookDeliveryRequest": { "type": "object", "description": "Inputs for requesting another attempt for a tenant webhook delivery.", "properties": { "deliveryId": { "type": "string", "minLength": 1, "description": "Identifier of the webhook delivery to inspect or retry.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" } }, "x-request-required": [ "deliveryId" ], "required": [ "deliveryId" ] }, "RetryWebhookDeliveryResponse": { "type": "object", "description": "Result payload for requesting another attempt for a tenant webhook delivery.", "properties": { "delivery": { "description": "Webhook delivery record returned by the operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/EventDelivery" } ] } } }, "LLMMessagePublishedEventWebhook": { "type": "object", "description": "Domain event published when a new assistant/tool message is produced.", "properties": { "event_context": { "description": "Event provenance and routing metadata associated with the emitted event.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/EventContextWebhook" } ] }, "message": { "description": "The generated assistant/tool message", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/MessageWebhook" } ] } }, "x-reference-model": { "title": "LLMMessagePublishedEvent", "url": "/api/models/llm-message-published-event#webhook" } }, "EventContextWebhook": { "type": "object", "description": "EventContext standardizes event envelope metadata for domain events", "properties": { "event_name": { "type": "string", "description": "Stable event name, e.g. \"llm.message_published\"", "x-presence": "implicit" }, "version": { "type": "string", "description": "Version of the event schema (semver or simple numeric)", "x-presence": "implicit" }, "event_id": { "type": "string", "description": "Unique event identifier (UUID)", "x-presence": "implicit" }, "correlation_id": { "type": "string", "description": "Correlation identifier (e.g., session/workflow/conversation id)", "x-presence": "implicit" }, "emitted_at": { "type": "string", "description": "RFC3339 timestamp string of when the event was emitted", "x-presence": "implicit" }, "caller_key": { "type": "string", "description": "Publisher-provided routing key (e.g., conversation/thread id)", "x-presence": "implicit" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Application-level metadata (not transport tracing headers)", "x-presence": "collection" }, "tenant_id": { "type": "string", "description": "Identifier of the tenant to which the event belongs, used to select that tenant’s webhook\ndestinations.", "x-presence": "implicit" }, "project_id": { "type": "string", "description": "Identifier of the project within the tenant that scopes the event. Defaults to default when no\nproject is supplied.", "x-presence": "implicit" }, "session_id": { "type": "string", "description": "Identifier of the end-user application session associated with the event, distinct from tenant\nand conversation identity.", "x-presence": "implicit" } }, "x-reference-model": { "title": "EventContext", "url": "/api/models/event-context#webhook" } }, "MessageWebhook": { "type": "object", "description": "Chat message", "properties": { "role": { "oneOf": [ { "type": "string", "enum": [ "ROLE_SYSTEM", "ROLE_USER", "ROLE_ASSISTANT", "ROLE_TOOL" ], "x-enumDescriptions": { "ROLE_SYSTEM": "Instructions or context provided as a system message.", "ROLE_USER": "Input supplied by the user or customer application.", "ROLE_ASSISTANT": "Content produced by the assistant, including its tool-call requests.", "ROLE_TOOL": "A tool result supplied back to the assistant." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "ROLE_SYSTEM", "number": 1, "canonical": true, "description": "Instructions or context provided as a system message." }, { "name": "ROLE_USER", "number": 2, "canonical": true, "description": "Input supplied by the user or customer application." }, { "name": "ROLE_ASSISTANT", "number": 3, "canonical": true, "description": "Content produced by the assistant, including its tool-call requests." }, { "name": "ROLE_TOOL", "number": 4, "canonical": true, "description": "A tool result supplied back to the assistant." } ], "x-enum-description": "Participant role attached to a conversation message and forwarded in model context.", "description": "Role of the participant that produced the chat message.", "x-presence": "implicit", "x-protovalidate": { "enum": { "definedOnly": true, "notIn": [ 0 ] } }, "x-validation-scope": "request" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/ContentPartWebhook" }, "description": "Content parts composing the chat message.", "x-presence": "collection" }, "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCallWebhook" }, "description": "Assistant-to-tool invocations.", "x-presence": "collection" }, "name": { "type": "string", "description": "Name identifying the sender of the chat message.", "x-presence": "implicit" }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp associated with the conversation message or event.", "x-presence": "message" }, "message_id": { "type": "string", "description": "Unique message identifier.", "x-presence": "implicit" }, "annotations": { "type": "array", "items": { "$ref": "#/components/schemas/AnnotationWebhook" }, "description": "Structured annotations (e.g., standardized web search URL citations, PDF reuse tokens)", "x-presence": "collection" }, "sequence": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Monotonic, per-conversation sequence number for stable ordering (1-based)", "x-presence": "implicit" }, "generated_by": { "type": "string", "description": "Workflow run id or generator key that produced this message (e.g., workflow run key)", "x-presence": "implicit" }, "usage": { "description": "Token usage for this generation (populated for assistant messages)", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/UsageWebhook" } ] }, "model": { "type": "string", "description": "Model that generated this message (e.g., \"anthropic/claude-sonnet-4\")", "x-presence": "implicit" }, "generation_context": { "description": "Dynamic context that shaped this generation (memories, search params, turn info)", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GenerationContextWebhook" } ] }, "client_context": { "description": "Arbitrary client-supplied context attached by the client for this message", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ClientContextWebhook" } ] }, "feedback": { "type": "array", "items": { "$ref": "#/components/schemas/MessageFeedbackWebhook" }, "description": "Feedback on an assistant message, with one entry per rater identified by rated_by. A later\nrating by the same rater replaces their earlier entry.", "x-presence": "collection" }, "source_user_message_id": { "type": "string", "description": "Identifier of the user message that opened this conversation turn. Generated messages in the\nsame turn share this value; a user message carries its own message_id. Empty on historical\nmessages that predate turn attribution.", "x-presence": "implicit" }, "finish_reason": { "type": "string", "description": "Why the model stopped, verbatim from the provider: \"stop\",\n\"tool_calls\", \"length\", \"error\". Empty for historical messages.", "x-presence": "implicit" } }, "x-reference-model": { "title": "Message", "url": "/api/models/message#webhook" }, "x-protovalidate": { "cel": [ { "id": "message_content_or_tool_calls", "message": "content or tool_calls required", "expression": "size(this.content) > 0 || size(this.tool_calls) > 0" } ] }, "x-validation-scope": "request", "x-request-required": [ "role" ] }, "ContentPartWebhook": { "type": "object", "description": "Content parts composing a message (flattened structure for JSON compatibility)", "properties": { "type": { "oneOf": [ { "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" ], "x-enumDescriptions": { "CONTENT_PART_TYPE_TEXT": "Plain text carried by the content part.", "CONTENT_PART_TYPE_IMAGE_URL": "An image supplied through a remote URL.", "CONTENT_PART_TYPE_IMAGE_BASE64": "An image supplied as base64-encoded bytes.", "CONTENT_PART_TYPE_FILE_ID": "A provider file identifier or internal storage identifier resolved before generation.", "CONTENT_PART_TYPE_FILE_PATH": "A reference to a local file path.", "CONTENT_PART_TYPE_FILE_URL": "A file supplied through a public or signed URL.", "CONTENT_PART_TYPE_FILE_DATA_URL": "A file embedded in a data URL, including its media type and encoded data.", "CONTENT_PART_TYPE_AUDIO_BASE64": "Base64-encoded audio; the part metadata identifies its audio format.", "CONTENT_PART_TYPE_REASONING": "A reasoning segment returned by a model provider, when available." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "CONTENT_PART_TYPE_TEXT", "number": 1, "canonical": true, "description": "Plain text carried by the content part." }, { "name": "CONTENT_PART_TYPE_IMAGE_URL", "number": 2, "canonical": true, "description": "An image supplied through a remote URL." }, { "name": "CONTENT_PART_TYPE_IMAGE_BASE64", "number": 3, "canonical": true, "description": "An image supplied as base64-encoded bytes." }, { "name": "CONTENT_PART_TYPE_FILE_ID", "number": 4, "canonical": true, "description": "A provider file identifier or internal storage identifier resolved before generation." }, { "name": "CONTENT_PART_TYPE_FILE_PATH", "number": 5, "canonical": true, "description": "A reference to a local file path." }, { "name": "CONTENT_PART_TYPE_FILE_URL", "number": 6, "canonical": true, "description": "A file supplied through a public or signed URL." }, { "name": "CONTENT_PART_TYPE_FILE_DATA_URL", "number": 7, "canonical": true, "description": "A file embedded in a data URL, including its media type and encoded data." }, { "name": "CONTENT_PART_TYPE_AUDIO_BASE64", "number": 8, "canonical": true, "description": "Base64-encoded audio; the part metadata identifies its audio format." }, { "name": "CONTENT_PART_TYPE_REASONING", "number": 9, "canonical": true, "description": "A reasoning segment returned by a model provider, when available." } ], "x-enum-description": "Discriminator identifying which content representation a message part carries.", "description": "Kind of content carried by this message part.", "x-presence": "implicit", "x-protovalidate": { "enum": { "definedOnly": true } }, "x-validation-scope": "request" }, "content": { "type": "string", "description": "Text content, image URL, file ID, or base64-encoded data.", "x-presence": "implicit" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional type-specific metadata (dimensions, mime_type, etc.).", "x-presence": "collection" }, "cache_preferred": { "type": "boolean", "description": "Hint that this part is eligible for provider prompt caching.", "x-presence": "implicit" }, "structured_message": { "description": "Populated on TEXT parts for structured output responses.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/StructuredMessageWebhook" } ] } }, "x-reference-model": { "title": "ContentPart", "url": "/api/models/content-part#webhook" } }, "StructuredMessageWebhook": { "type": "object", "description": "A structured message whose JSON payload has been validated against\na declared schema. Consumers can trust that json_payload conforms\nto the schema identified by schema_name.\n\nInspect 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.", "properties": { "json_payload": { "type": "object", "additionalProperties": true, "description": "The validated JSON payload as a Struct (preserves types)", "x-presence": "message" }, "schema_name": { "type": "string", "description": "Schema identifier (from ResponseFormat.schema_name)", "x-presence": "implicit" }, "healed": { "type": "boolean", "description": "Whether response healing is reported for this structured message. Currently returned as false.", "x-presence": "implicit" } }, "x-reference-model": { "title": "StructuredMessage", "url": "/api/models/structured-message#webhook" } }, "ToolCallWebhook": { "type": "object", "description": "A single structured tool call emitted by the model\n\n[`clientToolDeadlineAt`](/api/models/tool-call#response-field-clienttooldeadlineat) is the client answer\nwindow. Expiry ends that wait and rejects late results; the timeout policy determines the outcome.", "properties": { "id": { "type": "string", "description": "Provider-supplied call id.", "x-presence": "implicit" }, "name": { "type": "string", "description": "Name of the tool or function being invoked.", "x-presence": "implicit" }, "arguments_json": { "type": "object", "additionalProperties": true, "description": "JSON object payload.", "x-presence": "message" }, "status": { "oneOf": [ { "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" ], "x-enumDescriptions": { "TOOL_EXECUTION_STATUS_PENDING": "The tool call is waiting to begin execution.", "TOOL_EXECUTION_STATUS_EXECUTING": "The tool call is currently executing.", "TOOL_EXECUTION_STATUS_COMPLETED": "The tool call completed successfully. Responses use this canonical spelling for numeric value\n3.", "TOOL_EXECUTION_STATUS_FAILED": "Tool execution ended unsuccessfully; inspect the tool error or end reason.", "TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION": "The tool call is waiting for approval before it can execute.", "TOOL_EXECUTION_STATUS_CANCELLED": "The tool call was cancelled before normal completion.", "TOOL_EXECUTION_STATUS_TIMED_OUT": "Tool execution ended because its time limit elapsed." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "TOOL_EXECUTION_STATUS_PENDING", "number": 1, "canonical": true, "description": "The tool call is waiting to begin execution." }, { "name": "TOOL_EXECUTION_STATUS_EXECUTING", "number": 2, "canonical": true, "description": "The tool call is currently executing." }, { "name": "TOOL_EXECUTION_STATUS_COMPLETED", "number": 3, "canonical": true, "description": "The tool call completed successfully. Responses use this canonical spelling for numeric value\n3." }, { "name": "TOOL_EXECUTION_STATUS_SUCCESS", "number": 3, "canonical": false, "description": "Legacy alias of TOOL_EXECUTION_STATUS_COMPLETED with the same numeric value; use COMPLETED for\nnew writes." }, { "name": "TOOL_EXECUTION_STATUS_FAILED", "number": 4, "canonical": true, "description": "Tool execution ended unsuccessfully; inspect the tool error or end reason." }, { "name": "TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION", "number": 5, "canonical": true, "description": "The tool call is waiting for approval before it can execute." }, { "name": "TOOL_EXECUTION_STATUS_CANCELLED", "number": 6, "canonical": true, "description": "The tool call was cancelled before normal completion." }, { "name": "TOOL_EXECUTION_STATUS_TIMED_OUT", "number": 7, "canonical": true, "description": "Tool execution ended because its time limit elapsed." } ], "x-enum-description": "Execution state of one tool call, including approval waiting and terminal outcomes.", "description": "Execution status recorded for the tool call.", "x-presence": "implicit" }, "result_json": { "type": "object", "additionalProperties": true, "description": "Tool execution result (object).", "x-presence": "message" }, "executed_at": { "type": "string", "format": "date-time", "description": "Time when the tool execution was recorded.", "x-presence": "message" }, "server_id": { "type": "string", "description": "Which server provides this tool (for MCP tools).", "x-presence": "implicit" }, "is_client_tool": { "type": "boolean", "description": "True if this is a client-side tool handled by client.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Tool description captured when the call is emitted, preserving the definition used for\nhistorical calls even if the tool configuration later changes.", "x-presence": "implicit" }, "parameters_json_schema": { "type": "object", "additionalProperties": true, "description": "JSON Schema describing the tool’s input arguments.", "x-presence": "message" }, "requires_approval_at": { "type": "string", "format": "date-time", "description": "Deadline for an approval decision, calculated from the effective approval timeout. This is not\nthe time the call began waiting. An approval received after the deadline is rejected.", "x-presence": "message" }, "approved_at": { "type": "string", "format": "date-time", "description": "Timestamp when approval decision was recorded (if approved/rejected)", "x-presence": "message" }, "approved_by": { "type": "string", "description": "Identifier of the approver (user id, email, or actor key)", "x-presence": "implicit" }, "execution_duration": { "type": "string", "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]{1,9})?s$", "description": "End-to-end execution duration once terminal (includes tool server latency or client-side time)", "x-presence": "message" }, "end_reason": { "type": "string", "description": "Why this call ended, in one short phrase — \"approval rejected\",\n\"approval timeout\", the underlying error. Set only once `status` is\nterminal, and empty on a clean COMPLETED.", "x-presence": "implicit" }, "client_tool_deadline_at": { "type": "string", "format": "date-time", "description": "Deadline by which the client must submit a result for this call, stamped\nwhen the call is dispatched to a caller. Mirrors requires_approval_at.", "x-presence": "message" } }, "x-reference-model": { "title": "ToolCall", "url": "/api/models/tool-call#webhook" } }, "AnnotationWebhook": { "type": "object", "description": "Tagged provider annotation attached to generated content, such as a citation or PDF reference.", "properties": { "url_citation": { "description": "Submessage fields (optional); populate the one matching kind", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/UrlCitationWebhook" } ] }, "pdf": { "description": "PDF annotation or parser configuration selected by the enclosing message.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PdfAnnotationWebhook" } ] }, "kind": { "oneOf": [ { "type": "string", "enum": [ "ANNOTATION_KIND_URL_CITATION", "ANNOTATION_KIND_PDF" ], "x-enumDescriptions": { "ANNOTATION_KIND_URL_CITATION": "A citation to a source identified by its URL.", "ANNOTATION_KIND_PDF": "An annotation identifying source content in a PDF document." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "ANNOTATION_KIND_URL_CITATION", "number": 1, "canonical": true, "description": "A citation to a source identified by its URL." }, { "name": "ANNOTATION_KIND_PDF", "number": 2, "canonical": true, "description": "An annotation identifying source content in a PDF document." } ], "x-enum-description": "Kind of source annotation associated with generated content.", "description": "Selected kind; determines which submessage is populated", "x-presence": "implicit" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Provider-specific extras.", "x-presence": "collection" } }, "x-reference-model": { "title": "Annotation", "url": "/api/models/annotation#webhook" } }, "UrlCitationWebhook": { "type": "object", "description": "=== Annotations ===\nWeb source and character range cited in generated message content.", "properties": { "url": { "type": "string", "description": "URL associated with the resource or outbound request.", "x-presence": "implicit" }, "title": { "type": "string", "description": "Title of the web page cited by this annotation.", "x-presence": "implicit" }, "content": { "type": "string", "description": "Excerpt or snippet of the cited web page.", "x-presence": "implicit" }, "start_index": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Character index in message content.", "x-presence": "implicit" }, "end_index": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Character index in message content.", "x-presence": "implicit" } }, "x-reference-model": { "title": "UrlCitation", "url": "/api/models/url-citation#webhook" } }, "PdfAnnotationWebhook": { "type": "object", "description": "Provider annotation identifying a parsed PDF and reusable parsing output.", "properties": { "filename": { "type": "string", "description": "Optional identifying information about the original file", "x-presence": "implicit" }, "engine": { "type": "string", "description": "PDF parsing engine used by provider (e.g., \"pdf-text\", \"mistral-ocr\", \"native\")", "x-presence": "implicit" }, "token": { "type": "string", "description": "Opaque provider token or handle allowing reuse without re-parsing", "x-presence": "implicit" }, "source_url": { "type": "string", "description": "Optional: original source reference (public URL or data: URL)", "x-presence": "implicit" }, "hash": { "type": "string", "description": "Provider-supplied hash identifying the parsed file.", "x-presence": "implicit" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/ContentPartWebhook" }, "description": "Optional structured content returned by provider annotations (text, image URLs, etc.)\nNote: This can be large; include only if you need to round-trip provider annotations.", "x-presence": "collection" } }, "x-reference-model": { "title": "PdfAnnotation", "url": "/api/models/pdf-annotation#webhook" } }, "UsageWebhook": { "type": "object", "description": "Usage accounting", "properties": { "prompt_tokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Prompt-token usage reported by the model provider.", "x-presence": "implicit" }, "completion_tokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Completion-token usage reported by the model provider.", "x-presence": "implicit" }, "total_tokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Total token usage reported by the model provider.", "x-presence": "implicit" }, "cost_estimate": { "oneOf": [ { "type": "number", "format": "float" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Estimated cost in USD.", "x-presence": "implicit" }, "completion_tokens_details": { "description": "Breakdown of completion tokens.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/CompletionTokensDetailsWebhook" } ] }, "prompt_tokens_details": { "description": "Breakdown of prompt tokens (cache).", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PromptTokensDetailsWebhook" } ] }, "cost_details": { "description": "Breakdown of upstream provider cost (BYOK routes).", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/CostDetailsWebhook" } ] }, "is_byok": { "type": "boolean", "description": "Whether this generation used the customer's own model-provider key.", "x-presence": "implicit" } }, "x-reference-model": { "title": "Usage", "url": "/api/models/usage#webhook" } }, "CompletionTokensDetailsWebhook": { "type": "object", "description": "Breakdown of completion-token usage. Categories are measured by different upstream tokenizers\nand need not sum to completion_tokens; one category must not be derived by subtracting the\nothers.", "properties": { "reasoning_tokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Tokens used for reasoning/thinking.", "x-presence": "implicit" }, "image_tokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Completion tokens emitted as image output.", "x-presence": "implicit" }, "audio_tokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Completion tokens emitted as audio output.", "x-presence": "implicit" } }, "x-reference-model": { "title": "CompletionTokensDetails", "url": "/api/models/completion-tokens-details#webhook" } }, "PromptTokensDetailsWebhook": { "type": "object", "description": "Breakdown of prompt token usage by category (input-side cache accounting)", "properties": { "cached_tokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Prompt tokens served from cache (cache READ).", "x-presence": "implicit" }, "cache_write_tokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Prompt tokens written to cache this call (cache WRITE).", "x-presence": "implicit" }, "audio_tokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Prompt tokens from audio input (multimodal).", "x-presence": "implicit" }, "video_tokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Prompt tokens from video input (multimodal).", "x-presence": "implicit" } }, "x-reference-model": { "title": "PromptTokensDetails", "url": "/api/models/prompt-tokens-details#webhook" } }, "CostDetailsWebhook": { "type": "object", "description": "Breakdown of model-provider cost. When the customer supplies the provider key, usage.cost is\nzero and upstream_inference_cost reports the provider spend, split into prompt and completion\ncomponents.", "properties": { "upstream_inference_cost": { "oneOf": [ { "type": "number", "format": "float" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Total upstream provider cost (USD) on BYOK routes.", "x-presence": "implicit" }, "upstream_inference_prompt_cost": { "oneOf": [ { "type": "number", "format": "float" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Upstream cost attributed to prompt tokens (USD).", "x-presence": "implicit" }, "upstream_inference_completion_cost": { "oneOf": [ { "type": "number", "format": "float" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Upstream cost attributed to completion tokens (USD).", "x-presence": "implicit" } }, "x-reference-model": { "title": "CostDetails", "url": "/api/models/cost-details#webhook" } }, "GenerationContextWebhook": { "type": "object", "description": "Snapshot of retrieval inputs, prompt provenance, and turn position that shaped a generated message.", "properties": { "memories": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryReferenceWebhook" }, "description": "Memory records captured in the generation context.", "x-presence": "collection" }, "relations": { "type": "array", "items": { "$ref": "#/components/schemas/RelationReferenceWebhook" }, "description": "Graph relationships captured in the generation context.", "x-presence": "collection" }, "memory_search": { "description": "Memory-query parameters and counts recorded for this generation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/MemorySearchParamsWebhook" } ] }, "turn": { "description": "Turn position and limit within the generation run.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/TurnInfoWebhook" } ] }, "language_preference": { "type": "string", "description": "Language preference associated with the generation context.", "x-presence": "implicit" }, "resolved_system_prompt": { "type": "string", "description": "System prompt selected for this generation after prompt precedence is resolved. This field is\nretained in the schema but is not populated; use resolved_prompt_hash for recorded prompt\nidentity.", "x-presence": "implicit" }, "profile_id": { "type": "string", "description": "Agent profile that produced this message (\"\" if none active).", "x-presence": "implicit" }, "model": { "type": "string", "description": "Model actually used for this generation.", "x-presence": "implicit" }, "prompt_source": { "oneOf": [ { "type": "string", "enum": [ "PROMPT_SOURCE_CLIENT_OVERRIDE", "PROMPT_SOURCE_PROFILE_TEMPLATE", "PROMPT_SOURCE_DEFAULT_CONFIG" ], "x-enumDescriptions": { "PROMPT_SOURCE_CLIENT_OVERRIDE": "The caller supplied the prompt through the send request's generation-configuration override.", "PROMPT_SOURCE_PROFILE_TEMPLATE": "The prompt was rendered from the active agent profile template.", "PROMPT_SOURCE_DEFAULT_CONFIG": "The prompt came from the conversation or project default generation configuration." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "PROMPT_SOURCE_CLIENT_OVERRIDE", "number": 1, "canonical": true, "description": "The caller supplied the prompt through the send request's generation-configuration override." }, { "name": "PROMPT_SOURCE_PROFILE_TEMPLATE", "number": 2, "canonical": true, "description": "The prompt was rendered from the active agent profile template." }, { "name": "PROMPT_SOURCE_DEFAULT_CONFIG", "number": 3, "canonical": true, "description": "The prompt came from the conversation or project default generation configuration." } ], "x-enum-description": "Source that supplied the effective prompt for a generation turn.", "description": "Which precedence tier supplied the prompt.", "x-presence": "implicit" }, "base_config": { "description": "Generation configuration resolved before per-call overrides and timeout adjustments, with\nsystem_prompt omitted. The active profile supplies the base when selected; otherwise the\nconversation default does. May be absent on older turns or when neither supplies a\nconfiguration.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GenerationConfigWebhook" } ] }, "override_config": { "description": "Per-call generation configuration supplied before the override merge.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GenerationConfigWebhook" } ] }, "profile_version": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Immutable version of the active agent profile used to render this turn’s prompt. Absent on\nolder turns and turns without a profile template.", "x-presence": "implicit" }, "fragments_version": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Version of the prompt-fragment set used to render the profile prompt.", "x-presence": "implicit" }, "prompt_variables": { "type": "object", "additionalProperties": true, "description": "Values bound to the prompt template for this generation.", "x-presence": "message" }, "profile_render_failed": { "type": "boolean", "description": "Whether rendering the profile prompt failed for this generation.", "x-presence": "implicit" }, "resolved_prompt_hash": { "type": "string", "description": "SHA-256 hash, as 64 hexadecimal characters, of the resolved system prompt before the\ncurrent-time instruction is appended. Identifies prompt content only, excluding model and\nsampling parameters. Absent on older turns without prompt capture.", "x-presence": "implicit" }, "resolved_user_context": { "type": "string", "description": "The [User Context] block as rendered into this turn's prompt: the user's\nname, locale, and location conditions (weather/AQI/UV/sun times). This is\nthe literal text the model received, not a reconstruction.\n\nEmpty when the user has no stored location, when enrichment degraded, or\non turns predating capture.", "x-presence": "implicit" }, "resolved_mcp_servers": { "type": "array", "items": { "$ref": "#/components/schemas/MCPServerReferenceWebhook" }, "description": "The MCP server list that governed this turn — the tier actually resolved\n(conversation settings -> active profile -> per-turn override_mcp_servers),\nwhich is simultaneously the tool-discovery source and the CallTool\nallow/block basis.\n\nEmpty on turns predating capture and on threads with no MCP servers.", "x-presence": "collection" } }, "x-reference-model": { "title": "GenerationContext", "url": "/api/models/generation-context#webhook" } }, "MemoryReferenceWebhook": { "type": "object", "description": "A memory record retrieved and included in generation context.", "properties": { "memory_id": { "type": "string", "description": "Identifier of the retrieved memory record.", "x-presence": "implicit" }, "score": { "oneOf": [ { "type": "number", "format": "float" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Relevance score reported by the memory provider for this match.", "x-presence": "implicit" }, "memory_text": { "type": "string", "description": "Text of the retrieved memory record.", "x-presence": "implicit" }, "created_at": { "type": "string", "format": "date-time", "description": "Time when this record was created.", "x-presence": "message" }, "updated_at": { "type": "string", "format": "date-time", "description": "Time when this record was last updated.", "x-presence": "message" } }, "x-reference-model": { "title": "MemoryReference", "url": "/api/models/memory-reference#webhook" } }, "RelationReferenceWebhook": { "type": "object", "description": "A graph relationship retrieved and included in generation context.", "properties": { "source": { "type": "string", "description": "Source entity of the memory graph relationship.", "x-presence": "implicit" }, "relationship": { "type": "string", "description": "Relationship label connecting the source and destination entities.", "x-presence": "implicit" }, "destination": { "type": "string", "description": "Destination entity of the memory graph relationship.", "x-presence": "implicit" } }, "x-reference-model": { "title": "RelationReference", "url": "/api/models/relation-reference#webhook" } }, "MemorySearchParamsWebhook": { "type": "object", "description": "Parameters used to retrieve relevant memories during generation.", "properties": { "query": { "type": "string", "description": "Text submitted to memory retrieval for this generation.", "x-presence": "implicit" }, "top_k": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum memory matches requested during generation-context retrieval.", "x-presence": "implicit" }, "threshold": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Minimum relevance threshold requested for the memory query.", "x-presence": "implicit" }, "rerank": { "type": "boolean", "description": "Whether reranking was requested for the memory search.", "x-presence": "implicit" }, "results_returned": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of memory records returned by the search.", "x-presence": "implicit" }, "relations_returned": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of graph relationships returned by the search.", "x-presence": "implicit" } }, "x-reference-model": { "title": "MemorySearchParams", "url": "/api/models/memory-search-params#webhook" } }, "TurnInfoWebhook": { "type": "object", "description": "Turn position within an agentic generation run", "properties": { "current_turn": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Current turn position within the generation run.", "x-presence": "implicit" }, "max_turns": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum turns configured for the generation run.", "x-presence": "implicit" } }, "x-reference-model": { "title": "TurnInfo", "url": "/api/models/turn-info#webhook" } }, "GenerationConfigWebhook": { "type": "object", "description": "Canonical generation configuration\n\nSet 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.\n\nSee [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes.", "properties": { "temperature": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Sampling temperature. Omission inherits the base configuration or provider default; an\nexplicitly supplied zero remains an override.", "x-presence": "explicit" }, "top_p": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Cumulative token-probability cutoff used for nucleus sampling.", "x-presence": "explicit" }, "max_output_tokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum output-token count requested from the model provider.", "x-presence": "explicit" }, "frequency_penalty": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Sampling penalty applied to tokens according to their prior frequency.", "x-presence": "explicit" }, "presence_penalty": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Sampling penalty applied to tokens already present in generated content.", "x-presence": "explicit" }, "stop_sequences": { "type": "array", "items": { "type": "string" }, "description": "Stop tokens/sequences (unchanged).", "x-presence": "collection" }, "seed": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Deterministic control where supported.", "x-presence": "explicit" }, "response_format": { "description": "Structured-output format and schema requested for the model response.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ResponseFormatWebhook" } ] }, "allow_parallel_tool_calls": { "type": "boolean", "description": "Allow the model to issue multiple tool calls in parallel where supported", "x-presence": "explicit" }, "model": { "type": "string", "description": "Model selection\nPrimary model identifier requested for generation.", "x-presence": "implicit" }, "models": { "type": "array", "items": { "type": "string" }, "description": "Candidate models for routing.", "x-presence": "collection" }, "system_prompt": { "type": "string", "description": "Optional system prompt prepended as a system message. An explicitly empty value in a per-call\noverride clears the base prompt.", "x-presence": "explicit" }, "model_routing_filter": { "description": "Optional metadata-based model routing filter.\nWhen set, candidate models are filtered by these criteria before routing.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ModelRoutingFilterWebhook" } ] }, "provider": { "description": "Provider/multi-provider routing preferences", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ProviderPreferencesWebhook" } ] }, "reasoning": { "description": "Reasoning effort and output options passed to the model provider.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ReasoningOptionsWebhook" } ] }, "usage": { "description": "Token and cost accounting associated with the operation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/UsageOptionsWebhook" } ] }, "transforms": { "type": "array", "items": { "type": "string" }, "description": "Provider transformations requested for the generation input.", "x-presence": "collection" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinitionWebhook" }, "description": "Tools & tool policy\nTool definitions exposed to the model for server-side execution.", "x-presence": "collection" }, "tool_choice": { "description": "Policy controlling whether and which tool the model may call.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ToolChoiceWebhook" } ] }, "client_tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinitionWebhook" }, "description": "Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)", "x-presence": "collection" }, "tool_policy": { "description": "Per-run tool execution policy (approvals, ordering, limits, retries, timeouts)", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ToolExecutionPolicyWebhook" } ] }, "language_preference": { "type": "string", "nullable": true, "description": "Language preference (BCP-47), e.g., \"en-US\", \"es-ES\" (presence-aware)", "x-presence": "message", "x-protovalidate": { "string": { "minLen": "2", "pattern": "^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$" } }, "x-validation-scope": "request" }, "time_aware": { "description": "Time-aware generation options (current time, message timestamps, file timestamps)", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/TimeAwareConfigWebhook" } ] }, "turn_context": { "description": "Turn context configuration for turn-aware generation", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/TurnContextConfigWebhook" } ] }, "mem0": { "description": "Configuration for semantic memory search, context injection and extraction during generation.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/MemoryConfigWebhook" } ] }, "request_timeout_seconds": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Timeout for an individual model-provider request, in seconds. Zero selects the 30-second\ndefault; other values are clamped to the range 1–600.", "x-presence": "implicit" }, "file_resolution": { "description": "Configuration for resolving FILE_ID content parts to fresh signed URLs before calling a model\nprovider. When unset, unresolved content is skipped.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/FileResolutionConfigWebhook" } ] }, "clear_tools": { "type": "boolean", "description": "Set to true with an empty tools list in an override to clear inherited tools. An empty list\nalone inherits the base tools. This directive applies only when merging an override.", "x-presence": "implicit" }, "clear_client_tools": { "type": "boolean", "description": "Set to true with an empty client tools list in an override to clear inherited client tools for\nthat turn. An empty list alone inherits the base client tools, and a nonempty list replaces\nthem regardless of this directive. It applies only when merging an override and leaves server\ntool selection unchanged.", "x-presence": "implicit" }, "top_k": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Additional provider knobs", "x-presence": "explicit" }, "repetition_penalty": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Provider sampling penalty used to discourage repeated output.", "x-presence": "explicit" }, "logit_bias": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ] }, "description": "Per-token adjustments applied to the provider’s token-selection logits.", "x-presence": "collection" }, "top_logprobs": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of top token log probabilities requested from the provider.", "x-presence": "explicit" }, "min_p": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Minimum relative token probability used by supported sampling providers.", "x-presence": "explicit" }, "top_a": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Adaptive probability cutoff used by supported sampling providers.", "x-presence": "explicit" }, "user": { "type": "string", "description": "User identifier forwarded for provider-side request attribution.", "x-presence": "explicit" }, "modalities": { "type": "array", "items": { "oneOf": [ { "type": "string", "enum": [ "MODALITY_TEXT", "MODALITY_IMAGE", "MODALITY_AUDIO" ], "x-enumDescriptions": { "MODALITY_TEXT": "Request generated text output.", "MODALITY_IMAGE": "Request generated image output where the model supports it.", "MODALITY_AUDIO": "Request generated audio output where the model supports it." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "MODALITY_TEXT", "number": 1, "canonical": true, "description": "Request generated text output." }, { "name": "MODALITY_IMAGE", "number": 2, "canonical": true, "description": "Request generated image output where the model supports it." }, { "name": "MODALITY_AUDIO", "number": 3, "canonical": true, "description": "Request generated audio output where the model supports it." } ], "x-enum-description": "Output media requested from a model that supports that modality.", "description": "Output media requested from a model that supports that modality." }, "description": "Output modalities (e.g., [TEXT, IMAGE])", "x-presence": "collection" }, "plugins": { "type": "array", "items": { "$ref": "#/components/schemas/PluginConfigWebhook" }, "description": "Provider plugins requested for pre-processing or post-processing.", "x-presence": "collection" } }, "x-reference-model": { "title": "GenerationConfig", "url": "/api/models/generation-config#webhook" } }, "ResponseFormatWebhook": { "type": "object", "description": "Structured response control\n\nWhen 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.", "properties": { "json_object": { "type": "boolean", "description": "Whether the model provider is requested to return a valid JSON object.", "x-presence": "implicit" }, "json_schema": { "type": "object", "additionalProperties": true, "description": "JSON Schema describing the requested structured model output.", "x-presence": "message" }, "schema_name": { "type": "string", "description": "Human-readable name of the structured-output schema, included in structured-message metadata\nand in the provider request’s json_schema.name.", "x-presence": "implicit" }, "validate": { "type": "boolean", "description": "Enable server-side validation of the response against json_schema.\nDefault: true when json_schema is set (applied in Go when not explicitly set).", "x-presence": "explicit" }, "max_validation_retries": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum retries when server-side validation fails.\nDefault: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).", "x-presence": "explicit", "x-protovalidate": { "int32": { "lte": 3, "gte": 0 } }, "x-validation-scope": "request" }, "response_healing": { "type": "boolean", "description": "Enable response healing for structured JSON output. Defaults to enabled for non-streaming\nrequests with json_schema unless explicitly disabled.", "x-presence": "explicit" } }, "x-reference-model": { "title": "ResponseFormat", "url": "/api/models/response-format#webhook" } }, "ModelRoutingFilterWebhook": { "type": "object", "description": "ModelRoutingFilter defines metadata-based criteria for filtering model candidates.\nAll filters are ANDed — a model must pass every specified filter.\nUnset/zero-value fields are ignored (no filtering on that dimension).\n\nUnset 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.\n\n[`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.", "properties": { "min_context_length": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Minimum context window (tokens). Models below this are excluded.", "x-presence": "implicit" }, "min_max_completion_tokens": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Minimum max completion tokens. Models below this are excluded.\nModels reporting 0 (unknown) pass through (permissive).", "x-presence": "implicit" }, "required_input_modalities": { "type": "array", "items": { "type": "string" }, "description": "Required input modalities (e.g., [\"image\", \"audio\"]). Model must support ALL listed.\nModels with empty input_modalities are filtered out (strict).", "x-presence": "collection" }, "required_output_modalities": { "type": "array", "items": { "type": "string" }, "description": "Required output modalities (e.g., [\"image\"]). Model must support ALL listed.\nModels with empty output_modalities are filtered out (strict).", "x-presence": "collection" }, "max_prompt_cost": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Maximum cost per prompt token (e.g., 0.000003). 0 = no limit.\nUnparseable pricing strings pass through (permissive).", "x-presence": "implicit" }, "max_completion_cost": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Maximum cost per completion token. 0 = no limit.\nUnparseable pricing strings pass through (permissive).", "x-presence": "implicit" }, "exclude_moderated": { "type": "boolean", "description": "Exclude models with content moderation enabled.", "x-presence": "implicit" }, "required_parameters": { "type": "array", "items": { "type": "string" }, "description": "Required supported parameters (e.g., [\"tools\", \"response_format\"]).\nModel must support ALL listed.", "x-presence": "collection" } }, "x-reference-model": { "title": "ModelRoutingFilter", "url": "/api/models/model-routing-filter#webhook" } }, "ProviderPreferencesWebhook": { "type": "object", "description": "Routing preferences restricting and ordering the model providers eligible for a request.", "properties": { "order": { "type": "array", "items": { "type": "string" }, "description": "Preferred ordering of model providers for routing.", "x-presence": "collection" }, "allow_fallbacks": { "type": "boolean", "description": "Whether provider routing may fall back beyond the preferred order.", "x-presence": "implicit" }, "require_parameters": { "type": "boolean", "description": "Whether routing requires providers to support the requested parameters.", "x-presence": "implicit" }, "data_collection": { "oneOf": [ { "type": "string", "enum": [ "DATA_COLLECTION_MODE_ALLOW", "DATA_COLLECTION_MODE_DENY" ], "x-enumDescriptions": { "DATA_COLLECTION_MODE_ALLOW": "Allow routing to providers that may collect submitted data under their policies.", "DATA_COLLECTION_MODE_DENY": "Request routing only to providers that do not collect submitted data under the routing policy." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "DATA_COLLECTION_MODE_ALLOW", "number": 1, "canonical": true, "description": "Allow routing to providers that may collect submitted data under their policies." }, { "name": "DATA_COLLECTION_MODE_DENY", "number": 2, "canonical": true, "description": "Request routing only to providers that do not collect submitted data under the routing policy." } ], "x-enum-description": "Provider-routing preference for whether providers may collect submitted data.", "description": "Provider data-collection preference used when routing the request.", "x-presence": "implicit" }, "zdr": { "type": "boolean", "description": "Whether routing requests providers offering zero data retention.", "x-presence": "implicit" }, "only": { "type": "array", "items": { "type": "string" }, "description": "Provider identifiers allowed by the routing preference.", "x-presence": "collection" }, "ignore": { "type": "array", "items": { "type": "string" }, "description": "Provider identifiers excluded by the routing preference.", "x-presence": "collection" }, "quantizations": { "type": "array", "items": { "type": "string" }, "description": "Model quantization formats allowed by the routing preference.", "x-presence": "collection" }, "sort": { "oneOf": [ { "type": "string", "enum": [ "PROVIDER_SORT_PRICE", "PROVIDER_SORT_THROUGHPUT", "PROVIDER_SORT_LATENCY" ], "x-enumDescriptions": { "PROVIDER_SORT_PRICE": "Prefer providers with lower price.", "PROVIDER_SORT_THROUGHPUT": "Prefer providers with higher throughput.", "PROVIDER_SORT_LATENCY": "Prefer providers with lower latency." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "PROVIDER_SORT_PRICE", "number": 1, "canonical": true, "description": "Prefer providers with lower price." }, { "name": "PROVIDER_SORT_THROUGHPUT", "number": 2, "canonical": true, "description": "Prefer providers with higher throughput." }, { "name": "PROVIDER_SORT_LATENCY", "number": 3, "canonical": true, "description": "Prefer providers with lower latency." } ], "x-enum-description": "Metric used to order eligible model providers.", "description": "Metric used to order eligible model providers.", "x-presence": "implicit" }, "max_price": { "description": "Upper price bounds used when selecting a model provider.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ProviderMaxPriceWebhook" } ] }, "enforce_distillable_text": { "type": "boolean", "description": "Embeddings: enforce distillable text.", "x-presence": "implicit" }, "preferred_min_throughput": { "description": "Deprioritize providers below this throughput (tokens/sec).\nDoes not exclude — just pushes to end of preference list.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PercentileThresholdWebhook" } ] }, "preferred_max_latency": { "description": "Deprioritize providers above this latency (ms).", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PercentileThresholdWebhook" } ] } }, "x-reference-model": { "title": "ProviderPreferences", "url": "/api/models/provider-preferences#webhook" } }, "ProviderMaxPriceWebhook": { "type": "object", "description": "Routing / provider preferences (generic superset)", "properties": { "prompt": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "$/1M prompt tokens.", "x-presence": "implicit" }, "completion": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "$/1M completion tokens.", "x-presence": "implicit" }, "request": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Maximum provider cost allowed per request, in US dollars.", "x-presence": "implicit" }, "image": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Maximum provider cost allowed per image, in US dollars.", "x-presence": "implicit" }, "audio": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "$/1M audio tokens.", "x-presence": "implicit" } }, "x-reference-model": { "title": "ProviderMaxPrice", "url": "/api/models/provider-max-price#webhook" } }, "PercentileThresholdWebhook": { "type": "object", "description": "Percentile thresholds for provider performance metrics", "properties": { "p50": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Threshold applied to the provider metric’s 50th percentile.", "x-presence": "implicit" }, "p90": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Threshold applied to the provider metric’s 90th percentile.", "x-presence": "implicit" } }, "x-reference-model": { "title": "PercentileThreshold", "url": "/api/models/percentile-threshold#webhook" } }, "ReasoningOptionsWebhook": { "type": "object", "description": "Reasoning options\n\nSupported 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.", "properties": { "effort": { "oneOf": [ { "type": "string", "enum": [ "EFFORT_HIGH", "EFFORT_MEDIUM", "EFFORT_LOW", "EFFORT_XHIGH", "EFFORT_MINIMAL", "EFFORT_NONE" ], "x-enumDescriptions": { "EFFORT_HIGH": "Request the provider's high reasoning-effort level.", "EFFORT_MEDIUM": "Request the provider's medium reasoning-effort level.", "EFFORT_LOW": "Request the provider's low reasoning-effort level.", "EFFORT_XHIGH": "Request the provider's extra-high reasoning-effort level where supported.", "EFFORT_MINIMAL": "Request the provider's minimal reasoning-effort level where supported.", "EFFORT_NONE": "Request no reasoning effort where the provider supports disabling it." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "EFFORT_HIGH", "number": 1, "canonical": true, "description": "Request the provider's high reasoning-effort level." }, { "name": "EFFORT_MEDIUM", "number": 2, "canonical": true, "description": "Request the provider's medium reasoning-effort level." }, { "name": "EFFORT_LOW", "number": 3, "canonical": true, "description": "Request the provider's low reasoning-effort level." }, { "name": "EFFORT_XHIGH", "number": 4, "canonical": true, "description": "Request the provider's extra-high reasoning-effort level where supported." }, { "name": "EFFORT_MINIMAL", "number": 5, "canonical": true, "description": "Request the provider's minimal reasoning-effort level where supported." }, { "name": "EFFORT_NONE", "number": 6, "canonical": true, "description": "Request no reasoning effort where the provider supports disabling it." } ], "x-enum-description": "Requested reasoning effort sent to the model provider; supported levels and their effect\ndepend on the chosen model.", "description": "Requested model reasoning effort.", "x-presence": "implicit" }, "max_tokens": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum reasoning-token count requested from the model provider.", "x-presence": "implicit" }, "exclude": { "type": "boolean", "description": "Whether the provider should omit reasoning content from its response.", "x-presence": "implicit" }, "include_reasoning_history": { "type": "boolean", "description": "When true (default), reasoning content from previous turns is included\nin multi-turn requests to enable provider continuity.", "x-presence": "implicit" } }, "x-reference-model": { "title": "ReasoningOptions", "url": "/api/models/reasoning-options#webhook" } }, "UsageOptionsWebhook": { "type": "object", "description": "Usage accounting preferences", "properties": { "include": { "type": "boolean", "description": "Whether usage accounting should be included in the provider response.", "x-presence": "implicit" } }, "x-reference-model": { "title": "UsageOptions", "url": "/api/models/usage-options#webhook" } }, "ToolDefinitionWebhook": { "type": "object", "description": "Canonical tool/function definition used across all services\n\n**[`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.\n\n**[`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.", "properties": { "name": { "type": "string", "description": "Name used to select and invoke the tool.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "description": { "type": "string", "description": "Explanation of the tool’s purpose supplied to the model and callers.", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "parameters_json_schema": { "type": "object", "additionalProperties": true, "description": "JSON Schema object.", "x-presence": "message" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional tool metadata (version, category, etc.).", "x-presence": "collection" }, "server_id": { "type": "string", "description": "Which server provides this tool (for MCP tools).", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tool categorization tags.", "x-presence": "collection" }, "documentation_url": { "type": "string", "description": "Link to detailed documentation.", "x-presence": "implicit" }, "output_json_schema": { "type": "object", "additionalProperties": true, "description": "Optional output schema (JSON Schema serialized as string) describing structured results", "x-presence": "message" } }, "x-reference-model": { "title": "ToolDefinition", "url": "/api/models/tool-definition#webhook" }, "x-request-required": [ "name", "description", "server_id" ] }, "ToolChoiceWebhook": { "type": "object", "description": "Policy selecting automatic tool choice, no tool use, or a named tool.", "properties": { "kind": { "oneOf": [ { "type": "string", "enum": [ "TOOL_CHOICE_KIND_AUTO", "TOOL_CHOICE_KIND_NONE", "TOOL_CHOICE_KIND_SPECIFIC" ], "x-enumDescriptions": { "TOOL_CHOICE_KIND_AUTO": "Let the provider decide whether to call an available tool.", "TOOL_CHOICE_KIND_NONE": "Disable tool selection for this generation.", "TOOL_CHOICE_KIND_SPECIFIC": "Require the named tool specified by the enclosing tool-choice configuration." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "TOOL_CHOICE_KIND_AUTO", "number": 1, "canonical": true, "description": "Let the provider decide whether to call an available tool." }, { "name": "TOOL_CHOICE_KIND_NONE", "number": 2, "canonical": true, "description": "Disable tool selection for this generation." }, { "name": "TOOL_CHOICE_KIND_SPECIFIC", "number": 3, "canonical": true, "description": "Require the named tool specified by the enclosing tool-choice configuration." } ], "x-enum-description": "How the model provider should choose whether and which tool to call.", "description": "Discriminator selecting the representation or policy used by this message.", "x-presence": "implicit" }, "specific_tool_name": { "type": "string", "description": "Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.", "x-presence": "implicit" } }, "x-reference-model": { "title": "ToolChoice", "url": "/api/models/tool-choice#webhook" } }, "ToolExecutionPolicyWebhook": { "type": "object", "description": "Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget\nand answer windows. Some stored controls are not enforced by the current workflow.\n\nIf an expected approval does not appear, inspect the tool/server require rules and\nauto-approve exceptions. Auto-approve takes precedence; server IDs are compared\ncase-insensitively after trimming whitespace. An exception does not establish that\nthe user reviewed the action.\n\nAn omitted or zero [`approvalTimeoutMs`](/api/models/tool-execution-policy#request-field-approvaltimeoutms)\nwaits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#request-field-failonapprovaltimeouttoolnamepatterns)\nyields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes\nevery expiry `FAILED`.\n\nThe retry controls [`retriableToolNamePatterns`](/api/models/tool-execution-policy#request-field-retriabletoolnamepatterns),\n[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),\n[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),\n[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and\n[`retryBackoff`](/api/models/tool-execution-policy#request-field-retrybackoff) are\nstored but do not schedule retries. Ordering rules, tie-breaking, the per-loop\ncall cap, client-tool scheduling mode, failure mode and stop-on-failure rules are\nalso not enforced; do not rely on them as execution or safety controls.\n\n[`maxTotalToolCalls`](/api/models/tool-execution-policy#request-field-maxtotaltoolcalls)\nlimits admitted calls across the run; zero or omission leaves the cap unset. A\nclient call consumes budget when armed. A routable MCP call consumes budget before\napproval, including when held for approval or later rejected. Unknown tools and\ncalls refused because the cap is already exhausted do not consume budget. Further\ncalls at the limit receive `FAILED` tool results naming the limit, which the model\ncan use when continuing the run.\n\n[`maxParallelToolCalls`](/api/models/tool-execution-policy#request-field-maxparalleltoolcalls)\nlimits concurrent MCP execution. Zero or one runs MCP calls sequentially; values\ngreater than one permit concurrency. Client calls are armed separately, and your\napplication controls their execution concurrency.\n\nChoose [`clientToolTimeoutMs`](/api/models/tool-execution-policy#request-field-clienttooltimeoutms)\nfor your application's validation and action. Zero or omission gives a five-minute\nanswer window; there is no unbounded setting. Each call returns its resolved\n[`clientToolDeadlineAt`](/api/models/tool-call#response-field-clienttooldeadlineat).\n\nSee [Tool execution policies](/api/tool-execution/policies) for policy selection and\ncaller reconciliation.", "properties": { "require_approval_tool_name_patterns": { "type": "array", "items": { "type": "string" }, "description": "Approvals\nTool-name patterns selecting calls that require an approval decision.", "x-presence": "collection" }, "require_approval_server_ids": { "type": "array", "items": { "type": "string" }, "description": "MCP server identifiers whose calls require approval. IDs are compared case-insensitively\nafter trimming whitespace.", "x-presence": "collection" }, "auto_approve_tool_name_patterns": { "type": "array", "items": { "type": "string" }, "description": "Tool-name patterns whose matching calls may be approved automatically.", "x-presence": "collection" }, "auto_approve_server_ids": { "type": "array", "items": { "type": "string" }, "description": "MCP server identifiers exempted from approval require rules. IDs are compared\ncase-insensitively after trimming whitespace.", "x-presence": "collection" }, "approval_mode": { "oneOf": [ { "type": "string", "enum": [ "APPROVAL_MODE_MIXED", "APPROVAL_MODE_BLOCK_ALL" ], "x-enumDescriptions": { "APPROVAL_MODE_MIXED": "Run automatically approved calls immediately and hold only calls that require approval.", "APPROVAL_MODE_BLOCK_ALL": "Hold execution of all tool calls in the loop until the approval-required calls are approved or\nrejected." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "APPROVAL_MODE_MIXED", "number": 1, "canonical": true, "description": "Run automatically approved calls immediately and hold only calls that require approval." }, { "name": "APPROVAL_MODE_BLOCK_ALL", "number": 2, "canonical": true, "description": "Hold execution of all tool calls in the loop until the approval-required calls are approved or\nrejected." } ], "x-enum-description": "How approval-required tool calls affect other tool calls in the same execution loop.", "description": "How to schedule execution when approvals are required for some tools", "x-presence": "implicit" }, "client_tool_mode": { "oneOf": [ { "type": "string", "enum": [ "CLIENT_TOOL_MODE_MIXED", "CLIENT_TOOL_MODE_BLOCK_ALL" ], "x-enumDescriptions": { "CLIENT_TOOL_MODE_MIXED": "Record pending client tools and continue with server-executed MCP tools and the loop.", "CLIENT_TOOL_MODE_BLOCK_ALL": "Hold loop advancement until the caller submits results for all pending client tools." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "CLIENT_TOOL_MODE_MIXED", "number": 1, "canonical": true, "description": "Record pending client tools and continue with server-executed MCP tools and the loop." }, { "name": "CLIENT_TOOL_MODE_BLOCK_ALL", "number": 2, "canonical": true, "description": "Hold loop advancement until the caller submits results for all pending client tools." } ], "x-enum-description": "How unresolved caller-executed tools affect progression of the tool loop.", "description": "Stored requested client-tool scheduling mode; not enforced by the current workflow.", "x-presence": "implicit" }, "approval_timeout_ms": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Time allowed for an approval decision, in milliseconds. Zero or omission selects the\nfive-minute default; a positive value overrides it. There is no unbounded wait setting.\nAt expiry, matching fail_on_approval_timeout_tool_name_patterns produces FAILED;\nother calls become TIMED_OUT. An empty pattern list makes every expiry FAILED.", "x-presence": "implicit" }, "fail_on_approval_timeout_tool_name_patterns": { "type": "array", "items": { "type": "string" }, "description": "Selects approval timeouts reported as FAILED; nonmatching calls become TIMED_OUT.\nAn empty list makes every approval expiry FAILED. Global failure_mode is not enforced.", "x-presence": "collection" }, "order_rules": { "type": "array", "items": { "$ref": "#/components/schemas/ToolExecutionOrderRuleWebhook" }, "description": "Stored requested ordering rules; not applied by the current generation workflow.", "x-presence": "collection" }, "stable_sort_by_call_index_on_tie": { "type": "boolean", "description": "Stored requested ordering tie-breaker; not applied by the current generation workflow.", "x-presence": "implicit" }, "max_parallel_tool_calls": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls\nsequentially; larger values permit concurrency. Client calls are armed separately,\nand their execution concurrency is controlled by the caller application.", "x-presence": "implicit" }, "max_tool_calls_per_loop": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Stored requested per-loop tool-call cap; not enforced by the current generation workflow.", "x-presence": "implicit" }, "max_total_tool_calls": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum admitted tool calls across the run; zero or omission leaves the cap unset.\nClient calls count when armed. Routable MCP calls count before approval, including\ncalls later rejected. Unknown tools and calls refused by an exhausted cap do not count.", "x-presence": "implicit" }, "retriable_tool_name_patterns": { "type": "array", "items": { "type": "string" }, "description": "Stored requested retry selection; does not enable retries in the current workflow.", "x-presence": "collection" }, "max_retries": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Stored requested retry count; does not enable retries in the current workflow.", "x-presence": "implicit" }, "retry_backoff": { "description": "Stored requested retry delays; not applied by the current generation workflow.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/BackoffWebhook" } ] }, "retryable_error_substrings": { "type": "array", "items": { "type": "string" }, "description": "Stored requested retryable-error selection; not evaluated by the current workflow.", "x-presence": "collection" }, "non_retryable_error_substrings": { "type": "array", "items": { "type": "string" }, "description": "Stored requested retry exclusions; not evaluated by the current generation workflow.", "x-presence": "collection" }, "timeouts": { "description": "Timeouts\nOverall execution time budget for the generation run.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/TimeoutPolicyWebhook" } ] }, "client_tool_timeout_ms": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Time allowed for a client-side tool result, in milliseconds. Zero or omission selects\nthe five-minute default; a positive value overrides it. There is no unbounded wait.\nThe resolved answer deadline is returned as clientToolDeadlineAt on each call.\nA result arriving after the deadline is rejected. At expiry, an empty or matching\nfail_on_approval_timeout_tool_name_patterns list yields FAILED; other calls become TIMED_OUT.\nExpiry closes the answer window and does not cancel a client action already in progress.", "x-presence": "implicit" }, "failure_mode": { "oneOf": [ { "type": "string", "enum": [ "FAILURE_MODE_CONTINUE", "FAILURE_MODE_STOP_LOOP", "FAILURE_MODE_STOP_RUN" ], "x-enumDescriptions": { "FAILURE_MODE_CONTINUE": "Request continued processing after the failed tool call.", "FAILURE_MODE_STOP_LOOP": "Request stopping the current tool-execution loop after the failure.", "FAILURE_MODE_STOP_RUN": "Request stopping the generation run after the failure." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "FAILURE_MODE_CONTINUE", "number": 1, "canonical": true, "description": "Request continued processing after the failed tool call." }, { "name": "FAILURE_MODE_STOP_LOOP", "number": 2, "canonical": true, "description": "Request stopping the current tool-execution loop after the failure." }, { "name": "FAILURE_MODE_STOP_RUN", "number": 3, "canonical": true, "description": "Request stopping the generation run after the failure." } ], "x-enum-description": "Requested scope of stopping after a tool execution failure.", "description": "Stored requested failure action; not enforced by the current generation workflow.", "x-presence": "implicit" }, "stop_on_failure_rules": { "type": "array", "items": { "$ref": "#/components/schemas/StopOnFailureRuleWebhook" }, "description": "Stored requested stop rules; not evaluated by the current generation workflow.", "x-presence": "collection" } }, "x-reference-model": { "title": "ToolExecutionPolicy", "url": "/api/models/tool-execution-policy#webhook" } }, "ToolExecutionOrderRuleWebhook": { "type": "object", "description": "Requested ordering rule for tool execution. The current generation workflow stores\nthese rules but does not apply their patterns, server filters or weights.", "properties": { "tool_name_patterns": { "type": "array", "items": { "type": "string" }, "description": "Requested tool-name patterns; not evaluated by the current generation workflow.", "x-presence": "collection" }, "server_ids": { "type": "array", "items": { "type": "string" }, "description": "Requested MCP server filter; not evaluated by the current generation workflow.", "x-presence": "collection" }, "weight": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Requested ordering weight; not applied by the current generation workflow.", "x-presence": "implicit" } }, "x-reference-model": { "title": "ToolExecutionOrderRule", "url": "/api/models/tool-execution-order-rule#webhook" } }, "BackoffWebhook": { "type": "object", "description": "Requested initial delay, growth factor and upper bound for tool-call retries.\nThe current generation workflow stores this configuration but does not schedule\nretries from it.", "properties": { "initial_ms": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Requested initial retry delay in milliseconds; not applied by the current generation workflow.", "x-presence": "implicit" }, "multiplier": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Requested retry-delay multiplier; not applied by the current generation workflow.", "x-presence": "implicit" }, "max_ms": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Requested maximum retry delay in milliseconds; not applied by the current generation workflow.", "x-presence": "implicit" } }, "x-reference-model": { "title": "Backoff", "url": "/api/models/backoff#webhook" } }, "TimeoutPolicyWebhook": { "type": "object", "description": "Bounds the run as a whole. This message has no per-tool or per-loop execution\ntimeout. Approval and client-result answer windows are configured separately on\nToolExecutionPolicy; those waits do not cancel an already dispatched remote action.\n\nSet a finite [`timeouts.overallMs`](/api/models/timeout-policy#request-field-overallms)\nwhen the task needs a duration limit. It is measured from run start; zero or\nomission leaves the run-level duration unbounded.\n\nWhen Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and\npending calls can be closed with `endReason: \"run_timed_out\"`. A call still awaiting\napproval has not been dispatched. The timeout does not guarantee a remote action\nstops at that instant, establish whether it took effect, or roll it back.\n\nUse [`endReason`](/api/models/tool-call#response-field-endreason) to distinguish a\nrun deadline from a call's own answer window: an unanswered approval reads\n`approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the\nactual tool status too; approval and client-tool expiry can produce `FAILED` or\n`TIMED_OUT`. Run and individual tool outcomes are different fields.", "properties": { "overall_ms": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Overall run budget in milliseconds, measured from run start. Zero or omission\nleaves this run-level bound unset. The workflow checks the deadline and can end\nwith AGENT_STATUS_TIMED_OUT; it cannot cancel or undo a remote action already\ndispatched. Approval and client-result waits retain their separate finite limits.", "x-presence": "implicit" } }, "x-reference-model": { "title": "TimeoutPolicy", "url": "/api/models/timeout-policy#webhook" } }, "StopOnFailureRuleWebhook": { "type": "object", "description": "Requested tool-selection rule for handling an execution failure. The current\ngeneration workflow stores these rules but does not evaluate them or stop a loop\nor run because of them.\n\nThe conditions in [`stopOnFailureRules`](/api/models/tool-execution-policy#request-field-stoponfailurerules),\nincluding [`priority`](/api/models/stop-on-failure-rule#request-field-priority),\ntimeout inclusion and error matching, are not enforced. Do not rely on these\nfields as a stop control.", "properties": { "tool_name_patterns": { "type": "array", "items": { "type": "string" }, "description": "Requested tool-name selection; not evaluated by the current generation workflow.", "x-presence": "collection" }, "server_ids": { "type": "array", "items": { "type": "string" }, "description": "Requested MCP server selection; not evaluated by the current generation workflow.", "x-presence": "collection" }, "on_failure": { "oneOf": [ { "type": "string", "enum": [ "FAILURE_MODE_CONTINUE", "FAILURE_MODE_STOP_LOOP", "FAILURE_MODE_STOP_RUN" ], "x-enumDescriptions": { "FAILURE_MODE_CONTINUE": "Request continued processing after the failed tool call.", "FAILURE_MODE_STOP_LOOP": "Request stopping the current tool-execution loop after the failure.", "FAILURE_MODE_STOP_RUN": "Request stopping the generation run after the failure." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "FAILURE_MODE_CONTINUE", "number": 1, "canonical": true, "description": "Request continued processing after the failed tool call." }, { "name": "FAILURE_MODE_STOP_LOOP", "number": 2, "canonical": true, "description": "Request stopping the current tool-execution loop after the failure." }, { "name": "FAILURE_MODE_STOP_RUN", "number": 3, "canonical": true, "description": "Request stopping the generation run after the failure." } ], "x-enum-description": "Requested scope of stopping after a tool execution failure.", "description": "Requested failure action; not evaluated by the current generation workflow.", "x-presence": "implicit" }, "include_timeouts": { "type": "boolean", "description": "Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.", "x-presence": "implicit" }, "error_substrings": { "type": "array", "items": { "type": "string" }, "description": "Requested error-text selection; not evaluated by the current generation workflow.", "x-presence": "collection" }, "priority": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Requested rule priority; not evaluated by the current generation workflow.", "x-presence": "implicit" } }, "x-reference-model": { "title": "StopOnFailureRule", "url": "/api/models/stop-on-failure-rule#webhook" } }, "TimeAwareConfigWebhook": { "type": "object", "description": "Configuration for time-aware LLM generation.\nControls injection of temporal context (current time, message timestamps,\nfile timestamps) into the LLM context during generation.", "properties": { "include_current_time": { "type": "boolean", "description": "Append the current date and time to the system prompt as temporal context. Default: true.", "x-presence": "implicit" }, "include_message_timestamps": { "type": "boolean", "description": "Include timestamps on messages in the model context. Requires the message timestamp to be\npopulated. Default: false.", "x-presence": "implicit" }, "include_file_timestamps": { "type": "boolean", "description": "Include upload/modification timestamps when resolving FILE_ID content.\nWhen true, resolved file references include \"[Uploaded: ]\" annotations.\nDefault: false", "x-presence": "implicit" }, "timezone": { "type": "string", "description": "Timezone for formatting (IANA format, e.g., \"America/Los_Angeles\").\nDefault: \"UTC\"", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "50" } }, "x-validation-scope": "request" }, "timestamp_format": { "type": "string", "description": "Format pattern for timestamps.\n\"friendly\" (default): \"Jan 2, 2026 at 3:04 PM MST\"\n\"iso8601\": \"2026-01-02T15:04:00-08:00\"\n\"date_only\": \"2026-01-02\"", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "50", "in": [ "", "friendly", "iso8601", "date_only" ] } }, "x-validation-scope": "request" } }, "x-reference-model": { "title": "TimeAwareConfig", "url": "/api/models/time-aware-config#webhook" } }, "TurnContextConfigWebhook": { "type": "object", "description": "Configuration for turn-aware LLM generation\n\nTurn 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.", "properties": { "enabled": { "type": "boolean", "description": "Enable turn context injection into system prompt\nDefault: true", "x-presence": "implicit" }, "include_tool_guidance": { "type": "boolean", "description": "Include tool usage guidance based on remaining turns\nDefault: false (can enable for agentic workflows)", "x-presence": "implicit" }, "format": { "type": "string", "description": "Format for turn context\n\"minimal\": \"[Turn 2/5]\"\n\"standard\": \"[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]\"\n\"verbose\": Includes detailed behavioral guidance\nDefault: \"standard\"", "x-presence": "implicit", "x-protovalidate": { "string": { "in": [ "minimal", "standard", "verbose" ] } }, "x-validation-scope": "request" } }, "x-reference-model": { "title": "TurnContextConfig", "url": "/api/models/turn-context-config#webhook" }, "x-request-required": [ "format" ] }, "MemoryConfigWebhook": { "type": "object", "description": "Configuration for searching, injecting and storing semantic memories during generation.\n\nMemory 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)\n(set at thread creation or via `update-default-generation-config`) or per turn via\n[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).\n\nEnabled 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.\n\nReranking 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.\n\n[`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.", "properties": { "enabled": { "type": "boolean", "description": "Enable searching for relevant memories, adding them to generation context and extracting new\nmemories after generation. Default: false.", "x-presence": "implicit" }, "search_top_k": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of memories to retrieve during search.\nHigher values provide more context but increase token usage.\n\nRange: 1-50 (validated only when enabled = true)\nDefault: 5", "x-presence": "implicit" }, "search_threshold": { "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN", "Infinity", "-Infinity" ] } ], "description": "Minimum relevance score threshold for memory search results.\nMemories below this threshold are filtered out.\nRange: 0.0-1.0 (validated only when enabled = true)\nDefault: 0.3", "x-presence": "implicit" }, "inject_as_system_context": { "type": "boolean", "description": "When true, inject found memories into the system prompt context.\nMemories are formatted as a bullet list under a \"[Relevant memories:]\" header.\nDefault: true", "x-presence": "implicit" }, "search_query_override": { "type": "string", "description": "Custom search query to use instead of the last user message.\nIf empty, the last user message content is used as the search query.", "x-presence": "implicit" }, "enable_rerank": { "type": "boolean", "description": "Enable reranking for improved search relevance.\nReranking provides better results but adds latency.\nDefault: false", "x-presence": "implicit" }, "add_memories_async": { "type": "boolean", "description": "When true, memory extraction happens asynchronously after generation completes.\nThis prevents extraction latency from affecting response time.\nDefault: true", "x-presence": "implicit" }, "custom_extraction_prompt": { "type": "string", "description": "Custom prompt for memory/fact extraction.\nIf empty, the default extraction prompt is used.\nUse this to customize what types of facts are extracted.", "x-presence": "implicit" }, "enable_graph": { "type": "boolean", "description": "Enable relationship extraction and graph-based memory search when graph memory is configured.\nDefault: false.", "x-presence": "implicit" }, "agent_id_override": { "type": "string", "description": "Override the agent_id used for memory scoping.\nBy default, the conversation_id is used as the agent_id.\nUse this to share memories across multiple conversations.", "x-presence": "implicit" }, "expose_as_mcp_tool": { "type": "boolean", "description": "Expose memory search as an MCP tool during generation.\nWhen true, the LLM can explicitly search memories via tool calls.\nRate limited to 3 searches per generation turn.\nDefault: false", "x-presence": "implicit" }, "include_assistant_messages": { "type": "boolean", "description": "Include assistant/agent-scoped memories in operations.\nWhen false, skips agent_id for both add and search operations,\nkeeping only user-scoped memories.\nDefault: false", "x-presence": "implicit" }, "inject_memory_timestamps": { "type": "boolean", "description": "Include created_at/updated_at timestamps on injected memories.\nWhen true, each memory bullet includes a \"(remembered: )\" annotation\nand optionally \"(updated: )\" if the memory was modified after creation.\nDefault: true", "x-presence": "implicit" } }, "x-reference-model": { "title": "MemoryConfig", "url": "/api/models/memory-config#webhook" }, "x-protovalidate": { "cel": [ { "id": "mem0_config_valid_when_enabled", "message": "search_top_k and search_threshold must be valid when enabled is true", "expression": "!this.enabled || ((this.search_top_k >= 1 && this.search_top_k <= 50) && (this.search_threshold >= 0.0 && this.search_threshold <= 1.0))" } ] }, "x-validation-scope": "request" }, "FileResolutionConfigWebhook": { "type": "object", "description": "Configuration for resolving CONTENT_PART_TYPE_FILE_ID parts to fresh signed\nURLs before requests are sent to LLM providers. Keeps stable file references\nin message history while generating ephemeral URLs only when needed.\n\nOmitting 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.", "properties": { "failure_mode": { "oneOf": [ { "type": "string", "enum": [ "FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION", "FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT" ], "x-enumDescriptions": { "FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION": "Fail generation when a file content part cannot be resolved.", "FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT": "Skip the unresolved content part and continue with the remaining content." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION", "number": 1, "canonical": true, "description": "Fail generation when a file content part cannot be resolved." }, { "name": "FILE_RESOLUTION_FAILURE_MODE_SKIP_CONTENT", "number": 2, "canonical": true, "description": "Skip the unresolved content part and continue with the remaining content." } ], "x-enum-description": "How generation handles a content part whose file identifier cannot be resolved.", "description": "Action to take when a file cannot be resolved. If omitted, skip unresolved file content\nand use the remaining content.", "x-presence": "implicit" } }, "x-reference-model": { "title": "FileResolutionConfig", "url": "/api/models/file-resolution-config#webhook" } }, "PluginConfigWebhook": { "type": "object", "description": "Provider plugin identifier and its parser, search, or additional configuration.", "properties": { "id": { "type": "string", "description": "Provider plugin identifier, such as file-parser.", "x-presence": "implicit" }, "pdf": { "description": "PDF annotation or parser configuration selected by the enclosing message.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PluginPDFConfigWebhook" } ] }, "web": { "description": "Web-search configuration for the selected generation plugin.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/PluginWebConfigWebhook" } ] }, "params": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional provider-specific plugin parameters.", "x-presence": "collection" } }, "x-reference-model": { "title": "PluginConfig", "url": "/api/models/plugin-config#webhook" } }, "PluginPDFConfigWebhook": { "type": "object", "description": "Plugins for pre/post-processing (generic representation)", "properties": { "engine": { "type": "string", "description": "PDF parsing engine selected for the provider plugin.", "x-presence": "implicit" } }, "x-reference-model": { "title": "PluginPDFConfig", "url": "/api/models/plugin-pdf-config#webhook" } }, "PluginWebConfigWebhook": { "type": "object", "description": "Provider web-search configuration used to augment a generation request.", "properties": { "engine": { "type": "string", "description": "Search engine selected for the provider’s web-search plugin.", "x-presence": "implicit" }, "max_results": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Maximum web-search result count requested by the plugin.", "x-presence": "implicit" }, "search_prompt": { "type": "string", "description": "Instructions supplied to the web-search plugin.", "x-presence": "implicit" }, "web_search_options": { "description": "Options controlling the amount of web-search context requested.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/WebSearchOptionsWebhook" } ] } }, "x-reference-model": { "title": "PluginWebConfig", "url": "/api/models/plugin-web-config#webhook" } }, "WebSearchOptionsWebhook": { "type": "object", "description": "Amount of web-search context requested for generation.", "properties": { "search_context_size": { "type": "string", "description": "Requested amount of web-search context: low, medium, or high.", "x-presence": "implicit" } }, "x-reference-model": { "title": "WebSearchOptions", "url": "/api/models/web-search-options#webhook" } }, "MCPServerReferenceWebhook": { "type": "object", "description": "MCP Server Reference\nLightweight reference to pre-configured MCP servers used by workflows", "properties": { "server_id": { "type": "string", "description": "ID of pre-configured MCP server (e.g., \"github\", \"filesystem\").", "x-presence": "implicit", "x-protovalidate": { "string": { "minLen": "1" } }, "x-validation-scope": "request" }, "enabled": { "type": "boolean", "description": "Whether to use this MCP server. Omission means enabled; only an explicitly false value\nexcludes it from discovery.", "x-presence": "explicit" }, "priority": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Priority override for tool selection (higher = preferred).", "x-presence": "implicit" }, "allowlist_tool_patterns": { "type": "array", "items": { "type": "string" }, "description": "Only include tools matching these patterns (e.g., \"github_get_*\", \"search_*\").", "x-presence": "collection" }, "blocklist_tool_patterns": { "type": "array", "items": { "type": "string" }, "description": "Exclude tools matching these patterns (e.g., \"*_delete\", \"*_destroy\").", "x-presence": "collection" }, "server_overrides": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Override server settings for this usage.", "x-presence": "collection" } }, "x-reference-model": { "title": "MCPServerReference", "url": "/api/models/mcp-server-reference#webhook" }, "x-request-required": [ "server_id" ] }, "ClientContextWebhook": { "type": "object", "description": "Opaque caller-supplied attributes attached to a conversation message.\n\nValues 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.", "properties": { "values": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Arbitrary client-supplied context for this message (e.g. page, referrer,\ndevice, in-app flow). Keys/values are opaque strings.", "x-presence": "collection", "x-protovalidate": { "map": { "maxPairs": "32", "keys": { "string": { "maxLen": "64" } }, "values": { "string": { "maxLen": "1024" } } } }, "x-validation-scope": "request" } }, "x-reference-model": { "title": "ClientContext", "url": "/api/models/client-context#webhook" } }, "MessageFeedbackWebhook": { "type": "object", "description": "One user's feedback on an assistant-generated message.", "properties": { "kind": { "oneOf": [ { "type": "string", "enum": [ "FEEDBACK_KIND_THUMB", "FEEDBACK_KIND_SCALE" ], "x-enumDescriptions": { "FEEDBACK_KIND_THUMB": "Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice.", "FEEDBACK_KIND_SCALE": "Feedback expressed as an integer rating from 1 through 10." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "FEEDBACK_KIND_THUMB", "number": 1, "canonical": true, "description": "Binary positive or negative feedback, represented by a thumbs-up or thumbs-down choice." }, { "name": "FEEDBACK_KIND_SCALE", "number": 2, "canonical": true, "description": "Feedback expressed as an integer rating from 1 through 10." } ], "x-enum-description": "Value scale used to interpret recorded feedback.", "description": "Rating representation used to interpret the feedback value.", "x-presence": "implicit", "x-protovalidate": { "enum": { "definedOnly": true, "notIn": [ 0 ] } }, "x-validation-scope": "request" }, "thumb_up": { "type": "boolean", "description": "Positive when true and negative when false; used for THUMB feedback.", "x-presence": "implicit" }, "rating": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent.", "x-presence": "implicit", "x-protovalidate": { "int32": { "lte": 10, "gte": 0 } }, "x-validation-scope": "request" }, "reason": { "type": "string", "description": "Optional explanation for the rating.", "x-presence": "implicit", "x-protovalidate": { "string": { "maxLen": "1000" } }, "x-validation-scope": "request" }, "rated_at": { "type": "string", "format": "date-time", "description": "Timestamp when feedback was submitted (server-set)", "x-presence": "message" }, "rated_by": { "type": "string", "description": "Identifier of the user who submitted this feedback. Set by the server\nfrom the authenticated user identity; never client-supplied. Each user\nhas one feedback entry per message.", "x-presence": "implicit" } }, "x-reference-model": { "title": "MessageFeedback", "url": "/api/models/message-feedback#webhook" }, "x-request-required": [ "kind" ] }, "LLMGenerationStartedEventWebhook": { "type": "object", "description": "Event emitted when a generation run starts. The event context identifies the associated\nconversation.", "properties": { "event_context": { "description": "Event provenance and routing metadata associated with the emitted event.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/EventContextWebhook" } ] }, "run_id": { "type": "string", "description": "Unique identifier for the workflow run", "x-presence": "implicit" }, "config": { "description": "Optional snapshot of generation configuration used for this run", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/GenerationConfigWebhook" } ] }, "starting_sequence": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Conversation sequence number at the moment the run started (if known)", "x-presence": "implicit" } }, "x-reference-model": { "title": "LLMGenerationStartedEvent", "url": "/api/models/llm-generation-started-event#webhook" } }, "LLMGenerationCompletedEventWebhook": { "type": "object", "description": "Event emitted when a generation run reaches a terminal state. The event context identifies the\nassociated conversation.", "properties": { "event_context": { "description": "Event provenance and routing metadata associated with the emitted event.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/EventContextWebhook" } ] }, "run_id": { "type": "string", "description": "Unique identifier for the workflow run", "x-presence": "implicit" }, "status": { "oneOf": [ { "type": "string", "enum": [ "WORKFLOW_STATUS_RUNNING", "WORKFLOW_STATUS_COMPLETED", "WORKFLOW_STATUS_FAILED", "WORKFLOW_STATUS_TIMED_OUT", "WORKFLOW_STATUS_CANCELED" ], "x-enumDescriptions": { "WORKFLOW_STATUS_RUNNING": "The workflow has started and has not reached a terminal outcome.", "WORKFLOW_STATUS_COMPLETED": "The workflow finished successfully.", "WORKFLOW_STATUS_FAILED": "The workflow ended because execution failed; inspect its error or end reason.", "WORKFLOW_STATUS_TIMED_OUT": "The workflow ended because its execution time limit elapsed.", "WORKFLOW_STATUS_CANCELED": "The workflow was cancelled before normal completion. This enum retains its existing CANCELED\nwire spelling." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "WORKFLOW_STATUS_RUNNING", "number": 1, "canonical": true, "description": "The workflow has started and has not reached a terminal outcome." }, { "name": "WORKFLOW_STATUS_COMPLETED", "number": 2, "canonical": true, "description": "The workflow finished successfully." }, { "name": "WORKFLOW_STATUS_FAILED", "number": 3, "canonical": true, "description": "The workflow ended because execution failed; inspect its error or end reason." }, { "name": "WORKFLOW_STATUS_TIMED_OUT", "number": 4, "canonical": true, "description": "The workflow ended because its execution time limit elapsed." }, { "name": "WORKFLOW_STATUS_CANCELED", "number": 5, "canonical": true, "description": "The workflow was cancelled before normal completion. This enum retains its existing CANCELED\nwire spelling." } ], "x-enum-description": "Lifecycle state of a workflow execution, distinct from the reason a terminal execution ended.", "description": "Terminal status of the run", "x-presence": "implicit" }, "loop_count": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Number of agent loops/steps executed", "x-presence": "implicit" }, "duration_ms": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "End-to-end run duration in milliseconds", "x-presence": "implicit" }, "usage": { "description": "Optional usage accounting for the run", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/UsageWebhook" } ] }, "error": { "description": "Structured error for FAILED/TIMED_OUT/CANCELED runs.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/RpcErrorWebhook" } ] }, "usage_by_model": { "type": "array", "items": { "$ref": "#/components/schemas/UsageByModelWebhook" }, "description": "Per-model breakdown of the same usage `usage` aggregates. Additive: `usage`\nstays the run-level total so existing consumers are unaffected, while\nbilling keys its charges on model. Empty when the producer predates it.", "x-presence": "collection" }, "turn_key": { "type": "string", "description": "Identifies the conversation turn this run served: the message_id of the\nopening user message, resolved once at run start and stamped on every\nmessage the run emits as Message.source_user_message_id.\n\nEmpty when the producer predates this field, or when the turn is\nunresolvable — never guess one, an empty key means \"no turn attribution\".", "x-presence": "implicit" } }, "x-reference-model": { "title": "LLMGenerationCompletedEvent", "url": "/api/models/llm-generation-completed-event#webhook" } }, "RpcErrorWebhook": { "type": "object", "description": "Standardized error payload following google.rpc.Status (AIP-193).\nUsed across all response messages and event payloads.", "properties": { "code": { "oneOf": [ { "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" ], "x-enumDescriptions": { "ERROR_CODE_CANCELLED": "The caller cancelled the operation before it completed.", "ERROR_CODE_UNKNOWN": "The operation failed without a more specific error classification.", "ERROR_CODE_INVALID_ARGUMENT": "The request contains an invalid argument or field value.", "ERROR_CODE_DEADLINE_EXCEEDED": "The operation did not complete before its deadline.", "ERROR_CODE_NOT_FOUND": "The requested resource does not exist or could not be found.", "ERROR_CODE_ALREADY_EXISTS": "The requested creation conflicts with a resource that already exists.", "ERROR_CODE_PERMISSION_DENIED": "The authenticated caller is not permitted to perform the operation.", "ERROR_CODE_RESOURCE_EXHAUSTED": "A quota, rate limit or other capacity limit prevented the operation.", "ERROR_CODE_FAILED_PRECONDITION": "The operation requires a system or resource state that is not currently satisfied.", "ERROR_CODE_ABORTED": "The operation was aborted, for example by a concurrent modification conflict.", "ERROR_CODE_OUT_OF_RANGE": "An argument is outside the range supported by this operation.", "ERROR_CODE_UNIMPLEMENTED": "The requested operation is not implemented.", "ERROR_CODE_INTERNAL": "An internal failure prevented the operation from completing.", "ERROR_CODE_UNAVAILABLE": "The service or a required dependency is temporarily unavailable.", "ERROR_CODE_DATA_LOSS": "The operation encountered unrecoverable loss or corruption of data.", "ERROR_CODE_UNAUTHENTICATED": "Authentication credentials are missing or invalid.", "ERROR_CODE_MODEL_INVALID": "The requested model identifier is absent from the model catalog.", "ERROR_CODE_MODEL_UNAVAILABLE": "The model exists, but no provider is currently available to serve it.", "ERROR_CODE_MODERATION_FLAGGED": "Content moderation flagged the submitted content.", "ERROR_CODE_GENERATION_FAILED": "Model generation failed after its configured attempts.", "ERROR_CODE_TOOL_EXECUTION_FAILED": "Execution of a requested tool failed.", "ERROR_CODE_UPSTREAM_PROVIDER": "An upstream model provider returned an error.", "ERROR_CODE_VALIDATION_EXHAUSTED": "Structured-output validation still failed after the configured attempts.", "ERROR_CODE_PAYMENT_REQUIRED": "The account lacks the credits required for the operation." } }, { "type": "integer", "format": "int32", "not": { "enum": [ 0 ] } } ], "x-enum-values": [ { "name": "ERROR_CODE_CANCELLED", "number": 1, "canonical": true, "description": "The caller cancelled the operation before it completed." }, { "name": "ERROR_CODE_UNKNOWN", "number": 2, "canonical": true, "description": "The operation failed without a more specific error classification." }, { "name": "ERROR_CODE_INVALID_ARGUMENT", "number": 3, "canonical": true, "description": "The request contains an invalid argument or field value." }, { "name": "ERROR_CODE_DEADLINE_EXCEEDED", "number": 4, "canonical": true, "description": "The operation did not complete before its deadline." }, { "name": "ERROR_CODE_NOT_FOUND", "number": 5, "canonical": true, "description": "The requested resource does not exist or could not be found." }, { "name": "ERROR_CODE_ALREADY_EXISTS", "number": 6, "canonical": true, "description": "The requested creation conflicts with a resource that already exists." }, { "name": "ERROR_CODE_PERMISSION_DENIED", "number": 7, "canonical": true, "description": "The authenticated caller is not permitted to perform the operation." }, { "name": "ERROR_CODE_RESOURCE_EXHAUSTED", "number": 8, "canonical": true, "description": "A quota, rate limit or other capacity limit prevented the operation." }, { "name": "ERROR_CODE_FAILED_PRECONDITION", "number": 9, "canonical": true, "description": "The operation requires a system or resource state that is not currently satisfied." }, { "name": "ERROR_CODE_ABORTED", "number": 10, "canonical": true, "description": "The operation was aborted, for example by a concurrent modification conflict." }, { "name": "ERROR_CODE_OUT_OF_RANGE", "number": 11, "canonical": true, "description": "An argument is outside the range supported by this operation." }, { "name": "ERROR_CODE_UNIMPLEMENTED", "number": 12, "canonical": true, "description": "The requested operation is not implemented." }, { "name": "ERROR_CODE_INTERNAL", "number": 13, "canonical": true, "description": "An internal failure prevented the operation from completing." }, { "name": "ERROR_CODE_UNAVAILABLE", "number": 14, "canonical": true, "description": "The service or a required dependency is temporarily unavailable." }, { "name": "ERROR_CODE_DATA_LOSS", "number": 15, "canonical": true, "description": "The operation encountered unrecoverable loss or corruption of data." }, { "name": "ERROR_CODE_UNAUTHENTICATED", "number": 16, "canonical": true, "description": "Authentication credentials are missing or invalid." }, { "name": "ERROR_CODE_MODEL_INVALID", "number": 600, "canonical": true, "description": "The requested model identifier is absent from the model catalog." }, { "name": "ERROR_CODE_MODEL_UNAVAILABLE", "number": 601, "canonical": true, "description": "The model exists, but no provider is currently available to serve it." }, { "name": "ERROR_CODE_MODERATION_FLAGGED", "number": 602, "canonical": true, "description": "Content moderation flagged the submitted content." }, { "name": "ERROR_CODE_GENERATION_FAILED", "number": 603, "canonical": true, "description": "Model generation failed after its configured attempts." }, { "name": "ERROR_CODE_TOOL_EXECUTION_FAILED", "number": 604, "canonical": true, "description": "Execution of a requested tool failed." }, { "name": "ERROR_CODE_UPSTREAM_PROVIDER", "number": 605, "canonical": true, "description": "An upstream model provider returned an error." }, { "name": "ERROR_CODE_VALIDATION_EXHAUSTED", "number": 606, "canonical": true, "description": "Structured-output validation still failed after the configured attempts." }, { "name": "ERROR_CODE_PAYMENT_REQUIRED", "number": 607, "canonical": true, "description": "The account lacks the credits required for the operation." } ], "x-enum-description": "Machine-readable reason that a request or operation failed; inspect the accompanying error\ndetails for context.", "description": "Machine-readable error code. Clients switch on this field.", "x-presence": "implicit" }, "message": { "type": "string", "description": "Human-readable error description. Intended for developers, not end users.\nMust not be parsed programmatically — use code and details instead.", "x-presence": "implicit" }, "is_terminal": { "type": "boolean", "description": "Whether this error is terminal (non-retryable). When true, repeating the\nsame request will produce the same error. When false, transient condition\nmay resolve on retry.", "x-presence": "implicit" }, "details": { "description": "Structured error details. At most one of each detail type.\nFollows google.rpc.Status details pattern but uses concrete types\ninstead of google.protobuf.Any for type safety and codegen.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ErrorDetailsWebhook" } ] } }, "x-reference-model": { "title": "RpcError", "url": "/api/models/rpc-error#webhook" } }, "ErrorDetailsWebhook": { "type": "object", "description": "Typed error details container. Concrete fields instead of Any for\ntype safety across languages. At most one of each detail type.", "properties": { "error_info": { "description": "Identifies the error for machine consumption.\nREQUIRED on all errors per AIP-193 (enforced at Go helper level).", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ErrorInfoWebhook" } ] }, "retry_info": { "description": "Retry guidance for transient errors.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/RetryInfoWebhook" } ] }, "field_violations": { "type": "array", "items": { "$ref": "#/components/schemas/FieldViolationWebhook" }, "description": "Field-level validation failures.", "x-presence": "collection" }, "upstream_error": { "description": "Upstream provider error context.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/UpstreamErrorWebhook" } ] }, "model_error": { "description": "Model-specific error context.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ModelErrorWebhook" } ] }, "help_links": { "type": "array", "items": { "$ref": "#/components/schemas/HelpLinkWebhook" }, "description": "Help links for error resolution.", "x-presence": "collection" } }, "x-reference-model": { "title": "ErrorDetails", "url": "/api/models/error-details#webhook" } }, "ErrorInfoWebhook": { "type": "object", "description": "Machine-readable error identification (per AIP-193, every error must include this).", "properties": { "reason": { "type": "string", "description": "Stable machine-readable reason string (e.g., \"MODEL_NOT_FOUND\",\n\"RATE_LIMITED\", \"MODERATION_FLAGGED\").\nUnique within the domain. Clients may switch on this field.", "x-presence": "implicit" }, "domain": { "type": "string", "description": "Machine-readable namespace identifying the origin of the error.", "x-presence": "implicit" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Arbitrary key-value metadata. If the message field mentions a specific\nvalue (model name, field path, etc.), it MUST also appear here.", "x-presence": "collection" } }, "x-reference-model": { "title": "ErrorInfo", "url": "/api/models/error-info#webhook" } }, "RetryInfoWebhook": { "type": "object", "description": "Retry guidance for transient errors.", "properties": { "retry_delay_ms": { "type": "string", "format": "int64", "pattern": "^-?\\d+$", "description": "Suggested minimum delay before retrying, in milliseconds.", "x-presence": "implicit" } }, "x-reference-model": { "title": "RetryInfo", "url": "/api/models/retry-info#webhook" } }, "FieldViolationWebhook": { "type": "object", "description": "A single field-level validation violation.", "properties": { "field": { "type": "string", "description": "Dot-separated path to the field (e.g., \"generation_config.model\").", "x-presence": "implicit" }, "description": { "type": "string", "description": "Human-readable description of the violation.", "x-presence": "implicit" } }, "x-reference-model": { "title": "FieldViolation", "url": "/api/models/field-violation#webhook" } }, "UpstreamErrorWebhook": { "type": "object", "description": "Context from an upstream provider error.", "properties": { "provider": { "type": "string", "description": "Name of the upstream provider that reported the error.", "x-presence": "implicit" }, "status_code": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "HTTP status code returned by the provider.", "x-presence": "implicit" }, "raw_body": { "type": "string", "description": "Raw error body from the provider. Truncated to 512 bytes (enforced at Go level).", "x-presence": "implicit" } }, "x-reference-model": { "title": "UpstreamError", "url": "/api/models/upstream-error#webhook" } }, "ModelErrorWebhook": { "type": "object", "description": "Model-specific error context.", "properties": { "model_id": { "type": "string", "description": "The model ID that caused the error.", "x-presence": "implicit" }, "reason": { "type": "string", "description": "Why the model failed (e.g., \"invalid\", \"unavailable\", \"moderation_flagged\").", "x-presence": "implicit" }, "alternatives_tried": { "type": "array", "items": { "type": "string" }, "description": "Alternative models that were tried or could be tried.", "x-presence": "collection" } }, "x-reference-model": { "title": "ModelError", "url": "/api/models/model-error#webhook" } }, "HelpLinkWebhook": { "type": "object", "description": "A help link for error resolution.", "properties": { "url": { "type": "string", "description": "URL to documentation or resolution guide.", "x-presence": "implicit" }, "description": { "type": "string", "description": "Description of what the link provides.", "x-presence": "implicit" } }, "x-reference-model": { "title": "HelpLink", "url": "/api/models/help-link#webhook" } }, "UsageByModelWebhook": { "type": "object", "description": "Usage attributed to a single model within one generation run.", "properties": { "model": { "type": "string", "description": "Model identifier as recorded on the assistant message that produced it.", "x-presence": "implicit" }, "calls": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Provider completions attributed to this model within the run.", "x-presence": "implicit" }, "usage": { "description": "Same shape as the run aggregate, scoped to this model.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/UsageWebhook" } ] } }, "x-reference-model": { "title": "UsageByModel", "url": "/api/models/usage-by-model#webhook" } }, "ToolCallStartedEventWebhook": { "type": "object", "description": "Event for a tool call that has begun execution or is waiting for human approval. Check the event\nname and tool-call status to distinguish these cases; the event context identifies the\nconversation.", "properties": { "event_context": { "description": "Event provenance and routing metadata associated with the emitted event.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/EventContextWebhook" } ] }, "tool_call": { "description": "Tool-call snapshot before a result is available, including its identity, name, server and\narguments. For llm.tool_call_started the status is EXECUTING; for\nllm.tool_call_approval_required it is REQUIRES_CONFIRMATION and requires_approval_at is the\ndecision deadline. result_json is unset.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ToolCallWebhook" } ] } }, "x-reference-model": { "title": "ToolCallStartedEvent", "url": "/api/models/tool-call-started-event#webhook" } }, "ToolCallCompletedEventWebhook": { "type": "object", "description": "Event emitted when a tool call reaches COMPLETED, FAILED, CANCELLED or TIMED_OUT, including\ncalls that required human approval.", "properties": { "event_context": { "description": "Event provenance and routing metadata associated with the emitted event.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/EventContextWebhook" } ] }, "tool_call": { "description": "Final tool call: status is terminal (SUCCESS|FAILED|CANCELLED|TIMED_OUT),\nresult_json populated.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/ToolCallWebhook" } ] }, "execution_time_ms": { "type": "integer", "format": "int32", "minimum": -2147483648, "maximum": 2147483647, "description": "Wall-clock execution time in milliseconds (0 when unknown, e.g. dispatch error).", "x-presence": "implicit" } }, "x-reference-model": { "title": "ToolCallCompletedEvent", "url": "/api/models/tool-call-completed-event#webhook" } } }, "models": [ { "schemaName": "Account", "title": "Account", "slug": "/api/models/account", "description": "Connected account (external user's OAuth connection to an app)", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "domain-model", "title": "Account", "slug": "/api/models/account" }, "usedBy": [ "connected-apps:pipedreamListAccountsForCurrentUser" ], "usedByRoots": [], "fields": [ { "name": "id", "description": "Unique account ID.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Display name (e.g., user's email or handle).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "externalUserId", "description": "Your application's user ID.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "healthy", "description": "Whether the account credentials are valid.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "app", "description": "Pipedream application selected by the request or returned by the provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "oauthAppId", "description": "OAuth app identifier (if applicable).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time when this record was created.", "presence": "message", "required": false, "requestRequired": false }, { "name": "updatedAt", "description": "Time when this record was last updated.", "presence": "message", "required": false, "requestRequired": false }, { "name": "credentialsLastRefreshedAt", "description": "Time when the connected account credentials were last refreshed.", "presence": "message", "required": false, "requestRequired": false }, { "name": "credentialsExpiresAt", "description": "Expiration time reported for the connected account credentials.", "presence": "message", "required": false, "requestRequired": false }, { "name": "error", "description": "Error message if unhealthy.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "lastRefreshedAt", "description": "ISO 8601 when credentials were last refreshed.", "presence": "message", "required": false, "requestRequired": false }, { "name": "nextRefreshAt", "description": "ISO 8601 when credentials will next be refreshed.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "AddDatasetItemRequest", "title": "AddDatasetItemRequest", "slug": "/api/models/add-dataset-item-request", "description": "Inputs for adding an input and expected-output pair in an evaluation dataset.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "AddDatasetItemRequest", "slug": "/api/models/add-dataset-item-request" }, "usedBy": [ "evals:addDatasetItem" ], "usedByRoots": [], "fields": [ { "name": "datasetId", "description": "Identifier of the evaluation dataset.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "inputJson", "description": "Dataset item input serialized as JSON text.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "expectedOutputJson", "description": "Expected dataset item output serialized as JSON text.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sourceTraceId", "description": "Identifier of the trace used as the source for the dataset item.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadataJson", "description": "Additional evaluation metadata serialized as JSON text.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "conversationId", "description": "Identifier of the conversation associated with the evaluation record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sourceUserMessageId", "description": "Identifier of the user message that originated the evaluated generation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "AddDatasetItemResponse", "title": "AddDatasetItemResponse", "slug": "/api/models/add-dataset-item-response", "description": "Result of adding an input and expected-output pair in an evaluation dataset.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "AddDatasetItemResponse", "slug": "/api/models/add-dataset-item-response" }, "usedBy": [ "evals:addDatasetItem" ], "usedByRoots": [], "fields": [ { "name": "itemId", "description": "Identifier of the dataset item or annotation queue item being addressed.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "AddSubscribersToTopicRequest", "title": "AddSubscribersToTopicRequest", "slug": "/api/models/add-subscribers-to-topic-request", "description": "Inputs for adding selected users to a notification topic’s recipient membership.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "AddSubscribersToTopicRequest", "slug": "/api/models/add-subscribers-to-topic-request" }, "usedBy": [ "notifications:addSubscribersToTopic" ], "usedByRoots": [], "fields": [ { "name": "topicKey", "description": "Caller-facing key identifying a notification topic.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "userIds", "description": "Identifiers of the users selected by the operation.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "AddSubscribersToTopicResponse", "title": "AddSubscribersToTopicResponse", "slug": "/api/models/add-subscribers-to-topic-response", "description": "Result payload for adding selected users to a notification topic’s recipient membership.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "AddSubscribersToTopicResponse", "slug": "/api/models/add-subscribers-to-topic-response" }, "usedBy": [ "notifications:addSubscribersToTopic" ], "usedByRoots": [], "fields": [ { "name": "result", "description": "Accepted and failed subscriber counts with per-subscriber errors from the membership change.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "AgentProfile", "title": "AgentProfile", "slug": "/api/models/agent-profile", "description": "A reusable persona with model configuration, tools and metadata describing when it should be\nselected.\n\nSee [Profile selection and versioning](/api/agent-profiles/selection-and-versioning) for profile resolution and fragment versions.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "domain-model", "title": "AgentProfile", "slug": "/api/models/agent-profile" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile" ], "usedByRoots": [], "fields": [ { "name": "profileId", "description": "Stable id, unique within the project library.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Display name used when selecting an agent profile.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Human-facing summary.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "whenToUse", "description": "Routing hint, Skill-style \"use when…\"", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "keywords", "description": "Keywords associated with discovery or selection of the agent profile.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "enabled", "description": "Whether the profile is enabled for selection. Omission during creation defaults to true; an\nexplicitly false value creates a disabled profile.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "generationConfig", "description": "--- the bundle (reused as-is: model, system_prompt, temperature, …) ---\nModel, sampling, and tool configuration used for generation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "mcpServers", "description": "--- the tool bundle for this profile ---\nDrives per-profile MCP tool discovery; replaces the conversation-wide\nConversationSettings.mcp_servers for turns where this profile is active.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "variableSpecs", "description": "Variables consumed by the profile’s system-prompt template, rendered from the conversation’s\nprompt_variables.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "version", "description": "Output-only immutable revision of the profile. Versions start at one and increase on\nsuccessful mutations; values supplied on writes are ignored.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "disableDefaultTools", "description": "Exclude the default MCP tool catalog from this profile’s effective server set. When true, only\nthe profile’s configured MCP servers are used.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "AgentProfileInput", "title": "AgentProfile", "slug": "/api/models/agent-profile-input", "description": "A reusable persona with model configuration, tools and metadata describing when it should be\nselected.\n\nSee [Profile selection and versioning](/api/agent-profiles/selection-and-versioning) for profile resolution and fragment versions.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "domain-model", "title": "AgentProfile", "slug": "/api/models/agent-profile" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:updateAgentProfile" ], "usedByRoots": [], "fields": [ { "name": "profileId", "description": "Stable id, unique within the project library.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Display name used when selecting an agent profile.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Human-facing summary.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "whenToUse", "description": "Routing hint, Skill-style \"use when…\"", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "keywords", "description": "Keywords associated with discovery or selection of the agent profile.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "enabled", "description": "Whether the profile is enabled for selection. Omission during creation defaults to true; an\nexplicitly false value creates a disabled profile.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "generationConfig", "description": "--- the bundle (reused as-is: model, system_prompt, temperature, …) ---\nModel, sampling, and tool configuration used for generation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "mcpServers", "description": "--- the tool bundle for this profile ---\nDrives per-profile MCP tool discovery; replaces the conversation-wide\nConversationSettings.mcp_servers for turns where this profile is active.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "variableSpecs", "description": "Variables consumed by the profile’s system-prompt template, rendered from the conversation’s\nprompt_variables.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "version", "description": "Output-only immutable revision of the profile. Versions start at one and increase on\nsuccessful mutations; values supplied on writes are ignored.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "disableDefaultTools", "description": "Exclude the default MCP tool catalog from this profile’s effective server set. When true, only\nthe profile’s configured MCP servers are used.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "AgentProfileLibrary", "title": "AgentProfileLibrary", "slug": "/api/models/agent-profile-library", "description": "Selection metadata for the project’s agent profiles. Retrieve an individual profile to read its\ncomplete model and tool configuration.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "domain-model", "title": "AgentProfileLibrary", "slug": "/api/models/agent-profile-library" }, "usedBy": [ "agent-profiles:getAgentProfileLibrary" ], "usedByRoots": [], "fields": [ { "name": "profiles", "description": "Profile identity and selection metadata. Full configurations are retrieved individually with\nGetAgentProfile.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "defaultProfileId", "description": "Project's nominated default profile. Native conversations do not automatically apply it\nwhen active_profile_id is empty; the client must explicitly select its intended profile.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "AgentProfileMetadata", "title": "AgentProfileMetadata", "slug": "/api/models/agent-profile-metadata", "description": "Profile identity and selection hints for a picker or router. This projection excludes the\nsystem prompt, generation settings, tools and MCP configuration; retrieve AgentProfile to\ninspect the runtime configuration. These hints do not establish that routing is active.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "domain-model", "title": "AgentProfileMetadata", "slug": "/api/models/agent-profile-metadata" }, "usedBy": [ "agent-profiles:getAgentProfileLibrary" ], "usedByRoots": [], "fields": [ { "name": "profileId", "description": "Identifier of the agent profile associated with the operation or generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Display name used when presenting an agent profile in the library.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Human-readable description of the resource.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "whenToUse", "description": "Instructions describing when this agent profile should be selected.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "keywords", "description": "Keywords associated with discovery or selection of the agent profile.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "enabled", "description": "Whether this configuration is enabled.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "AgentProfileVersionInfo", "title": "AgentProfileVersionInfo", "slug": "/api/models/agent-profile-version-info", "description": "Version identifier and creation time for an immutable agent-profile revision.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "domain-model", "title": "AgentProfileVersionInfo", "slug": "/api/models/agent-profile-version-info" }, "usedBy": [ "agent-profiles:listAgentProfileVersions" ], "usedByRoots": [], "fields": [ { "name": "version", "description": "Version of the resource represented by this message.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time when this record was created.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "Annotation", "title": "Annotation", "slug": "/api/models/annotation", "description": "Tagged provider annotation attached to generated content, such as a citation or PDF reference.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "Annotation", "slug": "/api/models/annotation" }, "usedBy": [ "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "urlCitation", "description": "Submessage fields (optional); populate the one matching kind", "presence": "message", "required": false, "requestRequired": false }, { "name": "pdf", "description": "PDF annotation or parser configuration selected by the enclosing message.", "presence": "message", "required": false, "requestRequired": false }, { "name": "kind", "description": "Selected kind; determines which submessage is populated", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Provider-specific extras.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "AnnotationInput", "title": "Annotation", "slug": "/api/models/annotation-input", "description": "Tagged provider annotation attached to generated content, such as a citation or PDF reference.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "Annotation", "slug": "/api/models/annotation" }, "usedBy": [ "conversations:appendMessage", "conversations:sendMessage", "conversations:sendMessageSync" ], "usedByRoots": [], "fields": [ { "name": "urlCitation", "description": "Submessage fields (optional); populate the one matching kind", "presence": "message", "required": false, "requestRequired": false }, { "name": "pdf", "description": "PDF annotation or parser configuration selected by the enclosing message.", "presence": "message", "required": false, "requestRequired": false }, { "name": "kind", "description": "Selected kind; determines which submessage is populated", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Provider-specific extras.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "AnnotationQueue", "title": "AnnotationQueue", "slug": "/api/models/annotation-queue", "description": "Named work queue assigning score configurations to human annotation items.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "AnnotationQueue", "slug": "/api/models/annotation-queue" }, "usedBy": [ "evals:listAnnotationQueues" ], "usedByRoots": [], "fields": [ { "name": "queueId", "description": "Identifier of the annotation queue.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Display name of the annotation work queue.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Human-readable description of the resource.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "scoreConfigIds", "description": "Score configurations available when annotating items in this queue. At least one configuration\nis required.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time when this record was created.", "presence": "message", "required": false, "requestRequired": false }, { "name": "updatedAt", "description": "Time when this record was last updated.", "presence": "message", "required": false, "requestRequired": false }, { "name": "pendingCount", "description": "Number of queue items awaiting annotation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "completedCount", "description": "Number of queue items reported completed.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "AnnotationQueueItem", "title": "AnnotationQueueItem", "slug": "/api/models/annotation-queue-item", "description": "Evaluation object assigned to an annotation queue with completion state and attribution.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "AnnotationQueueItem", "slug": "/api/models/annotation-queue-item" }, "usedBy": [ "evals:completeAnnotationQueueItem", "evals:listAnnotationQueueItems" ], "usedByRoots": [], "fields": [ { "name": "itemId", "description": "Identifier of the dataset or annotation queue item.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "queueId", "description": "Identifier of the annotation queue.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "objectId", "description": "Identifier of the evaluation object addressed by the comment or queue item.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "objectType", "description": "Kind of evaluation object addressed by the comment or annotation queue item.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "status", "description": "Completion state of the annotation queue item.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "completedAt", "description": "Time when the operation was marked complete.", "presence": "message", "required": false, "requestRequired": false }, { "name": "completedBy", "description": "Identifier of the user who completed the annotation queue item.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time when this record was created.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "AnnotationWebhook", "title": "Annotation", "slug": "/api/models/annotation-webhook", "description": "Tagged provider annotation attached to generated content, such as a citation or PDF reference.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "Annotation", "slug": "/api/models/annotation" }, "usedBy": [], "usedByRoots": [ "llm.message_published" ], "fields": [ { "name": "url_citation", "description": "Submessage fields (optional); populate the one matching kind", "presence": "message", "required": false, "requestRequired": false }, { "name": "pdf", "description": "PDF annotation or parser configuration selected by the enclosing message.", "presence": "message", "required": false, "requestRequired": false }, { "name": "kind", "description": "Selected kind; determines which submessage is populated", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Provider-specific extras.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "App", "title": "App", "slug": "/api/models/app", "description": "App metadata", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "domain-model", "title": "App", "slug": "/api/models/app" }, "usedBy": [ "connected-apps:pipedreamListApps", "connected-apps:pipedreamRetrieveApp" ], "usedByRoots": [], "fields": [ { "name": "id", "description": "Identifier of the app record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "nameSlug", "description": "Unique slug identifier (e.g., \"slack\", \"github\").", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Display name of the integration app in the Pipedream catalog.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "authType", "description": "Authentication mechanism reported for the connected account or app.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Human-readable description of the resource.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "imgSrc", "description": "Image URL supplied for the integration app.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "customFieldsJson", "description": "JSON string for custom fields.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "categories", "description": "Categories assigned to the integration app.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "featuredWeight", "description": "Provider weight used to order featured apps.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "AppCategory", "title": "AppCategory", "slug": "/api/models/app-category", "description": "App category", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "domain-model", "title": "AppCategory", "slug": "/api/models/app-category" }, "usedBy": [ "connected-apps:pipedreamListAppCategories" ], "usedByRoots": [], "fields": [ { "name": "id", "description": "Identifier of the app category record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "nameSlug", "description": "Pipedream app slug identifying the catalog entry.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Display label of the app category in the Pipedream catalog.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "AppendMessageRequest", "title": "AppendMessageRequest", "slug": "/api/models/append-message-request", "description": "Input for adding a message to conversation history without starting generation.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "AppendMessageRequest", "slug": "/api/models/append-message-request" }, "usedBy": [ "conversations:appendMessage" ], "usedByRoots": [], "fields": [ { "name": "conversationKey", "description": "Identifier of the conversation thread.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "message", "description": "Required, for the same reason as SendMessageRequest.user_message and via\nthe same hole: this field's name is \"message\", the sends call theirs\n\"user_message\", and the lenient codec discards whichever one the caller did\nnot pick. Appending nothing costs no tokens, but applyAppendMessage returns\nnil for a nil message and the endpoint answers 200 regardless — so a\nCONTEXT UPDATE feed writes nothing and the TRIGGER that later reads the\nthread is missing the context it was told had landed.", "presence": "message", "required": true, "requestRequired": true } ] }, { "schemaName": "AppendMessageResponse", "title": "AppendMessageResponse", "slug": "/api/models/append-message-response", "description": "Result of adding a message to conversation history without starting generation. This message declares no response fields.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "AppendMessageResponse", "slug": "/api/models/append-message-response" }, "usedBy": [ "conversations:appendMessage" ], "usedByRoots": [], "fields": [] }, { "schemaName": "ArchiveAllInboxMessagesRequest", "title": "ArchiveAllInboxMessagesRequest", "slug": "/api/models/archive-all-inbox-messages-request", "description": "Inputs for archiving inbox notifications selected by the supplied tag filter.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "ArchiveAllInboxMessagesRequest", "slug": "/api/models/archive-all-inbox-messages-request" }, "usedBy": [ "notifications:archiveAllInboxMessages" ], "usedByRoots": [], "fields": [ { "name": "tags", "description": "Labels associated with the resource for organization or filtering.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "ArchiveAllInboxMessagesResponse", "title": "ArchiveAllInboxMessagesResponse", "slug": "/api/models/archive-all-inbox-messages-response", "description": "Result payload for archiving inbox notifications selected by the supplied tag filter.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "ArchiveAllInboxMessagesResponse", "slug": "/api/models/archive-all-inbox-messages-response" }, "usedBy": [ "notifications:archiveAllInboxMessages" ], "usedByRoots": [], "fields": [ { "name": "archivedCount", "description": "Number of inbox entries reported archived by the operation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ArchiveAllReadInboxMessagesRequest", "title": "ArchiveAllReadInboxMessagesRequest", "slug": "/api/models/archive-all-read-inbox-messages-request", "description": "Inputs for archiving read inbox notifications selected by the supplied tag filter.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "ArchiveAllReadInboxMessagesRequest", "slug": "/api/models/archive-all-read-inbox-messages-request" }, "usedBy": [ "notifications:archiveAllReadInboxMessages" ], "usedByRoots": [], "fields": [ { "name": "tags", "description": "Labels associated with the resource for organization or filtering.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "ArchiveAllReadInboxMessagesResponse", "title": "ArchiveAllReadInboxMessagesResponse", "slug": "/api/models/archive-all-read-inbox-messages-response", "description": "Mirrors ArchiveAllInboxMessagesResponse — same shape, distinct type so the\ntwo bulk-archive RPC contracts can evolve independently.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "ArchiveAllReadInboxMessagesResponse", "slug": "/api/models/archive-all-read-inbox-messages-response" }, "usedBy": [ "notifications:archiveAllReadInboxMessages" ], "usedByRoots": [], "fields": [ { "name": "archivedCount", "description": "Number of inbox entries reported archived by the operation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ArchiveInboxMessageRequest", "title": "ArchiveInboxMessageRequest", "slug": "/api/models/archive-inbox-message-request", "description": "Caller user_id derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "ArchiveInboxMessageRequest", "slug": "/api/models/archive-inbox-message-request" }, "usedBy": [ "notifications:archiveInboxMessage" ], "usedByRoots": [], "fields": [ { "name": "notificationId", "description": "Identifier of the notification whose inbox entry is being modified.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "ArchiveInboxMessageResponse", "title": "ArchiveInboxMessageResponse", "slug": "/api/models/archive-inbox-message-response", "description": "Result payload for archiving one inbox notification while retaining its provider record.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "ArchiveInboxMessageResponse", "slug": "/api/models/archive-inbox-message-response" }, "usedBy": [ "notifications:archiveInboxMessage" ], "usedByRoots": [], "fields": [ { "name": "status", "description": "Status reported by the notification provider.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "Backoff", "title": "Backoff", "slug": "/api/models/backoff", "description": "Requested initial delay, growth factor and upper bound for tool-call retries.\nThe current generation workflow stores this configuration but does not schedule\nretries from it.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "Backoff", "slug": "/api/models/backoff" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "conversations:updatePromptVariables", "conversations:updateSettings", "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "initialMs", "description": "Requested initial retry delay in milliseconds; not applied by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "multiplier", "description": "Requested retry-delay multiplier; not applied by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxMs", "description": "Requested maximum retry delay in milliseconds; not applied by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "BackoffInput", "title": "Backoff", "slug": "/api/models/backoff-input", "description": "Requested initial delay, growth factor and upper bound for tool-call retries.\nThe current generation workflow stores this configuration but does not schedule\nretries from it.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "Backoff", "slug": "/api/models/backoff" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:appendMessage", "conversations:createThread", "conversations:sendMessage", "conversations:sendMessageSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "conversations:updateSettings", "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [ "generation-config" ], "fields": [ { "name": "initialMs", "description": "Requested initial retry delay in milliseconds; not applied by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "multiplier", "description": "Requested retry-delay multiplier; not applied by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxMs", "description": "Requested maximum retry delay in milliseconds; not applied by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "BackoffWebhook", "title": "Backoff", "slug": "/api/models/backoff-webhook", "description": "Requested initial delay, growth factor and upper bound for tool-call retries.\nThe current generation workflow stores this configuration but does not schedule\nretries from it.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "Backoff", "slug": "/api/models/backoff" }, "usedBy": [], "usedByRoots": [ "llm.generation_started", "llm.message_published" ], "fields": [ { "name": "initial_ms", "description": "Requested initial retry delay in milliseconds; not applied by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "multiplier", "description": "Requested retry-delay multiplier; not applied by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "max_ms", "description": "Requested maximum retry delay in milliseconds; not applied by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "BatchGenerateDownloadUrlsRequest", "title": "BatchGenerateDownloadUrlsRequest", "slug": "/api/models/batch-generate-download-urls-request", "description": "Inputs for issuing signed download URLs for a collection of files.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "BatchGenerateDownloadUrlsRequest", "slug": "/api/models/batch-generate-download-urls-request" }, "usedBy": [ "storage:batchGenerateDownloadUrls" ], "usedByRoots": [], "fields": [ { "name": "fileIds", "description": "File IDs to resolve (1-50 per batch).", "presence": "collection", "required": true, "requestRequired": true }, { "name": "expiresSeconds", "description": "Requested lifetime of the signed URL, in seconds.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "BatchGenerateDownloadUrlsResponse", "title": "BatchGenerateDownloadUrlsResponse", "slug": "/api/models/batch-generate-download-urls-response", "description": "Result payload for issuing signed download URLs for a collection of files.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "BatchGenerateDownloadUrlsResponse", "slug": "/api/models/batch-generate-download-urls-response" }, "usedBy": [ "storage:batchGenerateDownloadUrls" ], "usedByRoots": [], "fields": [ { "name": "results", "description": "Signed download URL or item-specific error for each requested file.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "BulkTriggerEvent", "title": "BulkTriggerEvent", "slug": "/api/models/bulk-trigger-event", "description": "One notification workflow trigger included in a bulk submission.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "domain-model", "title": "BulkTriggerEvent", "slug": "/api/models/bulk-trigger-event" }, "usedBy": [ "notifications:sendBulkNotification" ], "usedByRoots": [], "fields": [ { "name": "workflowId", "description": "Identifier of the notification workflow to execute or configure.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "userId", "description": "Identifier of the user associated with the operation.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "payload", "description": "Template variables and event data passed to the notification workflow.", "presence": "message", "required": false, "requestRequired": false }, { "name": "overrides", "description": "Provider-specific overrides applied to the notification trigger.", "presence": "message", "required": false, "requestRequired": false }, { "name": "transactionId", "description": "Identifier correlating a notification trigger with later status or cancellation requests.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "BulkTriggerResult", "title": "BulkTriggerResult", "slug": "/api/models/bulk-trigger-result", "description": "Provider acknowledgement and errors for one bulk notification trigger.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "domain-model", "title": "BulkTriggerResult", "slug": "/api/models/bulk-trigger-result" }, "usedBy": [ "notifications:sendBulkNotification" ], "usedByRoots": [], "fields": [ { "name": "acknowledged", "description": "Whether the notification provider acknowledged the trigger.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "status", "description": "Status reported by the notification provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "transactionId", "description": "Identifier correlating a notification trigger with later status or cancellation requests.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "errors", "description": "Errors reported while processing notification requests.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "BulkUpdatePreferencesRequest", "title": "BulkUpdatePreferencesRequest", "slug": "/api/models/bulk-update-preferences-request", "description": "Inputs for applying channel-preference changes across selected notification workflows.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "BulkUpdatePreferencesRequest", "slug": "/api/models/bulk-update-preferences-request" }, "usedBy": [ "notifications:bulkUpdatePreferences" ], "usedByRoots": [], "fields": [ { "name": "entries", "description": "Workflow-specific preference updates submitted together.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "BulkUpdatePreferencesResponse", "title": "BulkUpdatePreferencesResponse", "slug": "/api/models/bulk-update-preferences-response", "description": "Result payload for applying channel-preference changes across selected notification workflows.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "BulkUpdatePreferencesResponse", "slug": "/api/models/bulk-update-preferences-response" }, "usedBy": [ "notifications:bulkUpdatePreferences" ], "usedByRoots": [], "fields": [ { "name": "updatedCount", "description": "Number of preference entries reported updated.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CancelDigestEventRequest", "title": "CancelDigestEventRequest", "slug": "/api/models/cancel-digest-event-request", "description": "Inputs for cancelling a queued notification digest event.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "CancelDigestEventRequest", "slug": "/api/models/cancel-digest-event-request" }, "usedBy": [ "notifications:cancelDigestEvent" ], "usedByRoots": [], "fields": [ { "name": "transactionId", "description": "Identifier correlating a notification trigger with later status or cancellation requests.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "CancelDigestEventResponse", "title": "CancelDigestEventResponse", "slug": "/api/models/cancel-digest-event-response", "description": "Result payload for cancelling a queued notification digest event.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "CancelDigestEventResponse", "slug": "/api/models/cancel-digest-event-response" }, "usedBy": [ "notifications:cancelDigestEvent" ], "usedByRoots": [], "fields": [ { "name": "cancelled", "description": "Whether the notification cancellation was acknowledged.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "message", "description": "Diagnostic or descriptive text returned by the operation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CancelNotificationRequest", "title": "CancelNotificationRequest", "slug": "/api/models/cancel-notification-request", "description": "Inputs for cancelling a pending notification by transaction identifier.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "CancelNotificationRequest", "slug": "/api/models/cancel-notification-request" }, "usedBy": [ "notifications:cancelNotification" ], "usedByRoots": [], "fields": [ { "name": "transactionId", "description": "Identifier correlating a notification trigger with later status or cancellation requests.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "CancelNotificationResponse", "title": "CancelNotificationResponse", "slug": "/api/models/cancel-notification-response", "description": "Result payload for cancelling a pending notification by transaction identifier.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "CancelNotificationResponse", "slug": "/api/models/cancel-notification-response" }, "usedBy": [ "notifications:cancelNotification" ], "usedByRoots": [], "fields": [ { "name": "cancelled", "description": "Whether the notification cancellation was acknowledged.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "message", "description": "Diagnostic or descriptive text returned by the operation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ChannelRegistration", "title": "ChannelRegistration", "slug": "/api/models/channel-registration", "description": "Registration state and credential count for one notification channel.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "domain-model", "title": "ChannelRegistration", "slug": "/api/models/channel-registration" }, "usedBy": [ "notifications:getRegisteredChannels", "notifications:getSubscriber" ], "usedByRoots": [], "fields": [ { "name": "channel", "description": "Notification channel represented by this registration.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "registered", "description": "Whether the subscriber has a registration for this channel.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "credentialCount", "description": "Number of delivery credentials registered for the channel.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ChannelToggles", "title": "ChannelToggles", "slug": "/api/models/channel-toggles", "description": "Per-channel notification toggles. All fields are optional so that callers\ncan patch only the channels they want to change (omitted = leave unchanged).", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "domain-model", "title": "ChannelToggles", "slug": "/api/models/channel-toggles" }, "usedBy": [ "notifications:getPreferences", "notifications:getSubscriber" ], "usedByRoots": [], "fields": [ { "name": "inApp", "description": "Whether in-app notification delivery is enabled.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "push", "description": "Whether push notification delivery is enabled.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "email", "description": "Whether email notification delivery is enabled.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "sms", "description": "Whether SMS notification delivery is enabled.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "chat", "description": "Whether chat notification delivery is enabled.", "presence": "explicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ChannelTogglesInput", "title": "ChannelToggles", "slug": "/api/models/channel-toggles-input", "description": "Per-channel notification toggles. All fields are optional so that callers\ncan patch only the channels they want to change (omitted = leave unchanged).", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "domain-model", "title": "ChannelToggles", "slug": "/api/models/channel-toggles" }, "usedBy": [ "notifications:bulkUpdatePreferences", "notifications:updateGlobalPreference", "notifications:updateWorkflowPreference" ], "usedByRoots": [], "fields": [ { "name": "inApp", "description": "Whether in-app notification delivery is enabled.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "push", "description": "Whether push notification delivery is enabled.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "email", "description": "Whether email notification delivery is enabled.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "sms", "description": "Whether SMS notification delivery is enabled.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "chat", "description": "Whether chat notification delivery is enabled.", "presence": "explicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CheckTopicSubscriptionRequest", "title": "CheckTopicSubscriptionRequest", "slug": "/api/models/check-topic-subscription-request", "description": "user_id is a query target, not the caller.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "CheckTopicSubscriptionRequest", "slug": "/api/models/check-topic-subscription-request" }, "usedBy": [ "notifications:checkTopicSubscription" ], "usedByRoots": [], "fields": [ { "name": "topicKey", "description": "Caller-facing key identifying a notification topic.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "userId", "description": "Identifier of the user associated with the operation.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "CheckTopicSubscriptionResponse", "title": "CheckTopicSubscriptionResponse", "slug": "/api/models/check-topic-subscription-response", "description": "Result payload for checking whether a user belongs to a notification topic.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "CheckTopicSubscriptionResponse", "slug": "/api/models/check-topic-subscription-response" }, "usedBy": [ "notifications:checkTopicSubscription" ], "usedByRoots": [], "fields": [ { "name": "isSubscribed", "description": "Whether the user is subscribed to the selected topic.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ClientContext", "title": "ClientContext", "slug": "/api/models/client-context", "description": "Opaque caller-supplied attributes attached to a conversation message.\n\nValues 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.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "ClientContext", "slug": "/api/models/client-context" }, "usedBy": [ "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "values", "description": "Arbitrary client-supplied context for this message (e.g. page, referrer,\ndevice, in-app flow). Keys/values are opaque strings.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "ClientContextInput", "title": "ClientContext", "slug": "/api/models/client-context-input", "description": "Opaque caller-supplied attributes attached to a conversation message.\n\nValues 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.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "ClientContext", "slug": "/api/models/client-context" }, "usedBy": [ "conversations:appendMessage", "conversations:sendMessage", "conversations:sendMessageSync" ], "usedByRoots": [], "fields": [ { "name": "values", "description": "Arbitrary client-supplied context for this message (e.g. page, referrer,\ndevice, in-app flow). Keys/values are opaque strings.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "ClientContextWebhook", "title": "ClientContext", "slug": "/api/models/client-context-webhook", "description": "Opaque caller-supplied attributes attached to a conversation message.\n\nValues 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.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "ClientContext", "slug": "/api/models/client-context" }, "usedBy": [], "usedByRoots": [ "llm.message_published" ], "fields": [ { "name": "values", "description": "Arbitrary client-supplied context for this message (e.g. page, referrer,\ndevice, in-app flow). Keys/values are opaque strings.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "ClientToolResult", "title": "ClientToolResult", "slug": "/api/models/client-tool-result", "description": "Result submitted by the caller for a client-side tool call. Both tool_call_id and tool_name\nmust identify the same pending call. When submission reaches workflow validation, either missing\nvalue causes a 400 response. Copy the call's id and name into these result fields, rather than\nsubmitting the pending ToolCall unchanged.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "ClientToolResult", "slug": "/api/models/client-tool-result" }, "usedBy": [ "conversations:submitClientToolResults", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "toolCallId", "description": "Required call identifier, copied from the pending ToolCall.id.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "toolName", "description": "Required tool name, copied from the pending ToolCall.name.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "resultJson", "description": "Structured output for a matched pending call. A nonempty object records COMPLETED; an empty\nor omitted object records FAILED, including when the client could not complete the action.", "presence": "message", "required": false, "requestRequired": false }, { "name": "error", "description": "Supplied error detail. The current result handler does not consume this field; the presence\nof a nonempty result_json alone determines whether the tool is recorded as completed.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "Comment", "title": "Comment", "slug": "/api/models/comment", "description": "Authored text attached to a trace, observation, or other evaluation object.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "Comment", "slug": "/api/models/comment" }, "usedBy": [ "evals:listComments" ], "usedByRoots": [], "fields": [ { "name": "commentId", "description": "Identifier of the evaluation comment.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "objectType", "description": "Kind of evaluation object addressed by the comment or annotation queue item.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "objectId", "description": "Identifier of the evaluation object addressed by the comment or queue item.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "content", "description": "Text content of the evaluation comment.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "authorUserId", "description": "Identifier recorded for the user who authored the comment.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time when this record was created.", "presence": "message", "required": false, "requestRequired": false }, { "name": "updatedAt", "description": "Time when this record was last updated.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "CompactConversationRequest", "title": "CompactConversationRequest", "slug": "/api/models/compact-conversation-request", "description": "Input for compacting the conversation’s model context.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "CompactConversationRequest", "slug": "/api/models/compact-conversation-request" }, "usedBy": [ "conversations:compactConversation" ], "usedByRoots": [], "fields": [ { "name": "conversationKey", "description": "Identifier of the conversation thread.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "CompactConversationResponse", "title": "CompactConversationResponse", "slug": "/api/models/compact-conversation-response", "description": "Result of compacting the conversation's model context. Token counts describe the selected\nsource span and its replacement summary, not the entire context window. Counts and duration\nare unavailable while asynchronous compaction is pending.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "CompactConversationResponse", "slug": "/api/models/compact-conversation-response" }, "usedBy": [ "conversations:compactConversation" ], "usedByRoots": [], "fields": [ { "name": "compactionId", "description": "Identifier assigned to this context compaction.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "tokensBefore", "description": "Estimated tokens in the source messages being summarized, not the compaction trigger estimate.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "tokensAfter", "description": "Tokens in the generated summary, using provider-reported usage when available.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "tokensSaved", "description": "Source count minus summary count. The counts can use different methods; this is not an invoice saving.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "durationMs", "description": "Recorded compaction duration in milliseconds; it can be zero. Measure client elapsed time for latency comparisons.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "status", "description": "Status reported for this context compaction.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "Compaction", "title": "Compaction", "slug": "/api/models/compaction", "description": "Compaction metadata", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "Compaction", "slug": "/api/models/compaction" }, "usedBy": [ "conversations:getConversationState" ], "usedByRoots": [], "fields": [ { "name": "id", "description": "Identifier of the compaction record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "startSequence", "description": "Sequence number of the first conversation message represented by the compaction.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "endSequence", "description": "Sequence number of the last conversation message represented by the compaction.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "summary", "description": "Summary text produced by conversation compaction.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "originalTokenCount", "description": "Estimated token count of the context before compaction.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "summaryTokenCount", "description": "Estimated token count of the generated summary.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "modelUsed", "description": "Model identifier used for the context compaction.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time when this record was created.", "presence": "message", "required": false, "requestRequired": false }, { "name": "status", "description": "Execution state of the conversation compaction.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "triggerReason", "description": "Reason for triggering this compaction (auto threshold vs manual)", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CompactionConfig", "title": "CompactionConfig", "slug": "/api/models/compaction-config", "description": "Configuration for compaction strategy", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "CompactionConfig", "slug": "/api/models/compaction-config" }, "usedBy": [ "conversations:getConversationState", "conversations:updateContextManagementSettings" ], "usedByRoots": [], "fields": [ { "name": "mode", "description": "Context compaction mode selected by the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "threshold", "description": "Token-count or context-window-percentage threshold that triggers compaction.", "presence": "message", "required": false, "requestRequired": false }, { "name": "generationConfig", "description": "Separate config for compaction LLM calls.", "presence": "message", "required": false, "requestRequired": false }, { "name": "preserveRecent", "description": "Messages to keep uncompacted.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CompactionConfigInput", "title": "CompactionConfig", "slug": "/api/models/compaction-config-input", "description": "Configuration for compaction strategy", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "CompactionConfig", "slug": "/api/models/compaction-config" }, "usedBy": [ "conversations:createThread", "conversations:updateContextManagementSettings" ], "usedByRoots": [], "fields": [ { "name": "mode", "description": "Context compaction mode selected by the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "threshold", "description": "Token-count or context-window-percentage threshold that triggers compaction.", "presence": "message", "required": false, "requestRequired": false }, { "name": "generationConfig", "description": "Separate config for compaction LLM calls.", "presence": "message", "required": false, "requestRequired": false }, { "name": "preserveRecent", "description": "Messages to keep uncompacted.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CompleteAnnotationQueueItemRequest", "title": "CompleteAnnotationQueueItemRequest", "slug": "/api/models/complete-annotation-queue-item-request", "description": "Inputs for completing an evaluation object in an annotation queue.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "CompleteAnnotationQueueItemRequest", "slug": "/api/models/complete-annotation-queue-item-request" }, "usedBy": [ "evals:completeAnnotationQueueItem" ], "usedByRoots": [], "fields": [ { "name": "queueId", "description": "Identifier of the evaluation annotation queue.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "itemId", "description": "Identifier of the dataset item or annotation queue item being addressed.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "CompleteAnnotationQueueItemResponse", "title": "CompleteAnnotationQueueItemResponse", "slug": "/api/models/complete-annotation-queue-item-response", "description": "Result of completing an evaluation object in an annotation queue.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "CompleteAnnotationQueueItemResponse", "slug": "/api/models/complete-annotation-queue-item-response" }, "usedBy": [ "evals:completeAnnotationQueueItem" ], "usedByRoots": [], "fields": [ { "name": "item", "description": "Annotation queue item returned by the operation.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "CompleteInboxActionRequest", "title": "CompleteInboxActionRequest", "slug": "/api/models/complete-inbox-action-request", "description": "Inputs for marking an inbox notification’s action completed.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "CompleteInboxActionRequest", "slug": "/api/models/complete-inbox-action-request" }, "usedBy": [ "notifications:completeInboxAction" ], "usedByRoots": [], "fields": [ { "name": "notificationId", "description": "Identifier of the notification whose inbox entry is being modified.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "actionType", "description": "Action selector used when completing or reverting an inbox action.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "CompleteInboxActionResponse", "title": "CompleteInboxActionResponse", "slug": "/api/models/complete-inbox-action-response", "description": "Result payload for marking an inbox notification’s action completed.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "CompleteInboxActionResponse", "slug": "/api/models/complete-inbox-action-response" }, "usedBy": [ "notifications:completeInboxAction" ], "usedByRoots": [], "fields": [ { "name": "status", "description": "Status reported by the notification provider.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "CompletionTokensDetails", "title": "CompletionTokensDetails", "slug": "/api/models/completion-tokens-details", "description": "Breakdown of completion-token usage. Categories are measured by different upstream tokenizers\nand need not sum to completion_tokens; one category must not be derived by subtracting the\nothers.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "CompletionTokensDetails", "slug": "/api/models/completion-tokens-details" }, "usedBy": [ "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "reasoningTokens", "description": "Tokens used for reasoning/thinking.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "imageTokens", "description": "Completion tokens emitted as image output.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "audioTokens", "description": "Completion tokens emitted as audio output.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CompletionTokensDetailsInput", "title": "CompletionTokensDetails", "slug": "/api/models/completion-tokens-details-input", "description": "Breakdown of completion-token usage. Categories are measured by different upstream tokenizers\nand need not sum to completion_tokens; one category must not be derived by subtracting the\nothers.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "CompletionTokensDetails", "slug": "/api/models/completion-tokens-details" }, "usedBy": [ "conversations:appendMessage", "conversations:sendMessage", "conversations:sendMessageSync" ], "usedByRoots": [], "fields": [ { "name": "reasoningTokens", "description": "Tokens used for reasoning/thinking.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "imageTokens", "description": "Completion tokens emitted as image output.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "audioTokens", "description": "Completion tokens emitted as audio output.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CompletionTokensDetailsWebhook", "title": "CompletionTokensDetails", "slug": "/api/models/completion-tokens-details-webhook", "description": "Breakdown of completion-token usage. Categories are measured by different upstream tokenizers\nand need not sum to completion_tokens; one category must not be derived by subtracting the\nothers.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "CompletionTokensDetails", "slug": "/api/models/completion-tokens-details" }, "usedBy": [], "usedByRoots": [ "llm.generation_completed", "llm.message_published" ], "fields": [ { "name": "reasoning_tokens", "description": "Tokens used for reasoning/thinking.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "image_tokens", "description": "Completion tokens emitted as image output.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "audio_tokens", "description": "Completion tokens emitted as audio output.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ConfigureProviderRequest", "title": "ConfigureProviderRequest", "slug": "/api/models/configure-provider-request", "description": "tenant_id and environment derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "ConfigureProviderRequest", "slug": "/api/models/configure-provider-request" }, "usedBy": [ "notifications:configureProvider" ], "usedByRoots": [], "fields": [ { "name": "provider", "description": "Notification delivery provider being configured or reported.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "credentials", "description": "Provider-specific credentials supplied when configuring delivery.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "active", "description": "Whether the resource is marked active.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ConfigureProviderResponse", "title": "ConfigureProviderResponse", "slug": "/api/models/configure-provider-response", "description": "Result payload for configuring credentials and activation for a notification delivery provider.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "ConfigureProviderResponse", "slug": "/api/models/configure-provider-response" }, "usedBy": [ "notifications:configureProvider" ], "usedByRoots": [], "fields": [ { "name": "integrationId", "description": "Identifier of the provider integration in Novu.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "active", "description": "Whether the resource is marked active.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ContentPart", "title": "ContentPart", "slug": "/api/models/content-part", "description": "Content parts composing a message (flattened structure for JSON compatibility)", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "ContentPart", "slug": "/api/models/content-part" }, "usedBy": [ "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:mcpListResources", "conversations:mcpReadResource", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "type", "description": "Kind of content carried by this message part.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "content", "description": "Text content, image URL, file ID, or base64-encoded data.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Additional type-specific metadata (dimensions, mime_type, etc.).", "presence": "collection", "required": false, "requestRequired": false }, { "name": "cachePreferred", "description": "Hint that this part is eligible for provider prompt caching.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "structuredMessage", "description": "Populated on TEXT parts for structured output responses.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ContentPartInput", "title": "ContentPart", "slug": "/api/models/content-part-input", "description": "Content parts composing a message (flattened structure for JSON compatibility)", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "ContentPart", "slug": "/api/models/content-part" }, "usedBy": [ "conversations:appendMessage", "conversations:sendMessage", "conversations:sendMessageSync" ], "usedByRoots": [], "fields": [ { "name": "type", "description": "Kind of content carried by this message part.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "content", "description": "Text content, image URL, file ID, or base64-encoded data.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Additional type-specific metadata (dimensions, mime_type, etc.).", "presence": "collection", "required": false, "requestRequired": false }, { "name": "cachePreferred", "description": "Hint that this part is eligible for provider prompt caching.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "structuredMessage", "description": "Populated on TEXT parts for structured output responses.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ContentPartWebhook", "title": "ContentPart", "slug": "/api/models/content-part-webhook", "description": "Content parts composing a message (flattened structure for JSON compatibility)", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "ContentPart", "slug": "/api/models/content-part" }, "usedBy": [], "usedByRoots": [ "llm.message_published" ], "fields": [ { "name": "type", "description": "Kind of content carried by this message part.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "content", "description": "Text content, image URL, file ID, or base64-encoded data.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Additional type-specific metadata (dimensions, mime_type, etc.).", "presence": "collection", "required": false, "requestRequired": false }, { "name": "cache_preferred", "description": "Hint that this part is eligible for provider prompt caching.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "structured_message", "description": "Populated on TEXT parts for structured output responses.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ContextManagementSettings", "title": "ContextManagementSettings", "slug": "/api/models/context-management-settings", "description": "Configuration for context management", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "ContextManagementSettings", "slug": "/api/models/context-management-settings" }, "usedBy": [ "conversations:getConversationState", "conversations:updateContextManagementSettings" ], "usedByRoots": [], "fields": [ { "name": "strategy", "description": "Context management strategy selected for the conversation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "compactionConfig", "description": "Configuration applied when summarizing the conversation context.", "presence": "message", "required": false, "requestRequired": false }, { "name": "windowingConfig", "description": "Rules selecting the message window retained in model context.", "presence": "message", "required": false, "requestRequired": false }, { "name": "selectiveExclusionConfig", "description": "Rules selecting content to omit from the model context.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ContextManagementSettingsInput", "title": "ContextManagementSettings", "slug": "/api/models/context-management-settings-input", "description": "Configuration for context management", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "ContextManagementSettings", "slug": "/api/models/context-management-settings" }, "usedBy": [ "conversations:createThread", "conversations:updateContextManagementSettings" ], "usedByRoots": [], "fields": [ { "name": "strategy", "description": "Context management strategy selected for the conversation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "compactionConfig", "description": "Configuration applied when summarizing the conversation context.", "presence": "message", "required": false, "requestRequired": false }, { "name": "windowingConfig", "description": "Rules selecting the message window retained in model context.", "presence": "message", "required": false, "requestRequired": false }, { "name": "selectiveExclusionConfig", "description": "Rules selecting content to omit from the model context.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ConversationSettings", "title": "ConversationSettings", "slug": "/api/models/conversation-settings", "description": "Conversation-level settings controlling behavior across sends\n\n[`maxLoops`](/api/models/conversation-settings#request-field-maxloops) caps the **total number of generations** in a run — not the number of\ntool round trips. Default is **2**, which is what one round trip costs: a first\ngeneration to emit the tool call, a second to synthesize its result.\n\nOn the final generation the model is sent **no tools at all** (the request omits the\n[`tools`](/api/models/generation-config#request-field-tools) array), so it cannot emit a call there. `maxLoops: 1` therefore means a\nsingle tool-free reply — a valid way to ask for one, but not a way to get one tool\nround trip.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "ConversationSettings", "slug": "/api/models/conversation-settings" }, "usedBy": [ "conversations:getConversationState", "conversations:updatePromptVariables", "conversations:updateSettings" ], "usedByRoots": [], "fields": [ { "name": "interruptPolicy", "description": "Policy for an incoming message while another generation run is active.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxLoops", "description": "Default limit on agentic generation loops for the conversation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxParallelTools", "description": "Maximum number of tool executions allowed concurrently by this configuration.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "mcpServers", "description": "MCP servers available to this conversation; used for tool discovery/filtering", "presence": "collection", "required": false, "requestRequired": false }, { "name": "toolPolicy", "description": "Optional per-conversation tool execution policy applied to AgentConfig", "presence": "message", "required": false, "requestRequired": false }, { "name": "promptVariables", "description": "Typed values used when rendering profile prompt templates. They are shared by profiles in the\nconversation and can be refreshed with UpdatePromptVariables. Switching profiles renders the\nnew template with the same values.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ConversationSettingsInput", "title": "ConversationSettings", "slug": "/api/models/conversation-settings-input", "description": "Conversation-level settings controlling behavior across sends\n\n[`maxLoops`](/api/models/conversation-settings#request-field-maxloops) caps the **total number of generations** in a run — not the number of\ntool round trips. Default is **2**, which is what one round trip costs: a first\ngeneration to emit the tool call, a second to synthesize its result.\n\nOn the final generation the model is sent **no tools at all** (the request omits the\n[`tools`](/api/models/generation-config#request-field-tools) array), so it cannot emit a call there. `maxLoops: 1` therefore means a\nsingle tool-free reply — a valid way to ask for one, but not a way to get one tool\nround trip.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "ConversationSettings", "slug": "/api/models/conversation-settings" }, "usedBy": [ "conversations:createThread", "conversations:updateSettings" ], "usedByRoots": [], "fields": [ { "name": "interruptPolicy", "description": "Policy for an incoming message while another generation run is active.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxLoops", "description": "Default limit on agentic generation loops for the conversation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxParallelTools", "description": "Maximum number of tool executions allowed concurrently by this configuration.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "mcpServers", "description": "MCP servers available to this conversation; used for tool discovery/filtering", "presence": "collection", "required": false, "requestRequired": false }, { "name": "toolPolicy", "description": "Optional per-conversation tool execution policy applied to AgentConfig", "presence": "message", "required": false, "requestRequired": false }, { "name": "promptVariables", "description": "Typed values used when rendering profile prompt templates. They are shared by profiles in the\nconversation and can be refreshed with UpdatePromptVariables. Switching profiles renders the\nnew template with the same values.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ConversationThread", "title": "ConversationThread", "slug": "/api/models/conversation-thread", "description": "Lightweight thread registry record for multi-thread management", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "ConversationThread", "slug": "/api/models/conversation-thread" }, "usedBy": [ "conversations:createThread" ], "usedByRoots": [], "fields": [ { "name": "threadId", "description": "Identifier of the conversation thread.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "title", "description": "Display title of the conversation thread.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "tags", "description": "Labels associated with the resource for organization or filtering.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time when this record was created.", "presence": "message", "required": false, "requestRequired": false }, { "name": "updatedAt", "description": "Time when this record was last updated.", "presence": "message", "required": false, "requestRequired": false }, { "name": "externalId", "description": "Caller-supplied identifier associated with the conversation thread.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ConversationUpdateDefaultGenerationConfigRequest", "title": "ConversationUpdateDefaultGenerationConfigRequest", "slug": "/api/models/conversation-update-default-generation-config-request", "description": "Input for updating the conversation’s base generation configuration.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "ConversationUpdateDefaultGenerationConfigRequest", "slug": "/api/models/conversation-update-default-generation-config-request" }, "usedBy": [ "conversations:updateDefaultGenerationConfig" ], "usedByRoots": [], "fields": [ { "name": "conversationKey", "description": "Identifier of the conversation thread.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "defaultGenerationConfig", "description": "Base model and tool configuration for turns in this conversation.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ConversationUpdateDefaultGenerationConfigResponse", "title": "ConversationUpdateDefaultGenerationConfigResponse", "slug": "/api/models/conversation-update-default-generation-config-response", "description": "Result of updating the conversation’s base generation configuration.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "ConversationUpdateDefaultGenerationConfigResponse", "slug": "/api/models/conversation-update-default-generation-config-response" }, "usedBy": [ "conversations:updateDefaultGenerationConfig" ], "usedByRoots": [], "fields": [ { "name": "defaultGenerationConfig", "description": "Base model and tool configuration for turns in this conversation.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "CostDetails", "title": "CostDetails", "slug": "/api/models/cost-details", "description": "Breakdown of model-provider cost. When the customer supplies the provider key, usage.cost is\nzero and upstream_inference_cost reports the provider spend, split into prompt and completion\ncomponents.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "CostDetails", "slug": "/api/models/cost-details" }, "usedBy": [ "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "upstreamInferenceCost", "description": "Total upstream provider cost (USD) on BYOK routes.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "upstreamInferencePromptCost", "description": "Upstream cost attributed to prompt tokens (USD).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "upstreamInferenceCompletionCost", "description": "Upstream cost attributed to completion tokens (USD).", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CostDetailsInput", "title": "CostDetails", "slug": "/api/models/cost-details-input", "description": "Breakdown of model-provider cost. When the customer supplies the provider key, usage.cost is\nzero and upstream_inference_cost reports the provider spend, split into prompt and completion\ncomponents.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "CostDetails", "slug": "/api/models/cost-details" }, "usedBy": [ "conversations:appendMessage", "conversations:sendMessage", "conversations:sendMessageSync" ], "usedByRoots": [], "fields": [ { "name": "upstreamInferenceCost", "description": "Total upstream provider cost (USD) on BYOK routes.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "upstreamInferencePromptCost", "description": "Upstream cost attributed to prompt tokens (USD).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "upstreamInferenceCompletionCost", "description": "Upstream cost attributed to completion tokens (USD).", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CostDetailsWebhook", "title": "CostDetails", "slug": "/api/models/cost-details-webhook", "description": "Breakdown of model-provider cost. When the customer supplies the provider key, usage.cost is\nzero and upstream_inference_cost reports the provider spend, split into prompt and completion\ncomponents.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "CostDetails", "slug": "/api/models/cost-details" }, "usedBy": [], "usedByRoots": [ "llm.generation_completed", "llm.message_published" ], "fields": [ { "name": "upstream_inference_cost", "description": "Total upstream provider cost (USD) on BYOK routes.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "upstream_inference_prompt_cost", "description": "Upstream cost attributed to prompt tokens (USD).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "upstream_inference_completion_cost", "description": "Upstream cost attributed to completion tokens (USD).", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateAgentProfileRequest", "title": "CreateAgentProfileRequest", "slug": "/api/models/create-agent-profile-request", "description": "=== Create ===\nInputs for creating a project-scoped agent profile with prompt and generation settings.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "CreateAgentProfileRequest", "slug": "/api/models/create-agent-profile-request" }, "usedBy": [ "agent-profiles:createAgentProfile" ], "usedByRoots": [], "fields": [ { "name": "projectId", "description": "Identifier of the project associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "profile", "description": "Agent profile definition to add to the project library.", "presence": "message", "required": true, "requestRequired": true } ] }, { "schemaName": "CreateAgentProfileResponse", "title": "CreateAgentProfileResponse", "slug": "/api/models/create-agent-profile-response", "description": "Result payload for creating a project-scoped agent profile with prompt and generation settings.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "CreateAgentProfileResponse", "slug": "/api/models/create-agent-profile-response" }, "usedBy": [ "agent-profiles:createAgentProfile" ], "usedByRoots": [], "fields": [ { "name": "profile", "description": "Echoes the stored profile.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateAnnotationQueueRequest", "title": "CreateAnnotationQueueRequest", "slug": "/api/models/create-annotation-queue-request", "description": "Inputs for creating a queue of evaluation objects awaiting annotation.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "CreateAnnotationQueueRequest", "slug": "/api/models/create-annotation-queue-request" }, "usedBy": [ "evals:createAnnotationQueue" ], "usedByRoots": [], "fields": [ { "name": "name", "description": "Name assigned to, or used to filter, the evaluation record.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "scoreConfigIds", "description": "At least one: a queue's fixed config set is the whole difference between it\nand ad-hoc annotation.", "presence": "collection", "required": true, "requestRequired": true }, { "name": "description", "description": "Human-readable explanation of the evaluation record.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateAnnotationQueueResponse", "title": "CreateAnnotationQueueResponse", "slug": "/api/models/create-annotation-queue-response", "description": "Result of creating a queue of evaluation objects awaiting annotation.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "CreateAnnotationQueueResponse", "slug": "/api/models/create-annotation-queue-response" }, "usedBy": [ "evals:createAnnotationQueue" ], "usedByRoots": [], "fields": [ { "name": "queueId", "description": "Identifier of the evaluation annotation queue.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateCommentRequest", "title": "CreateCommentRequest", "slug": "/api/models/create-comment-request", "description": "Inputs for creating a comment attached to an evaluation object.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "CreateCommentRequest", "slug": "/api/models/create-comment-request" }, "usedBy": [ "evals:createComment" ], "usedByRoots": [], "fields": [ { "name": "objectType", "description": "Kind of evaluation object to which the comment belongs.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "objectId", "description": "Identifier of the evaluation object to which the comment belongs.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "content", "description": "Body of the evaluation comment.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "CreateCommentResponse", "title": "CreateCommentResponse", "slug": "/api/models/create-comment-response", "description": "Result of creating a comment attached to an evaluation object.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "CreateCommentResponse", "slug": "/api/models/create-comment-response" }, "usedBy": [ "evals:createComment" ], "usedByRoots": [], "fields": [ { "name": "commentId", "description": "Identifier of the evaluation comment.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateCustomMCPServerRequest", "title": "CreateCustomMCPServerRequest", "slug": "/api/models/create-custom-mcp-server-request", "description": "Inputs for registering a tenant-owned MCP server and its connection configuration.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "CreateCustomMCPServerRequest", "slug": "/api/models/create-custom-mcp-server-request" }, "usedBy": [ "mcp-servers:createCustomMcpServer" ], "usedByRoots": [], "fields": [ { "name": "projectId", "description": "Empty → \"default\"", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "server", "description": "MCP server record supplied to or returned by the operation.", "presence": "message", "required": true, "requestRequired": true } ] }, { "schemaName": "CreateCustomMCPServerResponse", "title": "CreateCustomMCPServerResponse", "slug": "/api/models/create-custom-mcp-server-response", "description": "Result payload for registering a tenant-owned MCP server and its connection configuration.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "CreateCustomMCPServerResponse", "slug": "/api/models/create-custom-mcp-server-response" }, "usedBy": [ "mcp-servers:createCustomMcpServer" ], "usedByRoots": [], "fields": [ { "name": "server", "description": "MCP server record supplied to or returned by the operation.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateDailySessionRequest", "title": "CreateDailySessionRequest", "slug": "/api/models/create-daily-session-request", "description": "Input for starting a Pipecat voice session for the conversation.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "CreateDailySessionRequest", "slug": "/api/models/create-daily-session-request" }, "usedBy": [ "conversations:createDailySession" ], "usedByRoots": [], "fields": [ { "name": "conversationKey", "description": "Identifier of the conversation thread.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "agentName", "description": "Name of the Pipecat agent to start for the voice session.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "socayoConfig", "description": "Socayo-specific agent configuration", "presence": "message", "required": false, "requestRequired": false }, { "name": "createDailyRoom", "description": "Whether session creation should also create a Daily room.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "dailyRoomProperties", "description": "Properties passed to Daily when creating the session room.", "presence": "message", "required": false, "requestRequired": false }, { "name": "dailyMeetingTokenProperties", "description": "Properties passed to Daily when issuing the meeting token.", "presence": "message", "required": false, "requestRequired": false }, { "name": "userData", "description": "User data passed to the Pipecat agent at session startup.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateDailySessionResponse", "title": "CreateDailySessionResponse", "slug": "/api/models/create-daily-session-response", "description": "Result of starting a Pipecat voice session for the conversation.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "CreateDailySessionResponse", "slug": "/api/models/create-daily-session-response" }, "usedBy": [ "conversations:createDailySession" ], "usedByRoots": [], "fields": [ { "name": "session", "description": "Daily voice session connection information.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateDatasetRequest", "title": "CreateDatasetRequest", "slug": "/api/models/create-dataset-request", "description": "Inputs for creating an evaluation dataset.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "CreateDatasetRequest", "slug": "/api/models/create-dataset-request" }, "usedBy": [ "evals:createDataset" ], "usedByRoots": [], "fields": [ { "name": "name", "description": "Name assigned to, or used to filter, the evaluation record.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "description", "description": "Human-readable explanation of the evaluation record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadataJson", "description": "Additional evaluation metadata serialized as JSON text.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateDatasetResponse", "title": "CreateDatasetResponse", "slug": "/api/models/create-dataset-response", "description": "Result of creating an evaluation dataset.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "CreateDatasetResponse", "slug": "/api/models/create-dataset-response" }, "usedBy": [ "evals:createDataset" ], "usedByRoots": [], "fields": [ { "name": "datasetId", "description": "Identifier of the evaluation dataset.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateFolderRequest", "title": "CreateFolderRequest", "slug": "/api/models/create-folder-request", "description": "Inputs for creating a folder entry in the user’s storage namespace.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "CreateFolderRequest", "slug": "/api/models/create-folder-request" }, "usedBy": [ "storage:createFolder" ], "usedByRoots": [], "fields": [ { "name": "folderPath", "description": "Path of the folder within the user’s storage namespace.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Additional attributes associated with the resource.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateFolderResponse", "title": "CreateFolderResponse", "slug": "/api/models/create-folder-response", "description": "Result payload for creating a folder entry in the user’s storage namespace.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "CreateFolderResponse", "slug": "/api/models/create-folder-response" }, "usedBy": [ "storage:createFolder" ], "usedByRoots": [], "fields": [ { "name": "folder", "description": "Metadata for the folder affected by the operation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "created", "description": "Whether this operation created a new folder.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateJobRequest", "title": "CreateJobRequest", "slug": "/api/models/create-job-request", "description": "Inputs for creating a scheduled job and its trigger settings.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "scheduling", "role": "operation-envelope", "title": "CreateJobRequest", "slug": "/api/models/create-job-request" }, "usedBy": [ "scheduled-jobs:createJob" ], "usedByRoots": [], "fields": [ { "name": "name", "description": "Human-readable name assigned to the scheduled job.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "description", "description": "Human-readable explanation of the scheduled job.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "scheduleType", "description": "Selects which schedule expression to supply. For SCHEDULE_TYPE_CRON, set\ncron_expression and optionally timezone; for SCHEDULE_TYPE_ONCE, set scheduled_at;\nfor SCHEDULE_TYPE_RECURRING_INTERVAL, set interval_seconds. Supply exactly one\nexpression matching the chosen type.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "cronExpression", "description": "Cron expression evaluated in timezone. Accepts 5 or 6 fields and supported shorthand\nexpressions. Examples: `0 9 * * 1-5` for weekdays at 09:00, `*/15 * * * *` for every\n15 minutes, and `0 0 1 * *` for the first day of each month at midnight.\n`@daily` means `0 0 * * *`; `@hourly` means `0 * * * *`.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "timezone", "description": "IANA timezone for cron evaluation, such as \"America/New_York\". Defaults to \"UTC\".", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "scheduledAt", "description": "Instant at which a one-time scheduled job should run.", "presence": "message", "required": false, "requestRequired": false }, { "name": "intervalSeconds", "description": "Interval between scheduled triggers, in seconds.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "target", "description": "Destination and invocation settings for the scheduled job.", "presence": "message", "required": true, "requestRequired": true }, { "name": "retryPolicy", "description": "Attempt limits and backoff settings for the scheduled target.", "presence": "message", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Application-defined JSON metadata attached to the scheduled job.", "presence": "message", "required": false, "requestRequired": false }, { "name": "autoPauseThreshold", "description": "Consecutive failure threshold used to pause the scheduled job.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "ownerSubject", "description": "Owner subject. When omitted, defaults to the caller derived from headers.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "externalId", "description": "Optional client-supplied identifier, unique within (tenant, project)\namong live schedules. Immutable once set. Must not start with \"sched_\".", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CreatePromptFragmentRequest", "title": "CreatePromptFragmentRequest", "slug": "/api/models/create-prompt-fragment-request", "description": "=== Create fragment ===\nInputs for creating a reusable block of prompt-template text in the project library.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "CreatePromptFragmentRequest", "slug": "/api/models/create-prompt-fragment-request" }, "usedBy": [ "agent-profiles:createPromptFragment" ], "usedByRoots": [], "fields": [ { "name": "projectId", "description": "Identifier of the project associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "fragment", "description": "Reusable prompt fragment definition to add to the project library.", "presence": "message", "required": true, "requestRequired": true } ] }, { "schemaName": "CreatePromptFragmentResponse", "title": "CreatePromptFragmentResponse", "slug": "/api/models/create-prompt-fragment-response", "description": "Result payload for creating a reusable block of prompt-template text in the project library.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "CreatePromptFragmentResponse", "slug": "/api/models/create-prompt-fragment-response" }, "usedBy": [ "agent-profiles:createPromptFragment" ], "usedByRoots": [], "fields": [ { "name": "fragment", "description": "Echoes the stored fragment.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateScoreConfigRequest", "title": "CreateScoreConfigRequest", "slug": "/api/models/create-score-config-request", "description": "Inputs for creating the definition and allowed values of an evaluation score.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "CreateScoreConfigRequest", "slug": "/api/models/create-score-config-request" }, "usedBy": [ "evals:createScoreConfig" ], "usedByRoots": [], "fields": [ { "name": "name", "description": "Name assigned to, or used to filter, the evaluation record.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "dataType", "description": "Value type used to interpret the evaluation score.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "categoricalValues", "description": "Allowed category values for the score configuration.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "minValue", "description": "Lower numeric bound for the score range.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxValue", "description": "Upper numeric bound for the score range.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateScoreConfigResponse", "title": "CreateScoreConfigResponse", "slug": "/api/models/create-score-config-response", "description": "Result of creating the definition and allowed values of an evaluation score.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "CreateScoreConfigResponse", "slug": "/api/models/create-score-config-response" }, "usedBy": [ "evals:createScoreConfig" ], "usedByRoots": [], "fields": [ { "name": "configId", "description": "Identifier of the evaluation score configuration.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateSubscriberRequest", "title": "CreateSubscriberRequest", "slug": "/api/models/create-subscriber-request", "description": "tenant_id and environment derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "CreateSubscriberRequest", "slug": "/api/models/create-subscriber-request" }, "usedBy": [ "notifications:createSubscriber" ], "usedByRoots": [], "fields": [ { "name": "subscriberId", "description": "Identifier of the notification subscriber.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "email", "description": "Email address used for subscriber contact and delivery.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "phone", "description": "Phone number used for subscriber contact and delivery.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "firstName", "description": "Subscriber’s given name.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "lastName", "description": "Subscriber’s family name.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "avatarUrl", "description": "URL of the subscriber’s avatar image.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "locale", "description": "Subscriber locale used when rendering notifications.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "data", "description": "Custom key-value attributes to attach to the new subscriber.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateSubscriberResponse", "title": "CreateSubscriberResponse", "slug": "/api/models/create-subscriber-response", "description": "Result payload for creating a notification subscriber with contact and locale attributes.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "CreateSubscriberResponse", "slug": "/api/models/create-subscriber-response" }, "usedBy": [ "notifications:createSubscriber" ], "usedByRoots": [], "fields": [ { "name": "novuSubscriberId", "description": "Subscriber identifier returned by Novu.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "subscriberId", "description": "Identifier of the notification subscriber.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateThreadRequest", "title": "CreateThreadRequest", "slug": "/api/models/create-thread-request", "description": "Input for creating a conversation thread with its initial configuration.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "CreateThreadRequest", "slug": "/api/models/create-thread-request" }, "usedBy": [ "conversations:createThread" ], "usedByRoots": [], "fields": [ { "name": "title", "description": "Display title of the conversation thread.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "tags", "description": "Labels associated with the conversation thread.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "activeProfileId", "description": "Agent profile selected as the conversation’s active profile at creation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "activeProfileVersion", "description": "Immutable version of the active profile to use. Zero selects its latest version.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "externalId", "description": "Caller-supplied identifier associated with the conversation thread.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "defaultGenerationConfig", "description": "Base model and tool configuration for turns in this conversation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "conversationSettings", "description": "Initial conversation settings, including prompt and integration configuration.", "presence": "message", "required": false, "requestRequired": false }, { "name": "contextManagementSettings", "description": "Optional context-management settings for the new conversation.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateThreadResponse", "title": "CreateThreadResponse", "slug": "/api/models/create-thread-response", "description": "Result of creating a conversation thread with its initial configuration.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "CreateThreadResponse", "slug": "/api/models/create-thread-response" }, "usedBy": [ "conversations:createThread" ], "usedByRoots": [], "fields": [ { "name": "thread", "description": "Conversation thread returned by creation.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateTopicRequest", "title": "CreateTopicRequest", "slug": "/api/models/create-topic-request", "description": "Inputs for creating a named notification topic with a caller-selected key.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "CreateTopicRequest", "slug": "/api/models/create-topic-request" }, "usedBy": [ "notifications:createTopic" ], "usedByRoots": [], "fields": [ { "name": "topicKey", "description": "Caller-facing key identifying a notification topic.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "name", "description": "Display name assigned to the notification topic.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateTopicResponse", "title": "CreateTopicResponse", "slug": "/api/models/create-topic-response", "description": "Result payload for creating a named notification topic with a caller-selected key.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "CreateTopicResponse", "slug": "/api/models/create-topic-response" }, "usedBy": [ "notifications:createTopic" ], "usedByRoots": [], "fields": [ { "name": "topicKey", "description": "Caller-facing key identifying a notification topic.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "topicId", "description": "Provider-assigned identifier of the notification topic.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateWebhookEndpointRequest", "title": "CreateWebhookEndpointRequest", "slug": "/api/models/create-webhook-endpoint-request", "description": "Inputs for registering a tenant webhook destination and its initial event subscription.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "webhooks", "role": "operation-envelope", "title": "CreateWebhookEndpointRequest", "slug": "/api/models/create-webhook-endpoint-request" }, "usedBy": [ "webhooks:createWebhookEndpoint" ], "usedByRoots": [], "fields": [ { "name": "name", "description": "Display name of the tenant’s webhook delivery destination.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "url", "description": "URL associated with the resource or outbound request.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "description", "description": "Human-readable description of the resource.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "eventTypes", "description": "Convenience: auto-create subscription.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateWebhookEndpointResponse", "title": "CreateWebhookEndpointResponse", "slug": "/api/models/create-webhook-endpoint-response", "description": "Result payload for registering a tenant webhook destination and its initial event subscription.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "webhooks", "role": "operation-envelope", "title": "CreateWebhookEndpointResponse", "slug": "/api/models/create-webhook-endpoint-response" }, "usedBy": [ "webhooks:createWebhookEndpoint" ], "usedByRoots": [], "fields": [ { "name": "endpoint", "description": "Webhook endpoint returned by the provider operation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "subscription", "description": "If event_types provided.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateWebhookSubscriptionRequest", "title": "CreateWebhookSubscriptionRequest", "slug": "/api/models/create-webhook-subscription-request", "description": "Inputs for subscribing a tenant webhook endpoint to selected event types.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "webhooks", "role": "operation-envelope", "title": "CreateWebhookSubscriptionRequest", "slug": "/api/models/create-webhook-subscription-request" }, "usedBy": [ "webhooks:createWebhookSubscription" ], "usedByRoots": [], "fields": [ { "name": "endpointId", "description": "Identifier of the webhook endpoint receiving deliveries.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "eventTypes", "description": "Event type names selected for the webhook subscription.", "presence": "collection", "required": true, "requestRequired": true }, { "name": "externalId", "description": "Optional client-supplied identifier, unique among the tenant’s live subscriptions. Use it to\naddress deletion by a name your application manages; it becomes reusable after deletion.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateWebhookSubscriptionResponse", "title": "CreateWebhookSubscriptionResponse", "slug": "/api/models/create-webhook-subscription-response", "description": "Result payload for subscribing a tenant webhook endpoint to selected event types.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "webhooks", "role": "operation-envelope", "title": "CreateWebhookSubscriptionResponse", "slug": "/api/models/create-webhook-subscription-response" }, "usedBy": [ "webhooks:createWebhookSubscription" ], "usedByRoots": [], "fields": [ { "name": "subscription", "description": "Webhook subscription returned by the provider operation.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateWorkflowRequest", "title": "CreateWorkflowRequest", "slug": "/api/models/create-workflow-request", "description": "tenant_id and environment derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "CreateWorkflowRequest", "slug": "/api/models/create-workflow-request" }, "usedBy": [ "notifications:createWorkflow" ], "usedByRoots": [], "fields": [ { "name": "workflow", "description": "Notification workflow definition supplied to or returned by the provider.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "CreateWorkflowResponse", "title": "CreateWorkflowResponse", "slug": "/api/models/create-workflow-response", "description": "Result payload for registering a notification workflow definition with the provider.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "CreateWorkflowResponse", "slug": "/api/models/create-workflow-response" }, "usedBy": [ "notifications:createWorkflow" ], "usedByRoots": [], "fields": [ { "name": "workflow", "description": "Notification workflow definition supplied to or returned by the provider.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "CursorPageInfo", "title": "CursorPageInfo", "slug": "/api/models/cursor-page-info", "description": "Opaque-cursor pagination details. A cursor is used to request the next page; arbitrary\npage-number seeking is not supported.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "CursorPageInfo", "slug": "/api/models/cursor-page-info" }, "usedBy": [ "evals:listDatasetRuns", "evals:listObservations", "evals:listScores", "evals:listSessions", "evals:listTraces" ], "usedByRoots": [], "fields": [ { "name": "nextCursor", "description": "Pass back as the request's `cursor` for the next page. Empty on the last\npage.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "limit", "description": "Maximum number of entries requested from the listing.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "totalItems", "description": "Total number of matching items when it can be counted exactly. Absent when the selected\nfilters do not support an exact total.", "presence": "explicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CustomMCPServer", "title": "CustomMCPServer", "slug": "/api/models/custom-mcp-server", "description": "A project-scoped, HTTP-only MCP server definition, keyed\n(tenant_id, project_id, server_id). Its wire ID is \"custom:{server_id}\".\n\nauth_type selects the required credential fields. Authenticated modes require auth_secret_ref;\nNONE requires it to be empty. HEADER requires auth_header_name and QUERY requires auth_query_param;\nthose names must be empty for every other mode. Inconsistent combinations are rejected before\nstorage. Inline credentials are not accepted.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "domain-model", "title": "CustomMCPServer", "slug": "/api/models/custom-mcp-server" }, "usedBy": [ "mcp-servers:createCustomMcpServer", "mcp-servers:getCustomMcpServer", "mcp-servers:listCustomMcpServers", "mcp-servers:updateCustomMcpServer" ], "usedByRoots": [], "fields": [ { "name": "serverId", "description": "Unique within the project.", "presence": "implicit", "required": false, "requestRequired": true }, { "name": "displayName", "description": "Display name used for the registered MCP server.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Human-readable description of the resource.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "endpoint", "description": "HTTPS endpoint for Streamable HTTP; local and standard-input/output transports are unsupported.\nThe egress guard also rejects prohibited destinations such as metadata, loopback, private-network\nand in-cluster addresses. HTTPS alone does not satisfy these destination checks.", "presence": "implicit", "required": false, "requestRequired": true }, { "name": "authType", "description": "Authentication mechanism configured for the MCP server.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "authSecretRef", "description": "Required credential reference for BEARER, HEADER and QUERY authentication. Resolves within\nthis server's tenant and project; only the secret name is returned, never its value.", "presence": "message", "required": false, "requestRequired": false }, { "name": "authHeaderName", "description": "Name of the custom authentication header. The egress guard also rejects protected header\nnames; satisfying the field's character pattern alone does not permit every header.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enabled", "description": "Whether this configuration is enabled.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "requestTimeout", "description": "Time allowed for a remote request. Omission or a nonpositive duration uses 30 seconds;\npositive durations below one second are raised to one second. Long waits can delay the\nconversation while the remote server is unavailable.", "presence": "message", "required": false, "requestRequired": false }, { "name": "version", "description": "Output-only revision assigned by the store and incremented on updates. Ignored on writes.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdBy", "description": "Output-only identity of the caller that registered the server. Ignored on writes.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Output-only creation time assigned by the store. Ignored on writes.", "presence": "message", "required": false, "requestRequired": false }, { "name": "updatedAt", "description": "Output-only last-update time assigned by the store. Ignored on writes.", "presence": "message", "required": false, "requestRequired": false }, { "name": "authQueryParam", "description": "Required for QUERY auth; the vendor's parameter name (e.g. \"tavilyApiKey\").\n\nEmpty is allowed — populated only for QUERY auth.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "CustomMCPServerInput", "title": "CustomMCPServer", "slug": "/api/models/custom-mcp-server-input", "description": "A project-scoped, HTTP-only MCP server definition, keyed\n(tenant_id, project_id, server_id). Its wire ID is \"custom:{server_id}\".\n\nauth_type selects the required credential fields. Authenticated modes require auth_secret_ref;\nNONE requires it to be empty. HEADER requires auth_header_name and QUERY requires auth_query_param;\nthose names must be empty for every other mode. Inconsistent combinations are rejected before\nstorage. Inline credentials are not accepted.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "domain-model", "title": "CustomMCPServer", "slug": "/api/models/custom-mcp-server" }, "usedBy": [ "mcp-servers:createCustomMcpServer", "mcp-servers:updateCustomMcpServer" ], "usedByRoots": [], "fields": [ { "name": "serverId", "description": "Unique within the project.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "displayName", "description": "Display name used for the registered MCP server.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Human-readable description of the resource.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "endpoint", "description": "HTTPS endpoint for Streamable HTTP; local and standard-input/output transports are unsupported.\nThe egress guard also rejects prohibited destinations such as metadata, loopback, private-network\nand in-cluster addresses. HTTPS alone does not satisfy these destination checks.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "authType", "description": "Authentication mechanism configured for the MCP server.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "authSecretRef", "description": "Required credential reference for BEARER, HEADER and QUERY authentication. Resolves within\nthis server's tenant and project; only the secret name is returned, never its value.", "presence": "message", "required": false, "requestRequired": false }, { "name": "authHeaderName", "description": "Name of the custom authentication header. The egress guard also rejects protected header\nnames; satisfying the field's character pattern alone does not permit every header.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enabled", "description": "Whether this configuration is enabled.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "requestTimeout", "description": "Time allowed for a remote request. Omission or a nonpositive duration uses 30 seconds;\npositive durations below one second are raised to one second. Long waits can delay the\nconversation while the remote server is unavailable.", "presence": "message", "required": false, "requestRequired": false }, { "name": "version", "description": "Output-only revision assigned by the store and incremented on updates. Ignored on writes.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdBy", "description": "Output-only identity of the caller that registered the server. Ignored on writes.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Output-only creation time assigned by the store. Ignored on writes.", "presence": "message", "required": false, "requestRequired": false }, { "name": "updatedAt", "description": "Output-only last-update time assigned by the store. Ignored on writes.", "presence": "message", "required": false, "requestRequired": false }, { "name": "authQueryParam", "description": "Required for QUERY auth; the vendor's parameter name (e.g. \"tavilyApiKey\").\n\nEmpty is allowed — populated only for QUERY auth.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "DailyMeetingTokenProperties", "title": "DailyMeetingTokenProperties", "slug": "/api/models/daily-meeting-token-properties", "description": "Daily meeting token configuration (subset of common fields)", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "voice-media", "role": "domain-model", "title": "DailyMeetingTokenProperties", "slug": "/api/models/daily-meeting-token-properties" }, "usedBy": [ "conversations:createDailySession" ], "usedByRoots": [], "fields": [ { "name": "isOwner", "description": "Whether the issued Daily meeting token grants room-owner privileges.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableAutoRecording", "description": "Whether the Daily meeting token requests automatic recording.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "DailyMeetingTokenPropertiesInput", "title": "DailyMeetingTokenProperties", "slug": "/api/models/daily-meeting-token-properties-input", "description": "Daily meeting token configuration (subset of common fields)", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "voice-media", "role": "domain-model", "title": "DailyMeetingTokenProperties", "slug": "/api/models/daily-meeting-token-properties" }, "usedBy": [ "conversations:createDailySession" ], "usedByRoots": [], "fields": [ { "name": "isOwner", "description": "Whether the issued Daily meeting token grants room-owner privileges.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableAutoRecording", "description": "Whether the Daily meeting token requests automatic recording.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "DailyRoomProperties", "title": "DailyRoomProperties", "slug": "/api/models/daily-room-properties", "description": "Daily room configuration (subset of frequently used fields)", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "voice-media", "role": "domain-model", "title": "DailyRoomProperties", "slug": "/api/models/daily-room-properties" }, "usedBy": [ "conversations:createDailySession" ], "usedByRoots": [], "fields": [ { "name": "nbf", "description": "Timestamps (unix seconds)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "exp", "description": "Expiration time of the Daily room, as Unix seconds.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxParticipants", "description": "Limits\nMaximum number of participants allowed in the Daily room.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enablePeopleUi", "description": "UI toggles\nWhether the Daily room exposes the participant-list controls.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enablePipUi", "description": "Whether the Daily room enables picture-in-picture controls.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableEmojiReactions", "description": "Whether the Daily room enables emoji reactions.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableHandRaising", "description": "Whether the Daily room enables hand-raising controls.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enablePrejoinUi", "description": "Whether the Daily room enables its prejoin screen.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableLiveCaptionsUi", "description": "Whether the Daily room exposes live-caption controls.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableNetworkUi", "description": "Whether the Daily room exposes network-information controls.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableNoiseCancellationUi", "description": "Whether the Daily room exposes noise-cancellation controls.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableBreakoutRooms", "description": "Whether the Daily room enables breakout rooms.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableKnocking", "description": "Access and permissions", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "ownerOnlyBroadcast", "description": "Whether broadcasting is restricted to Daily room owners.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enforceUniqueUserIds", "description": "Whether the Daily room requires participant user identifiers to be unique.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableScreenshare", "description": "Features\nWhether screen sharing is enabled in the Daily room.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableVideoProcessingUi", "description": "Whether the Daily room exposes video-processing controls.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableChat", "description": "Whether chat is enabled in the Daily room.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableSharedChatHistory", "description": "Whether the Daily room enables shared chat history.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableAdvancedChat", "description": "Whether the Daily room enables advanced chat features.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableHiddenParticipants", "description": "Whether the Daily room allows hidden participants.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "startVideoOff", "description": "Media defaults\nWhether participants join the Daily room with video initially off.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "startAudioOff", "description": "Whether participants join the Daily room with audio initially off.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableRecording", "description": "Recording mode configured for the Daily room.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "ejectAtRoomExp", "description": "Whether participants are removed when the Daily room expires.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "ejectAfterElapsed", "description": "Elapsed session duration after which to eject participants, in seconds.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableMeshSfu", "description": "Topology and bandwidth", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sfuSwitchover", "description": "Daily topology setting controlling the switch to SFU transport.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableAdaptiveSimulcast", "description": "Whether adaptive simulcast is enabled for the Daily room.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableMultipartyAdaptiveSimulcast", "description": "Whether multiparty adaptive simulcast is enabled for the Daily room.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "experimentalOptimizeLargeCalls", "description": "Whether Daily’s experimental large-call optimization is requested.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "lang", "description": "Localization and hooks", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "meetingJoinHook", "description": "Webhook URL invoked by the Daily meeting-join hook.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "geo", "description": "Regions\nRegion selected for the Daily room’s media infrastructure.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "rtmpGeo", "description": "Region selected for Daily RTMP streaming.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "disableRtmpGeoFallback", "description": "Whether automatic RTMP region fallback is disabled.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "recordingsBucket", "description": "Storage destination configured for Daily recordings.", "presence": "message", "required": false, "requestRequired": false }, { "name": "transcriptionBucket", "description": "Storage destination configured for Daily transcriptions.", "presence": "message", "required": false, "requestRequired": false }, { "name": "recordingsTemplate", "description": "Template used for recording object names in storage.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "transcriptionTemplate", "description": "Template used for transcription object names in storage.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "DailyRoomPropertiesInput", "title": "DailyRoomProperties", "slug": "/api/models/daily-room-properties-input", "description": "Daily room configuration (subset of frequently used fields)", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "voice-media", "role": "domain-model", "title": "DailyRoomProperties", "slug": "/api/models/daily-room-properties" }, "usedBy": [ "conversations:createDailySession" ], "usedByRoots": [], "fields": [ { "name": "nbf", "description": "Timestamps (unix seconds)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "exp", "description": "Expiration time of the Daily room, as Unix seconds.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxParticipants", "description": "Limits\nMaximum number of participants allowed in the Daily room.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enablePeopleUi", "description": "UI toggles\nWhether the Daily room exposes the participant-list controls.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enablePipUi", "description": "Whether the Daily room enables picture-in-picture controls.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableEmojiReactions", "description": "Whether the Daily room enables emoji reactions.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableHandRaising", "description": "Whether the Daily room enables hand-raising controls.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enablePrejoinUi", "description": "Whether the Daily room enables its prejoin screen.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableLiveCaptionsUi", "description": "Whether the Daily room exposes live-caption controls.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableNetworkUi", "description": "Whether the Daily room exposes network-information controls.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableNoiseCancellationUi", "description": "Whether the Daily room exposes noise-cancellation controls.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableBreakoutRooms", "description": "Whether the Daily room enables breakout rooms.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableKnocking", "description": "Access and permissions", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "ownerOnlyBroadcast", "description": "Whether broadcasting is restricted to Daily room owners.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enforceUniqueUserIds", "description": "Whether the Daily room requires participant user identifiers to be unique.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableScreenshare", "description": "Features\nWhether screen sharing is enabled in the Daily room.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableVideoProcessingUi", "description": "Whether the Daily room exposes video-processing controls.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableChat", "description": "Whether chat is enabled in the Daily room.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableSharedChatHistory", "description": "Whether the Daily room enables shared chat history.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableAdvancedChat", "description": "Whether the Daily room enables advanced chat features.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableHiddenParticipants", "description": "Whether the Daily room allows hidden participants.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "startVideoOff", "description": "Media defaults\nWhether participants join the Daily room with video initially off.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "startAudioOff", "description": "Whether participants join the Daily room with audio initially off.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableRecording", "description": "Recording mode configured for the Daily room.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "ejectAtRoomExp", "description": "Whether participants are removed when the Daily room expires.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "ejectAfterElapsed", "description": "Elapsed session duration after which to eject participants, in seconds.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableMeshSfu", "description": "Topology and bandwidth", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sfuSwitchover", "description": "Daily topology setting controlling the switch to SFU transport.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableAdaptiveSimulcast", "description": "Whether adaptive simulcast is enabled for the Daily room.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableMultipartyAdaptiveSimulcast", "description": "Whether multiparty adaptive simulcast is enabled for the Daily room.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "experimentalOptimizeLargeCalls", "description": "Whether Daily’s experimental large-call optimization is requested.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "lang", "description": "Localization and hooks", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "meetingJoinHook", "description": "Webhook URL invoked by the Daily meeting-join hook.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "geo", "description": "Regions\nRegion selected for the Daily room’s media infrastructure.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "rtmpGeo", "description": "Region selected for Daily RTMP streaming.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "disableRtmpGeoFallback", "description": "Whether automatic RTMP region fallback is disabled.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "recordingsBucket", "description": "Storage destination configured for Daily recordings.", "presence": "message", "required": false, "requestRequired": false }, { "name": "transcriptionBucket", "description": "Storage destination configured for Daily transcriptions.", "presence": "message", "required": false, "requestRequired": false }, { "name": "recordingsTemplate", "description": "Template used for recording object names in storage.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "transcriptionTemplate", "description": "Template used for transcription object names in storage.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "DailySession", "title": "DailySession", "slug": "/api/models/daily-session", "description": "Session metadata for a Daily/Pipecat voice session", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "voice-media", "role": "domain-model", "title": "DailySession", "slug": "/api/models/daily-session" }, "usedBy": [ "conversations:createDailySession" ], "usedByRoots": [], "fields": [ { "name": "agentName", "description": "Name of the Pipecat agent running this voice session.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sessionId", "description": "Identifier of the Pipecat voice session.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "dailyRoom", "description": "Daily room address associated with the voice session.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "dailyToken", "description": "Daily meeting token issued for the voice session.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "userData", "description": "Generic body payload used to start.", "presence": "message", "required": false, "requestRequired": false }, { "name": "dailyRoomProperties", "description": "Properties passed to Daily when configuring the session room.", "presence": "message", "required": false, "requestRequired": false }, { "name": "dailyMeetingTokenProperties", "description": "Properties passed to Daily when issuing the meeting token.", "presence": "message", "required": false, "requestRequired": false }, { "name": "startedAt", "description": "Time when the operation started.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "Dataset", "title": "Dataset", "slug": "/api/models/dataset", "description": "Evaluation dataset metadata, item counts, run history, and input/output schemas.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "Dataset", "slug": "/api/models/dataset" }, "usedBy": [ "evals:listDatasets" ], "usedByRoots": [], "fields": [ { "name": "datasetId", "description": "Identifier of the evaluation dataset.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Name identifying the evaluation dataset.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Human-readable description of the resource.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadataJson", "description": "Additional attributes serialized as a JSON object.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "itemCount", "description": "Number of dataset items reported for the dataset or run.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "runCount", "description": "Number of runs reported for the evaluation dataset.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time when this record was created.", "presence": "message", "required": false, "requestRequired": false }, { "name": "lastRunAt", "description": "Time when the dataset was most recently evaluated.", "presence": "message", "required": false, "requestRequired": false }, { "name": "inputSchemaJson", "description": "JSON Schema describing dataset input values.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "expectedOutputSchemaJson", "description": "JSON Schema describing expected dataset output values.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "DatasetItem", "title": "DatasetItem", "slug": "/api/models/dataset-item", "description": "One evaluation input with its expected output and source trace references.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "DatasetItem", "slug": "/api/models/dataset-item" }, "usedBy": [ "evals:listDatasetItems" ], "usedByRoots": [], "fields": [ { "name": "itemId", "description": "Identifier of the dataset or annotation queue item.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "datasetId", "description": "Identifier of the evaluation dataset.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "datasetName", "description": "Name of the evaluation dataset.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "inputJson", "description": "Evaluation input serialized as JSON.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "expectedOutputJson", "description": "Expected output serialized as JSON. Empty until a curator supplies an expected result.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadataJson", "description": "Additional attributes serialized as a JSON object.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sourceTraceId", "description": "Identifier of the trace from which the dataset item originated.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sourceObservationId", "description": "Identifier of the observation from which the dataset item originated.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "status", "description": "State controlling whether the dataset item participates in evaluation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time when this record was created.", "presence": "message", "required": false, "requestRequired": false }, { "name": "updatedAt", "description": "Time when this record was last updated.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "DatasetRun", "title": "DatasetRun", "slug": "/api/models/dataset-run", "description": "Metadata describing one execution of an evaluation dataset.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "DatasetRun", "slug": "/api/models/dataset-run" }, "usedBy": [ "evals:getDatasetRun", "evals:listDatasetRuns" ], "usedByRoots": [], "fields": [ { "name": "runId", "description": "Identifier of the dataset or candidate evaluation run.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "datasetId", "description": "Identifier of the evaluation dataset.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Name assigned to this execution of the evaluation dataset.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Human-readable description of the resource.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadataJson", "description": "Additional attributes serialized as a JSON object.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "itemCount", "description": "Number of dataset items reported for the dataset or run.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time when this record was created.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "DatasetRunItem", "title": "DatasetRunItem", "slug": "/api/models/dataset-run-item", "description": "One item of a dataset run: which dataset item was executed, and the trace it\nproduced.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "DatasetRunItem", "slug": "/api/models/dataset-run-item" }, "usedBy": [ "evals:recordDatasetRun" ], "usedByRoots": [], "fields": [ { "name": "datasetItemId", "description": "Identifier of the dataset item used by this evaluation run.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "traceId", "description": "Identifier of the evaluation trace.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "observationId", "description": "Optional: pin the run to one observation inside the trace rather than the\nwhole turn, for a harness that scores a single generation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "DeleteAgentProfileRequest", "title": "DeleteAgentProfileRequest", "slug": "/api/models/delete-agent-profile-request", "description": "=== Delete ===\nInputs for removing an agent profile from the project library.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "DeleteAgentProfileRequest", "slug": "/api/models/delete-agent-profile-request" }, "usedBy": [ "agent-profiles:deleteAgentProfile" ], "usedByRoots": [], "fields": [ { "name": "projectId", "description": "Identifier of the project associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "profileId", "description": "Identifier of the agent profile associated with the operation or generation.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "DeleteAgentProfileResponse", "title": "DeleteAgentProfileResponse", "slug": "/api/models/delete-agent-profile-response", "description": "Response schema for removing an agent profile from the project library; no response fields are declared.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "DeleteAgentProfileResponse", "slug": "/api/models/delete-agent-profile-response" }, "usedBy": [ "agent-profiles:deleteAgentProfile" ], "usedByRoots": [], "fields": [] }, { "schemaName": "DeleteCommentRequest", "title": "DeleteCommentRequest", "slug": "/api/models/delete-comment-request", "description": "Inputs for deleting a comment attached to an evaluation object.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "DeleteCommentRequest", "slug": "/api/models/delete-comment-request" }, "usedBy": [ "evals:deleteComment" ], "usedByRoots": [], "fields": [ { "name": "commentId", "description": "Identifier of the evaluation comment.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "DeleteCommentResponse", "title": "DeleteCommentResponse", "slug": "/api/models/delete-comment-response", "description": "Result of deleting a comment attached to an evaluation object.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "DeleteCommentResponse", "slug": "/api/models/delete-comment-response" }, "usedBy": [ "evals:deleteComment" ], "usedByRoots": [], "fields": [ { "name": "deleted", "description": "Whether the deletion operation reported that it deleted the selected resource.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "DeleteCustomMCPServerRequest", "title": "DeleteCustomMCPServerRequest", "slug": "/api/models/delete-custom-mcp-server-request", "description": "Inputs for removing a tenant-owned MCP server registration.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "DeleteCustomMCPServerRequest", "slug": "/api/models/delete-custom-mcp-server-request" }, "usedBy": [ "mcp-servers:deleteCustomMcpServer" ], "usedByRoots": [], "fields": [ { "name": "projectId", "description": "Identifier of the project associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "serverId", "description": "Identifier of the MCP server associated with the operation or tool.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "DeleteCustomMCPServerResponse", "title": "DeleteCustomMCPServerResponse", "slug": "/api/models/delete-custom-mcp-server-response", "description": "Result payload for removing a tenant-owned MCP server registration.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "DeleteCustomMCPServerResponse", "slug": "/api/models/delete-custom-mcp-server-response" }, "usedBy": [ "mcp-servers:deleteCustomMcpServer" ], "usedByRoots": [], "fields": [ { "name": "deleted", "description": "False when the server did not exist; the call still succeeds.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "DeleteFileRequest", "title": "DeleteFileRequest", "slug": "/api/models/delete-file-request", "description": "Inputs for removing a stored file and its tracked metadata.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "DeleteFileRequest", "slug": "/api/models/delete-file-request" }, "usedBy": [ "storage:deleteFile" ], "usedByRoots": [], "fields": [ { "name": "fileId", "description": "Stable identifier of the stored file.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "DeleteFileResponse", "title": "DeleteFileResponse", "slug": "/api/models/delete-file-response", "description": "Result payload for removing a stored file and its tracked metadata.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "DeleteFileResponse", "slug": "/api/models/delete-file-response" }, "usedBy": [ "storage:deleteFile" ], "usedByRoots": [], "fields": [ { "name": "deleted", "description": "Whether the deletion operation reports the resource removed.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "spaceFreedBytes", "description": "Storage capacity reported freed by deletion, in bytes.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "DeleteFolderRequest", "title": "DeleteFolderRequest", "slug": "/api/models/delete-folder-request", "description": "Inputs for removing a folder entry and optionally its descendant content.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "DeleteFolderRequest", "slug": "/api/models/delete-folder-request" }, "usedBy": [ "storage:deleteFolder" ], "usedByRoots": [], "fields": [ { "name": "folderPath", "description": "Path of the folder within the user’s storage namespace.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "recursive", "description": "Whether the operation includes descendant folders and their contents.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "DeleteFolderResponse", "title": "DeleteFolderResponse", "slug": "/api/models/delete-folder-response", "description": "Result payload for removing a folder entry and optionally its descendant content.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "DeleteFolderResponse", "slug": "/api/models/delete-folder-response" }, "usedBy": [ "storage:deleteFolder" ], "usedByRoots": [], "fields": [ { "name": "deleted", "description": "Whether the deletion operation reports the resource removed.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "filesDeleted", "description": "Number of files reported deleted by the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "foldersDeleted", "description": "Number of folders reported deleted by the operation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "DeleteInboxMessageRequest", "title": "DeleteInboxMessageRequest", "slug": "/api/models/delete-inbox-message-request", "description": "Caller user_id derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "DeleteInboxMessageRequest", "slug": "/api/models/delete-inbox-message-request" }, "usedBy": [ "notifications:deleteInboxMessage" ], "usedByRoots": [], "fields": [ { "name": "messageId", "description": "Identifier of the inbox message to read or modify.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "DeleteInboxMessageResponse", "title": "DeleteInboxMessageResponse", "slug": "/api/models/delete-inbox-message-response", "description": "Result payload for removing an identified message from the subscriber’s notification inbox.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "DeleteInboxMessageResponse", "slug": "/api/models/delete-inbox-message-response" }, "usedBy": [ "notifications:deleteInboxMessage" ], "usedByRoots": [], "fields": [ { "name": "status", "description": "Status reported by the notification provider.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "DeleteJobRequest", "title": "DeleteJobRequest", "slug": "/api/models/delete-job-request", "description": "Inputs for deleting a scheduled job and its trigger settings.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "scheduling", "role": "operation-envelope", "title": "DeleteJobRequest", "slug": "/api/models/delete-job-request" }, "usedBy": [ "scheduled-jobs:deleteJob" ], "usedByRoots": [], "fields": [ { "name": "scheduleId", "description": "Identifier of the scheduled job.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "externalId", "description": "Caller-assigned correlation identifier for the scheduled job.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "DeleteJobResponse", "title": "DeleteJobResponse", "slug": "/api/models/delete-job-response", "description": "Result of deleting a scheduled job and its trigger settings.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "scheduling", "role": "operation-envelope", "title": "DeleteJobResponse", "slug": "/api/models/delete-job-response" }, "usedBy": [ "scheduled-jobs:deleteJob" ], "usedByRoots": [], "fields": [ { "name": "scheduleId", "description": "Identifier of the scheduled job.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "DeleteJobsForOwnerRequest", "title": "DeleteJobsForOwnerRequest", "slug": "/api/models/delete-jobs-for-owner-request", "description": "Tenant/project come from the ingress headers. The owner is the caller\nitself (derived from x-user-id) — there are no body fields.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "scheduling", "role": "operation-envelope", "title": "DeleteJobsForOwnerRequest", "slug": "/api/models/delete-jobs-for-owner-request" }, "usedBy": [ "scheduled-jobs:deleteJobsForOwner" ], "usedByRoots": [], "fields": [] }, { "schemaName": "DeleteJobsForOwnerResponse", "title": "DeleteJobsForOwnerResponse", "slug": "/api/models/delete-jobs-for-owner-response", "description": "Result of deleting scheduled jobs belonging to the selected owner.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "scheduling", "role": "operation-envelope", "title": "DeleteJobsForOwnerResponse", "slug": "/api/models/delete-jobs-for-owner-response" }, "usedBy": [ "scheduled-jobs:deleteJobsForOwner" ], "usedByRoots": [], "fields": [ { "name": "deletedCount", "description": "Number of scheduled jobs deleted by the operation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "DeleteJobsForProjectRequest", "title": "DeleteJobsForProjectRequest", "slug": "/api/models/delete-jobs-for-project-request", "description": "Tenant/project come from the ingress headers — the request body carries no\nfields.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "scheduling", "role": "operation-envelope", "title": "DeleteJobsForProjectRequest", "slug": "/api/models/delete-jobs-for-project-request" }, "usedBy": [ "scheduled-jobs:deleteJobsForProject" ], "usedByRoots": [], "fields": [] }, { "schemaName": "DeleteJobsForProjectResponse", "title": "DeleteJobsForProjectResponse", "slug": "/api/models/delete-jobs-for-project-response", "description": "Result of deleting scheduled jobs within the selected project.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "scheduling", "role": "operation-envelope", "title": "DeleteJobsForProjectResponse", "slug": "/api/models/delete-jobs-for-project-response" }, "usedBy": [ "scheduled-jobs:deleteJobsForProject" ], "usedByRoots": [], "fields": [ { "name": "deletedCount", "description": "Number of scheduled jobs deleted by the operation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "DeleteMemoryRequest", "title": "DeleteMemoryRequest", "slug": "/api/models/delete-memory-request", "description": "Input for deleting a memory record by its identifier.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "memory-knowledge", "role": "operation-envelope", "title": "DeleteMemoryRequest", "slug": "/api/models/delete-memory-request" }, "usedBy": [ "conversations:deleteMemory" ], "usedByRoots": [], "fields": [ { "name": "memoryId", "description": "Memory ID to delete", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "DeleteMemoryResponse", "title": "DeleteMemoryResponse", "slug": "/api/models/delete-memory-response", "description": "Result of deleting a memory record by its identifier.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "memory-knowledge", "role": "operation-envelope", "title": "DeleteMemoryResponse", "slug": "/api/models/delete-memory-response" }, "usedBy": [ "conversations:deleteMemory" ], "usedByRoots": [], "fields": [ { "name": "success", "description": "Whether deletion was successful", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "DeleteMessageRatingRequest", "title": "DeleteMessageRatingRequest", "slug": "/api/models/delete-message-rating-request", "description": "Withdraw the caller's own rating on a message in a thread. As with\nRateMessage, the rater is derived server-side from the verified request\nheaders; there is deliberately no \"whose rating\" parameter.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "DeleteMessageRatingRequest", "slug": "/api/models/delete-message-rating-request" }, "usedBy": [ "conversations:deleteMessageRating" ], "usedByRoots": [], "fields": [ { "name": "conversationKey", "description": "Identifier of the conversation thread.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "messageSequence", "description": "Message whose rating to withdraw (by sequence number)", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "DeleteMessageRatingResponse", "title": "DeleteMessageRatingResponse", "slug": "/api/models/delete-message-rating-response", "description": "Result of withdrawing the caller’s rating on a conversation message.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "DeleteMessageRatingResponse", "slug": "/api/models/delete-message-rating-response" }, "usedBy": [ "conversations:deleteMessageRating" ], "usedByRoots": [], "fields": [ { "name": "ratedMessage", "description": "The message with the caller's entry removed from the feedback list", "presence": "message", "required": false, "requestRequired": false }, { "name": "removed", "description": "False when the caller had no rating on this message — an idempotent\nsuccess, not an error.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "DeletePromptFragmentRequest", "title": "DeletePromptFragmentRequest", "slug": "/api/models/delete-prompt-fragment-request", "description": "=== Delete fragment ===\nInputs for removing a reusable prompt fragment from the project library.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "DeletePromptFragmentRequest", "slug": "/api/models/delete-prompt-fragment-request" }, "usedBy": [ "agent-profiles:deletePromptFragment" ], "usedByRoots": [], "fields": [ { "name": "projectId", "description": "Identifier of the project associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "fragmentId", "description": "Identifier of the reusable prompt fragment.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "DeletePromptFragmentResponse", "title": "DeletePromptFragmentResponse", "slug": "/api/models/delete-prompt-fragment-response", "description": "Response schema for removing a reusable prompt fragment from the project library; no response fields are declared.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "DeletePromptFragmentResponse", "slug": "/api/models/delete-prompt-fragment-response" }, "usedBy": [ "agent-profiles:deletePromptFragment" ], "usedByRoots": [], "fields": [] }, { "schemaName": "DeleteScoreRequest", "title": "DeleteScoreRequest", "slug": "/api/models/delete-score-request", "description": "Inputs for deleting a score attached to an evaluation object.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "DeleteScoreRequest", "slug": "/api/models/delete-score-request" }, "usedBy": [ "evals:deleteScore" ], "usedByRoots": [], "fields": [ { "name": "scoreId", "description": "Identifier of the recorded evaluation score.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "DeleteScoreResponse", "title": "DeleteScoreResponse", "slug": "/api/models/delete-score-response", "description": "Result of deleting a score attached to an evaluation object.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "DeleteScoreResponse", "slug": "/api/models/delete-score-response" }, "usedBy": [ "evals:deleteScore" ], "usedByRoots": [], "fields": [ { "name": "deleted", "description": "Whether the deletion operation reported that it deleted the selected resource.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "DeleteSecretRequest", "title": "DeleteSecretRequest", "slug": "/api/models/delete-secret-request", "description": "Selects a project secret to delete and whether to override reference checks.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "secrets", "role": "operation-envelope", "title": "DeleteSecretRequest", "slug": "/api/models/delete-secret-request" }, "usedBy": [ "secrets:deleteSecret" ], "usedByRoots": [], "fields": [ { "name": "name", "description": "Name identifying the secret within its project.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "force", "description": "Delete even when custom MCP servers still reference this secret. Those\nservers then fail closed the next time they try to resolve it.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "DeleteSecretResponse", "title": "DeleteSecretResponse", "slug": "/api/models/delete-secret-response", "description": "Result of deleting a project secret.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "secrets", "role": "operation-envelope", "title": "DeleteSecretResponse", "slug": "/api/models/delete-secret-response" }, "usedBy": [ "secrets:deleteSecret" ], "usedByRoots": [], "fields": [ { "name": "deleted", "description": "False when the secret did not exist; the call still succeeds.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "DeleteSubscriberRequest", "title": "DeleteSubscriberRequest", "slug": "/api/models/delete-subscriber-request", "description": "Caller user_id derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "DeleteSubscriberRequest", "slug": "/api/models/delete-subscriber-request" }, "usedBy": [ "notifications:deleteSubscriber" ], "usedByRoots": [], "fields": [] }, { "schemaName": "DeleteSubscriberResponse", "title": "DeleteSubscriberResponse", "slug": "/api/models/delete-subscriber-response", "description": "Result payload for removing the subscriber’s notification-provider record.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "DeleteSubscriberResponse", "slug": "/api/models/delete-subscriber-response" }, "usedBy": [ "notifications:deleteSubscriber" ], "usedByRoots": [], "fields": [ { "name": "status", "description": "Status reported by the notification provider.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "DeleteTopicRequest", "title": "DeleteTopicRequest", "slug": "/api/models/delete-topic-request", "description": "Inputs for removing an identified notification topic.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "DeleteTopicRequest", "slug": "/api/models/delete-topic-request" }, "usedBy": [ "notifications:deleteTopic" ], "usedByRoots": [], "fields": [ { "name": "topicKey", "description": "Caller-facing key identifying a notification topic.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "DeleteTopicResponse", "title": "DeleteTopicResponse", "slug": "/api/models/delete-topic-response", "description": "Result payload for removing an identified notification topic.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "DeleteTopicResponse", "slug": "/api/models/delete-topic-response" }, "usedBy": [ "notifications:deleteTopic" ], "usedByRoots": [], "fields": [ { "name": "status", "description": "Status reported by the notification provider.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "DeleteWebhookEndpointRequest", "title": "DeleteWebhookEndpointRequest", "slug": "/api/models/delete-webhook-endpoint-request", "description": "Inputs for removing a tenant’s webhook delivery destination.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "webhooks", "role": "operation-envelope", "title": "DeleteWebhookEndpointRequest", "slug": "/api/models/delete-webhook-endpoint-request" }, "usedBy": [ "webhooks:deleteWebhookEndpoint" ], "usedByRoots": [], "fields": [ { "name": "endpointId", "description": "Identifier of the webhook endpoint receiving deliveries.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "DeleteWebhookEndpointResponse", "title": "DeleteWebhookEndpointResponse", "slug": "/api/models/delete-webhook-endpoint-response", "description": "Response schema for removing a tenant’s webhook delivery destination; no response fields are declared.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "webhooks", "role": "operation-envelope", "title": "DeleteWebhookEndpointResponse", "slug": "/api/models/delete-webhook-endpoint-response" }, "usedBy": [ "webhooks:deleteWebhookEndpoint" ], "usedByRoots": [], "fields": [] }, { "schemaName": "DeleteWebhookSubscriptionRequest", "title": "DeleteWebhookSubscriptionRequest", "slug": "/api/models/delete-webhook-subscription-request", "description": "Inputs for removing a tenant webhook subscription by its external identifier.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "webhooks", "role": "operation-envelope", "title": "DeleteWebhookSubscriptionRequest", "slug": "/api/models/delete-webhook-subscription-request" }, "usedBy": [ "webhooks:deleteWebhookSubscription" ], "usedByRoots": [], "fields": [ { "name": "subscriptionId", "description": "Identifier of the subscription to delete. Supply exactly one of subscription_id or\nexternal_id.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "externalId", "description": "Stable external identifier used to address the webhook subscription.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "DeleteWebhookSubscriptionResponse", "title": "DeleteWebhookSubscriptionResponse", "slug": "/api/models/delete-webhook-subscription-response", "description": "Response schema for removing a tenant webhook subscription by its external identifier; no response fields are declared.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "webhooks", "role": "operation-envelope", "title": "DeleteWebhookSubscriptionResponse", "slug": "/api/models/delete-webhook-subscription-response" }, "usedBy": [ "webhooks:deleteWebhookSubscription" ], "usedByRoots": [], "fields": [] }, { "schemaName": "DeleteWorkflowRequest", "title": "DeleteWorkflowRequest", "slug": "/api/models/delete-workflow-request", "description": "tenant_id and environment derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "DeleteWorkflowRequest", "slug": "/api/models/delete-workflow-request" }, "usedBy": [ "notifications:deleteWorkflow" ], "usedByRoots": [], "fields": [ { "name": "workflowId", "description": "Identifier of the notification workflow to execute or configure.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "triggerIdentifier", "description": "Trigger identifier used to address a notification workflow.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "DeleteWorkflowResponse", "title": "DeleteWorkflowResponse", "slug": "/api/models/delete-workflow-response", "description": "Result payload for removing an identified notification workflow definition.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "DeleteWorkflowResponse", "slug": "/api/models/delete-workflow-response" }, "usedBy": [ "notifications:deleteWorkflow" ], "usedByRoots": [], "fields": [ { "name": "workflowId", "description": "Identifier of the notification workflow to execute or configure.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "Endpoint", "title": "Endpoint", "slug": "/api/models/endpoint", "description": "Provider record describing a webhook delivery destination and its delivery settings.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "webhooks", "role": "domain-model", "title": "Endpoint", "slug": "/api/models/endpoint" }, "usedBy": [ "webhooks:createWebhookEndpoint", "webhooks:listWebhookEndpoints", "webhooks:updateWebhookEndpoint" ], "usedByRoots": [], "fields": [ { "name": "id", "description": "Identifier of the endpoint record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Display name of the webhook delivery destination.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "url", "description": "URL associated with the resource or outbound request.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Human-readable description of the resource.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "status", "description": "Current state of the webhook endpoint.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "secret", "description": "Secret associated with the webhook endpoint or deployed trigger.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "httpTimeout", "description": "Timeout for an individual webhook HTTP delivery, in seconds.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "rateLimit", "description": "Maximum delivery rate configured for the webhook endpoint.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "rateLimitDuration", "description": "Delivery-rate window returned as a seconds-suffixed duration string (for example, 60s).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time when this record was created.", "presence": "message", "required": false, "requestRequired": false }, { "name": "updatedAt", "description": "Time when this record was last updated.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "EndUserState", "title": "EndUserState", "slug": "/api/models/end-user-state", "description": "Captured identity claims and editable profile values for a tenant's end user.\nIdentity claims are copied from the verified token and are read-only through the\nprofile update operations. Location, locale overrides, generation preferences and\napplication metadata are set through their corresponding profile update operations.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "identity-access", "role": "domain-model", "title": "EndUserState", "slug": "/api/models/end-user-state" }, "usedBy": [ "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "subject", "description": "Subject claim identifying the end user within the identity provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "tenantId", "description": "Identifier of the tenant that owns or scopes this record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "issuer", "description": "OIDC issuer identifying the identity provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "projectId", "description": "Identifier of the project within the tenant that scopes this record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "email", "description": "Email address received from the identity provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "emailVerified", "description": "Whether the identity provider marked the email address as verified.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Full name received from the identity provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "givenName", "description": "Given-name claim received from the identity provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "familyName", "description": "Family-name claim received from the identity provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "preferredUsername", "description": "Preferred username claim received from the identity provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "picture", "description": "Profile picture URL received from the identity provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "phoneNumber", "description": "Telephone number received from the identity provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "phoneNumberVerified", "description": "Whether the identity provider marked the telephone number as verified.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "signInProvider", "description": "Sign-in provider recorded with the captured identity.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "authMethod", "description": "Authentication method recorded with the captured identity.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "locale", "description": "Locale preference associated with the user or subscriber. IdP-sourced default (not the\noverride).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "zoneinfo", "description": "Time zone claim received from the identity provider. IdP-sourced default.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "customClaims", "description": "Additional identity claims stored as string key-value pairs.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "location", "description": "Coordinates and derived location metadata selected by the end user.", "presence": "message", "required": false, "requestRequired": false }, { "name": "localeOverride", "description": "Locale explicitly selected by the end user. When set, takes precedence over the\nidentity provider's locale; when empty, the identity-provider locale is used.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "defaultGenerationConfig", "description": "Default model generation settings associated with the end-user profile.", "presence": "message", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Application-defined key-value metadata associated with the end user.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "firstSeenAt", "description": "Time the end-user identity was first captured.", "presence": "message", "required": false, "requestRequired": false }, { "name": "lastSeenAt", "description": "Time the end user's identity was most recently observed.", "presence": "message", "required": false, "requestRequired": false }, { "name": "updatedAt", "description": "Time this record was most recently updated.", "presence": "message", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time this record was created.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "EndUserUpdateDefaultGenerationConfigRequest", "title": "EndUserUpdateDefaultGenerationConfigRequest", "slug": "/api/models/end-user-update-default-generation-config-request", "description": "Inputs for updating default model generation settings.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "identity-access", "role": "operation-envelope", "title": "EndUserUpdateDefaultGenerationConfigRequest", "slug": "/api/models/end-user-update-default-generation-config-request" }, "usedBy": [ "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [], "fields": [ { "name": "config", "description": "Default generation settings restricted to these user-settable fields: model, models,\ntemperature, top_p, max_output_tokens, frequency_penalty, presence_penalty,\nstop_sequences, seed and language_preference. Recognized fields outside this list,\nincluding operational settings for prompts, tools, MCP and timeouts, reject the whole\nrequest. New GenerationConfig fields are rejected unless added to this allowlist.\nEach model must also be permitted by the platform model allowlist. Unknown JSON names\nmay be discarded before these checks; they are not supported configuration settings.", "presence": "message", "required": true, "requestRequired": true } ] }, { "schemaName": "EndUserUpdateDefaultGenerationConfigResponse", "title": "EndUserUpdateDefaultGenerationConfigResponse", "slug": "/api/models/end-user-update-default-generation-config-response", "description": "Result of updating default model generation settings. This schema declares no result fields.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "identity-access", "role": "operation-envelope", "title": "EndUserUpdateDefaultGenerationConfigResponse", "slug": "/api/models/end-user-update-default-generation-config-response" }, "usedBy": [ "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [], "fields": [] }, { "schemaName": "EnqueueForAnnotationRequest", "title": "EnqueueForAnnotationRequest", "slug": "/api/models/enqueue-for-annotation-request", "description": "Inputs for adding an evaluation object to an annotation queue.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "EnqueueForAnnotationRequest", "slug": "/api/models/enqueue-for-annotation-request" }, "usedBy": [ "evals:enqueueForAnnotation" ], "usedByRoots": [], "fields": [ { "name": "queueId", "description": "Identifier of the evaluation annotation queue.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "targetType", "description": "Kind of evaluation object targeted by the score or annotation.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "targetId", "description": "Identifier of the evaluation object targeted by the score or annotation.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "EnqueueForAnnotationResponse", "title": "EnqueueForAnnotationResponse", "slug": "/api/models/enqueue-for-annotation-response", "description": "Result of adding an evaluation object to an annotation queue.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "EnqueueForAnnotationResponse", "slug": "/api/models/enqueue-for-annotation-response" }, "usedBy": [ "evals:enqueueForAnnotation" ], "usedByRoots": [], "fields": [ { "name": "queueItemId", "description": "Identifier assigned to the item in the annotation queue.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ErrorDetails", "title": "ErrorDetails", "slug": "/api/models/error-details", "description": "Typed error details container. Concrete fields instead of Any for\ntype safety across languages. At most one of each detail type.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "ErrorDetails", "slug": "/api/models/error-details" }, "usedBy": [ "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "errorInfo", "description": "Identifies the error for machine consumption.\nREQUIRED on all errors per AIP-193 (enforced at Go helper level).", "presence": "message", "required": false, "requestRequired": false }, { "name": "retryInfo", "description": "Retry guidance for transient errors.", "presence": "message", "required": false, "requestRequired": false }, { "name": "fieldViolations", "description": "Field-level validation failures.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "upstreamError", "description": "Upstream provider error context.", "presence": "message", "required": false, "requestRequired": false }, { "name": "modelError", "description": "Model-specific error context.", "presence": "message", "required": false, "requestRequired": false }, { "name": "helpLinks", "description": "Help links for error resolution.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "ErrorDetailsInput", "title": "ErrorDetails", "slug": "/api/models/error-details-input", "description": "Typed error details container. Concrete fields instead of Any for\ntype safety across languages. At most one of each detail type.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "ErrorDetails", "slug": "/api/models/error-details" }, "usedBy": [ "conversations:submitClientToolResults", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "errorInfo", "description": "Identifies the error for machine consumption.\nREQUIRED on all errors per AIP-193 (enforced at Go helper level).", "presence": "message", "required": false, "requestRequired": false }, { "name": "retryInfo", "description": "Retry guidance for transient errors.", "presence": "message", "required": false, "requestRequired": false }, { "name": "fieldViolations", "description": "Field-level validation failures.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "upstreamError", "description": "Upstream provider error context.", "presence": "message", "required": false, "requestRequired": false }, { "name": "modelError", "description": "Model-specific error context.", "presence": "message", "required": false, "requestRequired": false }, { "name": "helpLinks", "description": "Help links for error resolution.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "ErrorDetailsWebhook", "title": "ErrorDetails", "slug": "/api/models/error-details-webhook", "description": "Typed error details container. Concrete fields instead of Any for\ntype safety across languages. At most one of each detail type.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "ErrorDetails", "slug": "/api/models/error-details" }, "usedBy": [], "usedByRoots": [ "llm.generation_completed" ], "fields": [ { "name": "error_info", "description": "Identifies the error for machine consumption.\nREQUIRED on all errors per AIP-193 (enforced at Go helper level).", "presence": "message", "required": false, "requestRequired": false }, { "name": "retry_info", "description": "Retry guidance for transient errors.", "presence": "message", "required": false, "requestRequired": false }, { "name": "field_violations", "description": "Field-level validation failures.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "upstream_error", "description": "Upstream provider error context.", "presence": "message", "required": false, "requestRequired": false }, { "name": "model_error", "description": "Model-specific error context.", "presence": "message", "required": false, "requestRequired": false }, { "name": "help_links", "description": "Help links for error resolution.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "ErrorInfo", "title": "ErrorInfo", "slug": "/api/models/error-info", "description": "Machine-readable error identification (per AIP-193, every error must include this).", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "ErrorInfo", "slug": "/api/models/error-info" }, "usedBy": [ "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "reason", "description": "Stable machine-readable reason string (e.g., \"MODEL_NOT_FOUND\",\n\"RATE_LIMITED\", \"MODERATION_FLAGGED\").\nUnique within the domain. Clients may switch on this field.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "domain", "description": "Machine-readable namespace identifying the origin of the error.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Arbitrary key-value metadata. If the message field mentions a specific\nvalue (model name, field path, etc.), it MUST also appear here.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "ErrorInfoInput", "title": "ErrorInfo", "slug": "/api/models/error-info-input", "description": "Machine-readable error identification (per AIP-193, every error must include this).", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "ErrorInfo", "slug": "/api/models/error-info" }, "usedBy": [ "conversations:submitClientToolResults", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "reason", "description": "Stable machine-readable reason string (e.g., \"MODEL_NOT_FOUND\",\n\"RATE_LIMITED\", \"MODERATION_FLAGGED\").\nUnique within the domain. Clients may switch on this field.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "domain", "description": "Machine-readable namespace identifying the origin of the error.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Arbitrary key-value metadata. If the message field mentions a specific\nvalue (model name, field path, etc.), it MUST also appear here.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "ErrorInfoWebhook", "title": "ErrorInfo", "slug": "/api/models/error-info-webhook", "description": "Machine-readable error identification (per AIP-193, every error must include this).", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "ErrorInfo", "slug": "/api/models/error-info" }, "usedBy": [], "usedByRoots": [ "llm.generation_completed" ], "fields": [ { "name": "reason", "description": "Stable machine-readable reason string (e.g., \"MODEL_NOT_FOUND\",\n\"RATE_LIMITED\", \"MODERATION_FLAGGED\").\nUnique within the domain. Clients may switch on this field.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "domain", "description": "Machine-readable namespace identifying the origin of the error.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Arbitrary key-value metadata. If the message field mentions a specific\nvalue (model name, field path, etc.), it MUST also appear here.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "EvalFilter", "title": "EvalFilter", "slug": "/api/models/eval-filter", "description": "Typed comparison operand and column selector for querying evaluation-provider records.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "EvalFilter", "slug": "/api/models/eval-filter" }, "usedBy": [ "evals:listObservations", "evals:listScores", "evals:listSessions", "evals:listTraces" ], "usedByRoots": [], "fields": [ { "name": "type", "description": "Discriminator selecting the evaluation filter’s operand type.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "column", "description": "Evaluation filter column identifier, for example traceName, scores_avg, metadata or level.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "operator", "description": "Operator accepted for the selected filter type, for example contains, any of or >=.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "key", "description": "Set only for the *_OBJECT types: the metadata key or score name.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "stringValue", "description": "Exactly one value field is meaningful, chosen by type — flat siblings\nrather than a oneof, per repo convention.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "numberValue", "description": "Numeric operand used by the evaluation filter.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "booleanValue", "description": "Boolean operand or score value used by the selected evaluation type.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "stringValues", "description": "The *_OPTIONS types.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "timeValue", "description": "Timestamp operand used by the evaluation filter.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "EvalOverview", "title": "EvalOverview", "slug": "/api/models/eval-overview", "description": "Aggregated trace, score, latency, and profile metrics for an evaluation window.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "EvalOverview", "slug": "/api/models/eval-overview" }, "usedBy": [ "evals:getOverview" ], "usedByRoots": [], "fields": [ { "name": "totalTraces", "description": "Total trace count reported for the selected evaluation window.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "tracesByName", "description": "Trace counts grouped by trace name.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "tracesOverTime", "description": "Trace counts grouped into time buckets.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "observationsByLevel", "description": "Observation counts grouped by reported log level.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "scores", "description": "Score aggregates grouped separately by metric name and source.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "scoreMovingAverage", "description": "Moving-average score series returned for the selected window.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "scoredTraceRatio", "description": "Coverage card: share of traces carrying any score, and the annotated count.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "annotatedTraceCount", "description": "Number of traces reported to have annotations in the selected window.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "byProfile", "description": "Evaluation metrics grouped by agent profile.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "latencyPercentiles", "description": "Latency percentile summaries grouped by trace name.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "recentLowScores", "description": "Recent scores selected by the overview’s low-score query.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "EvaluationPageInfo", "title": "EvaluationPageInfo", "slug": "/api/models/evaluation-page-info", "description": "Offset-pagination position, page size and result totals.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "EvaluationPageInfo", "slug": "/api/models/evaluation-page-info" }, "usedBy": [ "evals:listAnnotationQueueItems", "evals:listAnnotationQueues", "evals:listComments", "evals:listDatasetItems", "evals:listDatasets", "evals:listScoreConfigs" ], "usedByRoots": [], "fields": [ { "name": "page", "description": "One-based page number.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "limit", "description": "Maximum number of entries requested from the listing.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "totalItems", "description": "Total item count reported for the selected dataset query.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "totalPages", "description": "Total number of pages reported for the current query.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "EventContextWebhook", "title": "EventContext", "slug": "/api/models/event-context-webhook", "description": "EventContext standardizes event envelope metadata for domain events", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "EventContext", "slug": "/api/models/event-context" }, "usedBy": [], "usedByRoots": [ "llm.generation_completed", "llm.generation_started", "llm.message_published", "llm.tool_call_approval_required", "llm.tool_call_completed", "llm.tool_call_started" ], "fields": [ { "name": "event_name", "description": "Stable event name, e.g. \"llm.message_published\"", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "version", "description": "Version of the event schema (semver or simple numeric)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "event_id", "description": "Unique event identifier (UUID)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "correlation_id", "description": "Correlation identifier (e.g., session/workflow/conversation id)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "emitted_at", "description": "RFC3339 timestamp string of when the event was emitted", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "caller_key", "description": "Publisher-provided routing key (e.g., conversation/thread id)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Application-level metadata (not transport tracing headers)", "presence": "collection", "required": false, "requestRequired": false }, { "name": "tenant_id", "description": "Identifier of the tenant to which the event belongs, used to select that tenant’s webhook\ndestinations.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "project_id", "description": "Identifier of the project within the tenant that scopes the event. Defaults to default when no\nproject is supplied.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "session_id", "description": "Identifier of the end-user application session associated with the event, distinct from tenant\nand conversation identity.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "EventDelivery", "title": "EventDelivery", "slug": "/api/models/event-delivery", "description": "Delivery-attempt state and response information for a webhook event.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "webhooks", "role": "domain-model", "title": "EventDelivery", "slug": "/api/models/event-delivery" }, "usedBy": [ "webhooks:listWebhookDeliveries", "webhooks:retryWebhookDelivery" ], "usedByRoots": [], "fields": [ { "name": "id", "description": "Identifier of the event delivery record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "eventId", "description": "Identifier of the webhook event being delivered.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "endpointId", "description": "Identifier of the webhook endpoint receiving deliveries.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "status", "description": "Current delivery status reported for this webhook event attempt.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "attempts", "description": "Number of delivery attempts reported for the webhook event.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "eventType", "description": "Type of the webhook event represented by this delivery.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time when this record was created.", "presence": "message", "required": false, "requestRequired": false }, { "name": "updatedAt", "description": "Time when this record was last updated.", "presence": "message", "required": false, "requestRequired": false }, { "name": "httpStatus", "description": "HTTP response status reported for the delivery attempt.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "responseData", "description": "Response body reported by the webhook delivery target.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "error", "description": "Error information reported for this operation or item.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "Execution", "title": "Execution", "slug": "/api/models/execution", "description": "Execution is a single firing record for a scheduled job.\n\nExecution records include:\n\n[`status`](/api/models/execution#response-field-status): `EXECUTION_STATUS_COMPLETED`, `EXECUTION_STATUS_FAILED`, or `EXECUTION_STATUS_CANCELLED` (cancellation, including operator or non-HTTP cancellation conditions).\n\n[`endReason`](/api/models/execution#response-field-endreason): Why a `FAILED` run failed, when the status alone does not say. `\"discarded\"` means the job exhausted [`maxAttempts`](/api/models/retry-policy#request-field-maxattempts) and will not be retried. Empty otherwise.\n\n[`httpStatus`](/api/models/execution#response-field-httpstatus): HTTP status code returned by the target.\n\n[`attempt`](/api/models/execution#response-field-attempt): Attempt number (1-based) within this firing.\n\n[`durationMs`](/api/models/execution#response-field-durationms): End-to-end duration of the delivery attempt.\n\n[`error`](/api/models/execution#response-field-error): Error message on `FAILED` outcomes.\n\n[`scheduledTime`](/api/models/execution#response-field-scheduledtime): When the execution was supposed to fire.\n\n[`startedAt`](/api/models/execution#response-field-startedat) / [`completedAt`](/api/models/execution#response-field-completedat): Actual start and completion times.\n\n[`responseBody`](/api/models/execution#response-field-responsebody): Truncated HTTP response body captured on failed dispatches (4 KiB cap). Empty for successful dispatches.\n\n[`responseHeaders`](/api/models/execution#response-field-responseheaders): Allowlisted response headers from the failed dispatch: `content-type`, `content-length`, `retry-after`, `x-request-id`, `date`.\n\n[`responseTruncated`](/api/models/execution#response-field-responsetruncated): `true` when [`responseBody`](/api/models/execution#response-field-responsebody) was clipped at the 4 KiB cap.\n\n[`responseSizeBytes`](/api/models/execution#response-field-responsesizebytes): Original response size in bytes (from `Content-Length` when present, else total bytes read before truncation).", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "scheduling", "role": "domain-model", "title": "Execution", "slug": "/api/models/execution" }, "usedBy": [ "scheduled-jobs:listExecutions" ], "usedByRoots": [], "fields": [ { "name": "executionId", "description": "Identifier of the scheduled job execution record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "scheduleId", "description": "Identifier of the scheduled job.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "tenantId", "description": "Identifier of the tenant that owns or scopes this record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "projectId", "description": "Identifier of the project within the tenant that scopes this record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "scheduledTime", "description": "Instant for which this execution or trigger was scheduled.", "presence": "message", "required": false, "requestRequired": false }, { "name": "startedAt", "description": "Time at which the subscription or execution started.", "presence": "message", "required": false, "requestRequired": false }, { "name": "completedAt", "description": "Time at which the scheduled execution completed.", "presence": "message", "required": false, "requestRequired": false }, { "name": "status", "description": "Execution outcome recorded for this scheduled attempt.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "httpStatus", "description": "HTTP status code returned by the target.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "attempt", "description": "Attempt number (1-based).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "durationMs", "description": "End-to-end duration in milliseconds.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "targetKind", "description": "Kind of target invoked by the scheduled execution.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "error", "description": "Error message when status is FAILED.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "riverJobId", "description": "Identifier of the underlying queue job that produced this scheduled execution, for correlating\nexecution diagnostics.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "responseBody", "description": "Truncated HTTP response body captured on failed dispatches. Empty for\nsuccessful dispatches by design — only error responses are stored. May\nalso be empty for binary content types or transport-level errors (see\nresponse_size_bytes / error).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "responseHeaders", "description": "Allowlisted response headers from the failed dispatch. Allowlist:\ncontent-type, content-length, retry-after, x-request-id, date.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "responseTruncated", "description": "True when response_body was clipped at the 4 KiB cap.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "responseSizeBytes", "description": "Original response size in bytes (from Content-Length when present,\nelse total bytes read before truncation).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "endReason", "description": "Explanation of an execution failure when status alone is insufficient, such as discarded after\nretry attempts were exhausted. Empty when there is no additional reason.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ExperimentContext", "title": "ExperimentContext", "slug": "/api/models/experiment-context", "description": "Dataset-run attribution attached when a scripted evaluation turn is sent. Supported on\nSendMessageRequest and SendMessageSyncRequest; ordinary conversation traffic leaves it unset.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "ExperimentContext", "slug": "/api/models/experiment-context" }, "usedBy": [ "conversations:sendMessage", "conversations:sendMessageSync" ], "usedByRoots": [], "fields": [ { "name": "datasetId", "description": "Identifier of the dataset to which this run belongs. Required whenever experiment context is\nsupplied.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "runName", "description": "Names the run. Repeating a run_name for the same dataset appends to that\nrun rather than starting a new one, because the derived experiment id is\ndeterministic — the same property that lets a retried turn land in the run\nit belongs to.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "datasetItemId", "description": "Which dataset item this turn exercises. Optional: a run can be scored on\nits traces alone, and a harness that does not model items per-turn can\nleave it empty.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Free-text description displayed with the dataset run.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadataJson", "description": "Additional run metadata serialized as a JSON object string and carried through unchanged.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "profileRevisionHash", "description": "Profile revision fingerprint attached to the dataset run for comparison and attribution.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "FieldViolation", "title": "FieldViolation", "slug": "/api/models/field-violation", "description": "A single field-level validation violation.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "FieldViolation", "slug": "/api/models/field-violation" }, "usedBy": [ "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "field", "description": "Dot-separated path to the field (e.g., \"generation_config.model\").", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Human-readable description of the violation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "FieldViolationInput", "title": "FieldViolation", "slug": "/api/models/field-violation-input", "description": "A single field-level validation violation.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "FieldViolation", "slug": "/api/models/field-violation" }, "usedBy": [ "conversations:submitClientToolResults", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "field", "description": "Dot-separated path to the field (e.g., \"generation_config.model\").", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Human-readable description of the violation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "FieldViolationWebhook", "title": "FieldViolation", "slug": "/api/models/field-violation-webhook", "description": "A single field-level validation violation.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "FieldViolation", "slug": "/api/models/field-violation" }, "usedBy": [], "usedByRoots": [ "llm.generation_completed" ], "fields": [ { "name": "field", "description": "Dot-separated path to the field (e.g., \"generation_config.model\").", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Human-readable description of the violation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "FileFilter", "title": "FileFilter", "slug": "/api/models/file-filter", "description": "Name, extension, tag, size, and upload-time criteria selecting stored files.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "domain-model", "title": "FileFilter", "slug": "/api/models/file-filter" }, "usedBy": [ "storage:listFiles", "storage:searchFiles" ], "usedByRoots": [], "fields": [ { "name": "extensions", "description": "File extensions used to restrict matching files.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "tags", "description": "Labels associated with the resource for organization or filtering.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "minSizeBytes", "description": "Minimum file size included by the filter, in bytes.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxSizeBytes", "description": "Maximum file size included by the filter, in bytes.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "uploadedAfter", "description": "Lower timestamp bound for files selected by upload time.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "uploadedBefore", "description": "Upper timestamp bound for files selected by upload time.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "nameContains", "description": "Text that must occur in the selected file’s name.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "FileInfo", "title": "FileInfo", "slug": "/api/models/file-info", "description": "FileInfo contains metadata about a file", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "domain-model", "title": "FileInfo", "slug": "/api/models/file-info" }, "usedBy": [ "storage:generateDownloadUrl", "storage:getFileMetadata", "storage:getState", "storage:listFiles", "storage:moveFile", "storage:registerUploadedFile", "storage:searchFiles", "storage:updateFileMetadata", "storage:uploadFile" ], "usedByRoots": [], "fields": [ { "name": "fileId", "description": "Stable identifier of the stored file.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Name of the file within its containing folder.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "path", "description": "Full path (e.g., \"/documents/report.pdf\").", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "folderPath", "description": "Parent folder path.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sizeBytes", "description": "Size of the file content, in bytes.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "contentType", "description": "Media type describing the file or response body.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "uploadedAt", "description": "RFC3339 timestamp.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "modifiedAt", "description": "RFC3339 timestamp.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Custom metadata.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "tags", "description": "User-defined tags.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "description", "description": "Optional description.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "storageRef", "description": "Reference to actual storage location.", "presence": "message", "required": false, "requestRequired": false }, { "name": "checksum", "description": "File checksum (SHA256).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "version", "description": "Version number (for versioning support).", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "FileResolutionConfig", "title": "FileResolutionConfig", "slug": "/api/models/file-resolution-config", "description": "Configuration for resolving CONTENT_PART_TYPE_FILE_ID parts to fresh signed\nURLs before requests are sent to LLM providers. Keeps stable file references\nin message history while generating ephemeral URLs only when needed.\n\nOmitting 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.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "FileResolutionConfig", "slug": "/api/models/file-resolution-config" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "failureMode", "description": "Action to take when a file cannot be resolved. If omitted, skip unresolved file content\nand use the remaining content.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "FileResolutionConfigInput", "title": "FileResolutionConfig", "slug": "/api/models/file-resolution-config-input", "description": "Configuration for resolving CONTENT_PART_TYPE_FILE_ID parts to fresh signed\nURLs before requests are sent to LLM providers. Keeps stable file references\nin message history while generating ephemeral URLs only when needed.\n\nOmitting 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.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "FileResolutionConfig", "slug": "/api/models/file-resolution-config" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:appendMessage", "conversations:createThread", "conversations:sendMessage", "conversations:sendMessageSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [ "generation-config" ], "fields": [ { "name": "failureMode", "description": "Action to take when a file cannot be resolved. If omitted, skip unresolved file content\nand use the remaining content.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "FileResolutionConfigWebhook", "title": "FileResolutionConfig", "slug": "/api/models/file-resolution-config-webhook", "description": "Configuration for resolving CONTENT_PART_TYPE_FILE_ID parts to fresh signed\nURLs before requests are sent to LLM providers. Keeps stable file references\nin message history while generating ephemeral URLs only when needed.\n\nOmitting 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.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "FileResolutionConfig", "slug": "/api/models/file-resolution-config" }, "usedBy": [], "usedByRoots": [ "llm.generation_started", "llm.message_published" ], "fields": [ { "name": "failure_mode", "description": "Action to take when a file cannot be resolved. If omitted, skip unresolved file content\nand use the remaining content.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "FileUrlResult", "title": "FileUrlResult", "slug": "/api/models/file-url-result", "description": "Signed download URL or item-specific error for one requested file.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "domain-model", "title": "FileUrlResult", "slug": "/api/models/file-url-result" }, "usedBy": [ "storage:batchGenerateDownloadUrls" ], "usedByRoots": [], "fields": [ { "name": "fileId", "description": "Stable identifier of the stored file.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "url", "description": "URL associated with the resource or outbound request.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "success", "description": "Whether the operation reports a successful result.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "error", "description": "Error information reported for this operation or item.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "contentType", "description": "MIME type (e.g. \"image/jpeg\"); lets consumers pick the right content-part shape (IMAGE_URL vs FILE_URL). Empty when success = false or unknown.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "FolderInfo", "title": "FolderInfo", "slug": "/api/models/folder-info", "description": "FolderInfo contains metadata about a folder", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "domain-model", "title": "FolderInfo", "slug": "/api/models/folder-info" }, "usedBy": [ "storage:createFolder", "storage:getState", "storage:listFiles" ], "usedByRoots": [], "fields": [ { "name": "folderId", "description": "Unique folder ID.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Name of the folder within its parent folder.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "path", "description": "Full path (e.g., \"/documents/work\").", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "parentPath", "description": "Parent folder path.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "RFC3339 timestamp.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "modifiedAt", "description": "RFC3339 timestamp.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Custom metadata.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "fileCount", "description": "Number of files (direct children).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "subfolderCount", "description": "Number of subfolders.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "totalSizeBytes", "description": "Total size of all files in folder (recursive).", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "GenerateDownloadUrlRequest", "title": "GenerateDownloadUrlRequest", "slug": "/api/models/generate-download-url-request", "description": "Inputs for issuing a signed URL for downloading a stored file.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "GenerateDownloadUrlRequest", "slug": "/api/models/generate-download-url-request" }, "usedBy": [ "storage:generateDownloadUrl" ], "usedByRoots": [], "fields": [ { "name": "fileId", "description": "Stable file ID to resolve to a signed URL.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "expiresSeconds", "description": "Requested lifetime of the signed URL, in seconds.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "responseContentDisposition", "description": "Content-Disposition override requested for the signed download response. Use attachment with\na filename to request a download under that name.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "GenerateDownloadUrlResponse", "title": "GenerateDownloadUrlResponse", "slug": "/api/models/generate-download-url-response", "description": "Result payload for issuing a signed URL for downloading a stored file.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "GenerateDownloadUrlResponse", "slug": "/api/models/generate-download-url-response" }, "usedBy": [ "storage:generateDownloadUrl" ], "usedByRoots": [], "fields": [ { "name": "url", "description": "URL associated with the resource or outbound request.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "file", "description": "Metadata for the file affected or retrieved by the operation.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "GenerateUploadUrlRequest", "title": "GenerateUploadUrlRequest", "slug": "/api/models/generate-upload-url-request", "description": "Inputs for issuing a signed URL for a direct file upload.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "GenerateUploadUrlRequest", "slug": "/api/models/generate-upload-url-request" }, "usedBy": [ "storage:generateUploadUrl" ], "usedByRoots": [], "fields": [ { "name": "folderPath", "description": "Path of the folder within the user’s storage namespace.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "fileName", "description": "File name to use within the selected folder.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "contentType", "description": "Media type describing the file or response body.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "expiresSeconds", "description": "Requested lifetime of the signed URL, in seconds.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Additional attributes associated with the resource.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "sizeBytes", "description": "Declared upload size in bytes. Required (> 0): pre-checked against quota and\nbound into the signed URL via x-goog-content-length-range so GCS itself\nrejects larger uploads.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "GenerateUploadUrlResponse", "title": "GenerateUploadUrlResponse", "slug": "/api/models/generate-upload-url-response", "description": "Result payload for issuing a signed URL for a direct file upload.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "GenerateUploadUrlResponse", "slug": "/api/models/generate-upload-url-response" }, "usedBy": [ "storage:generateUploadUrl" ], "usedByRoots": [], "fields": [ { "name": "url", "description": "URL associated with the resource or outbound request.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "fileId", "description": "Stable identifier of the stored file.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "fullPath", "description": "Complete object path allocated for the upload.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "requiredHeaders", "description": "HTTP headers the client must send with the signed upload request.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "GenerationConfig", "title": "GenerationConfig", "slug": "/api/models/generation-config", "description": "Canonical generation configuration\n\nSet 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.\n\nSee [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "GenerationConfig", "slug": "/api/models/generation-config" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "temperature", "description": "Sampling temperature. Omission inherits the base configuration or provider default; an\nexplicitly supplied zero remains an override.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "topP", "description": "Cumulative token-probability cutoff used for nucleus sampling.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "maxOutputTokens", "description": "Maximum output-token count requested from the model provider.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "frequencyPenalty", "description": "Sampling penalty applied to tokens according to their prior frequency.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "presencePenalty", "description": "Sampling penalty applied to tokens already present in generated content.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "stopSequences", "description": "Stop tokens/sequences (unchanged).", "presence": "collection", "required": false, "requestRequired": false }, { "name": "seed", "description": "Deterministic control where supported.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "responseFormat", "description": "Structured-output format and schema requested for the model response.", "presence": "message", "required": false, "requestRequired": false }, { "name": "allowParallelToolCalls", "description": "Allow the model to issue multiple tool calls in parallel where supported", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "model", "description": "Model selection\nPrimary model identifier requested for generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "models", "description": "Candidate models for routing.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "systemPrompt", "description": "Optional system prompt prepended as a system message. An explicitly empty value in a per-call\noverride clears the base prompt.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "modelRoutingFilter", "description": "Optional metadata-based model routing filter.\nWhen set, candidate models are filtered by these criteria before routing.", "presence": "message", "required": false, "requestRequired": false }, { "name": "provider", "description": "Provider/multi-provider routing preferences", "presence": "message", "required": false, "requestRequired": false }, { "name": "reasoning", "description": "Reasoning effort and output options passed to the model provider.", "presence": "message", "required": false, "requestRequired": false }, { "name": "usage", "description": "Token and cost accounting associated with the operation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "transforms", "description": "Provider transformations requested for the generation input.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "tools", "description": "Tools & tool policy\nTool definitions exposed to the model for server-side execution.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "toolChoice", "description": "Policy controlling whether and which tool the model may call.", "presence": "message", "required": false, "requestRequired": false }, { "name": "clientTools", "description": "Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)", "presence": "collection", "required": false, "requestRequired": false }, { "name": "toolPolicy", "description": "Per-run tool execution policy (approvals, ordering, limits, retries, timeouts)", "presence": "message", "required": false, "requestRequired": false }, { "name": "languagePreference", "description": "Language preference (BCP-47), e.g., \"en-US\", \"es-ES\" (presence-aware)", "presence": "message", "required": false, "requestRequired": false }, { "name": "timeAware", "description": "Time-aware generation options (current time, message timestamps, file timestamps)", "presence": "message", "required": false, "requestRequired": false }, { "name": "turnContext", "description": "Turn context configuration for turn-aware generation", "presence": "message", "required": false, "requestRequired": false }, { "name": "mem0", "description": "Configuration for semantic memory search, context injection and extraction during generation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "requestTimeoutSeconds", "description": "Timeout for an individual model-provider request, in seconds. Zero selects the 30-second\ndefault; other values are clamped to the range 1–600.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "fileResolution", "description": "Configuration for resolving FILE_ID content parts to fresh signed URLs before calling a model\nprovider. When unset, unresolved content is skipped.", "presence": "message", "required": false, "requestRequired": false }, { "name": "clearTools", "description": "Set to true with an empty tools list in an override to clear inherited tools. An empty list\nalone inherits the base tools. This directive applies only when merging an override.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "clearClientTools", "description": "Set to true with an empty client tools list in an override to clear inherited client tools for\nthat turn. An empty list alone inherits the base client tools, and a nonempty list replaces\nthem regardless of this directive. It applies only when merging an override and leaves server\ntool selection unchanged.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "topK", "description": "Additional provider knobs", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "repetitionPenalty", "description": "Provider sampling penalty used to discourage repeated output.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "logitBias", "description": "Per-token adjustments applied to the provider’s token-selection logits.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "topLogprobs", "description": "Number of top token log probabilities requested from the provider.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "minP", "description": "Minimum relative token probability used by supported sampling providers.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "topA", "description": "Adaptive probability cutoff used by supported sampling providers.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "user", "description": "User identifier forwarded for provider-side request attribution.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "modalities", "description": "Output modalities (e.g., [TEXT, IMAGE])", "presence": "collection", "required": false, "requestRequired": false }, { "name": "plugins", "description": "Provider plugins requested for pre-processing or post-processing.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "GenerationConfigInput", "title": "GenerationConfig", "slug": "/api/models/generation-config-input", "description": "Canonical generation configuration\n\nSet 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.\n\nSee [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "GenerationConfig", "slug": "/api/models/generation-config" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:appendMessage", "conversations:createThread", "conversations:sendMessage", "conversations:sendMessageSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [ "generation-config" ], "fields": [ { "name": "temperature", "description": "Sampling temperature. Omission inherits the base configuration or provider default; an\nexplicitly supplied zero remains an override.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "topP", "description": "Cumulative token-probability cutoff used for nucleus sampling.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "maxOutputTokens", "description": "Maximum output-token count requested from the model provider.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "frequencyPenalty", "description": "Sampling penalty applied to tokens according to their prior frequency.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "presencePenalty", "description": "Sampling penalty applied to tokens already present in generated content.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "stopSequences", "description": "Stop tokens/sequences (unchanged).", "presence": "collection", "required": false, "requestRequired": false }, { "name": "seed", "description": "Deterministic control where supported.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "responseFormat", "description": "Structured-output format and schema requested for the model response.", "presence": "message", "required": false, "requestRequired": false }, { "name": "allowParallelToolCalls", "description": "Allow the model to issue multiple tool calls in parallel where supported", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "model", "description": "Model selection\nPrimary model identifier requested for generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "models", "description": "Candidate models for routing.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "systemPrompt", "description": "Optional system prompt prepended as a system message. An explicitly empty value in a per-call\noverride clears the base prompt.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "modelRoutingFilter", "description": "Optional metadata-based model routing filter.\nWhen set, candidate models are filtered by these criteria before routing.", "presence": "message", "required": false, "requestRequired": false }, { "name": "provider", "description": "Provider/multi-provider routing preferences", "presence": "message", "required": false, "requestRequired": false }, { "name": "reasoning", "description": "Reasoning effort and output options passed to the model provider.", "presence": "message", "required": false, "requestRequired": false }, { "name": "usage", "description": "Token and cost accounting associated with the operation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "transforms", "description": "Provider transformations requested for the generation input.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "tools", "description": "Tools & tool policy\nTool definitions exposed to the model for server-side execution.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "toolChoice", "description": "Policy controlling whether and which tool the model may call.", "presence": "message", "required": false, "requestRequired": false }, { "name": "clientTools", "description": "Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)", "presence": "collection", "required": false, "requestRequired": false }, { "name": "toolPolicy", "description": "Per-run tool execution policy (approvals, ordering, limits, retries, timeouts)", "presence": "message", "required": false, "requestRequired": false }, { "name": "languagePreference", "description": "Language preference (BCP-47), e.g., \"en-US\", \"es-ES\" (presence-aware)", "presence": "message", "required": false, "requestRequired": false }, { "name": "timeAware", "description": "Time-aware generation options (current time, message timestamps, file timestamps)", "presence": "message", "required": false, "requestRequired": false }, { "name": "turnContext", "description": "Turn context configuration for turn-aware generation", "presence": "message", "required": false, "requestRequired": false }, { "name": "mem0", "description": "Configuration for semantic memory search, context injection and extraction during generation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "requestTimeoutSeconds", "description": "Timeout for an individual model-provider request, in seconds. Zero selects the 30-second\ndefault; other values are clamped to the range 1–600.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "fileResolution", "description": "Configuration for resolving FILE_ID content parts to fresh signed URLs before calling a model\nprovider. When unset, unresolved content is skipped.", "presence": "message", "required": false, "requestRequired": false }, { "name": "clearTools", "description": "Set to true with an empty tools list in an override to clear inherited tools. An empty list\nalone inherits the base tools. This directive applies only when merging an override.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "clearClientTools", "description": "Set to true with an empty client tools list in an override to clear inherited client tools for\nthat turn. An empty list alone inherits the base client tools, and a nonempty list replaces\nthem regardless of this directive. It applies only when merging an override and leaves server\ntool selection unchanged.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "topK", "description": "Additional provider knobs", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "repetitionPenalty", "description": "Provider sampling penalty used to discourage repeated output.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "logitBias", "description": "Per-token adjustments applied to the provider’s token-selection logits.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "topLogprobs", "description": "Number of top token log probabilities requested from the provider.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "minP", "description": "Minimum relative token probability used by supported sampling providers.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "topA", "description": "Adaptive probability cutoff used by supported sampling providers.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "user", "description": "User identifier forwarded for provider-side request attribution.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "modalities", "description": "Output modalities (e.g., [TEXT, IMAGE])", "presence": "collection", "required": false, "requestRequired": false }, { "name": "plugins", "description": "Provider plugins requested for pre-processing or post-processing.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "GenerationConfigWebhook", "title": "GenerationConfig", "slug": "/api/models/generation-config-webhook", "description": "Canonical generation configuration\n\nSet 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.\n\nSee [Generation configuration](/api/model-controls/configuration) for how settings combine across scopes.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "GenerationConfig", "slug": "/api/models/generation-config" }, "usedBy": [], "usedByRoots": [ "llm.generation_started", "llm.message_published" ], "fields": [ { "name": "temperature", "description": "Sampling temperature. Omission inherits the base configuration or provider default; an\nexplicitly supplied zero remains an override.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "top_p", "description": "Cumulative token-probability cutoff used for nucleus sampling.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "max_output_tokens", "description": "Maximum output-token count requested from the model provider.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "frequency_penalty", "description": "Sampling penalty applied to tokens according to their prior frequency.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "presence_penalty", "description": "Sampling penalty applied to tokens already present in generated content.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "stop_sequences", "description": "Stop tokens/sequences (unchanged).", "presence": "collection", "required": false, "requestRequired": false }, { "name": "seed", "description": "Deterministic control where supported.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "response_format", "description": "Structured-output format and schema requested for the model response.", "presence": "message", "required": false, "requestRequired": false }, { "name": "allow_parallel_tool_calls", "description": "Allow the model to issue multiple tool calls in parallel where supported", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "model", "description": "Model selection\nPrimary model identifier requested for generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "models", "description": "Candidate models for routing.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "system_prompt", "description": "Optional system prompt prepended as a system message. An explicitly empty value in a per-call\noverride clears the base prompt.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "model_routing_filter", "description": "Optional metadata-based model routing filter.\nWhen set, candidate models are filtered by these criteria before routing.", "presence": "message", "required": false, "requestRequired": false }, { "name": "provider", "description": "Provider/multi-provider routing preferences", "presence": "message", "required": false, "requestRequired": false }, { "name": "reasoning", "description": "Reasoning effort and output options passed to the model provider.", "presence": "message", "required": false, "requestRequired": false }, { "name": "usage", "description": "Token and cost accounting associated with the operation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "transforms", "description": "Provider transformations requested for the generation input.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "tools", "description": "Tools & tool policy\nTool definitions exposed to the model for server-side execution.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "tool_choice", "description": "Policy controlling whether and which tool the model may call.", "presence": "message", "required": false, "requestRequired": false }, { "name": "client_tools", "description": "Client-side tools that should be exposed to the model but executed by the client (not the workflow/MCP)", "presence": "collection", "required": false, "requestRequired": false }, { "name": "tool_policy", "description": "Per-run tool execution policy (approvals, ordering, limits, retries, timeouts)", "presence": "message", "required": false, "requestRequired": false }, { "name": "language_preference", "description": "Language preference (BCP-47), e.g., \"en-US\", \"es-ES\" (presence-aware)", "presence": "message", "required": false, "requestRequired": false }, { "name": "time_aware", "description": "Time-aware generation options (current time, message timestamps, file timestamps)", "presence": "message", "required": false, "requestRequired": false }, { "name": "turn_context", "description": "Turn context configuration for turn-aware generation", "presence": "message", "required": false, "requestRequired": false }, { "name": "mem0", "description": "Configuration for semantic memory search, context injection and extraction during generation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "request_timeout_seconds", "description": "Timeout for an individual model-provider request, in seconds. Zero selects the 30-second\ndefault; other values are clamped to the range 1–600.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "file_resolution", "description": "Configuration for resolving FILE_ID content parts to fresh signed URLs before calling a model\nprovider. When unset, unresolved content is skipped.", "presence": "message", "required": false, "requestRequired": false }, { "name": "clear_tools", "description": "Set to true with an empty tools list in an override to clear inherited tools. An empty list\nalone inherits the base tools. This directive applies only when merging an override.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "clear_client_tools", "description": "Set to true with an empty client tools list in an override to clear inherited client tools for\nthat turn. An empty list alone inherits the base client tools, and a nonempty list replaces\nthem regardless of this directive. It applies only when merging an override and leaves server\ntool selection unchanged.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "top_k", "description": "Additional provider knobs", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "repetition_penalty", "description": "Provider sampling penalty used to discourage repeated output.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "logit_bias", "description": "Per-token adjustments applied to the provider’s token-selection logits.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "top_logprobs", "description": "Number of top token log probabilities requested from the provider.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "min_p", "description": "Minimum relative token probability used by supported sampling providers.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "top_a", "description": "Adaptive probability cutoff used by supported sampling providers.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "user", "description": "User identifier forwarded for provider-side request attribution.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "modalities", "description": "Output modalities (e.g., [TEXT, IMAGE])", "presence": "collection", "required": false, "requestRequired": false }, { "name": "plugins", "description": "Provider plugins requested for pre-processing or post-processing.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "GenerationContext", "title": "GenerationContext", "slug": "/api/models/generation-context", "description": "Snapshot of retrieval inputs, prompt provenance, and turn position that shaped a generated message.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "GenerationContext", "slug": "/api/models/generation-context" }, "usedBy": [ "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "memories", "description": "Memory records captured in the generation context.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "relations", "description": "Graph relationships captured in the generation context.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "memorySearch", "description": "Memory-query parameters and counts recorded for this generation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "turn", "description": "Turn position and limit within the generation run.", "presence": "message", "required": false, "requestRequired": false }, { "name": "languagePreference", "description": "Language preference associated with the generation context.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "resolvedSystemPrompt", "description": "System prompt selected for this generation after prompt precedence is resolved. This field is\nretained in the schema but is not populated; use resolved_prompt_hash for recorded prompt\nidentity.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "profileId", "description": "Agent profile that produced this message (\"\" if none active).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "model", "description": "Model actually used for this generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "promptSource", "description": "Which precedence tier supplied the prompt.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "baseConfig", "description": "Generation configuration resolved before per-call overrides and timeout adjustments, with\nsystem_prompt omitted. The active profile supplies the base when selected; otherwise the\nconversation default does. May be absent on older turns or when neither supplies a\nconfiguration.", "presence": "message", "required": false, "requestRequired": false }, { "name": "overrideConfig", "description": "Per-call generation configuration supplied before the override merge.", "presence": "message", "required": false, "requestRequired": false }, { "name": "profileVersion", "description": "Immutable version of the active agent profile used to render this turn’s prompt. Absent on\nolder turns and turns without a profile template.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "fragmentsVersion", "description": "Version of the prompt-fragment set used to render the profile prompt.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "promptVariables", "description": "Values bound to the prompt template for this generation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "profileRenderFailed", "description": "Whether rendering the profile prompt failed for this generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "resolvedPromptHash", "description": "SHA-256 hash, as 64 hexadecimal characters, of the resolved system prompt before the\ncurrent-time instruction is appended. Identifies prompt content only, excluding model and\nsampling parameters. Absent on older turns without prompt capture.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "resolvedUserContext", "description": "The [User Context] block as rendered into this turn's prompt: the user's\nname, locale, and location conditions (weather/AQI/UV/sun times). This is\nthe literal text the model received, not a reconstruction.\n\nEmpty when the user has no stored location, when enrichment degraded, or\non turns predating capture.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "resolvedMcpServers", "description": "The MCP server list that governed this turn — the tier actually resolved\n(conversation settings -> active profile -> per-turn override_mcp_servers),\nwhich is simultaneously the tool-discovery source and the CallTool\nallow/block basis.\n\nEmpty on turns predating capture and on threads with no MCP servers.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "GenerationContextInput", "title": "GenerationContext", "slug": "/api/models/generation-context-input", "description": "Snapshot of retrieval inputs, prompt provenance, and turn position that shaped a generated message.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "GenerationContext", "slug": "/api/models/generation-context" }, "usedBy": [ "conversations:appendMessage", "conversations:sendMessage", "conversations:sendMessageSync" ], "usedByRoots": [], "fields": [ { "name": "memories", "description": "Memory records captured in the generation context.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "relations", "description": "Graph relationships captured in the generation context.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "memorySearch", "description": "Memory-query parameters and counts recorded for this generation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "turn", "description": "Turn position and limit within the generation run.", "presence": "message", "required": false, "requestRequired": false }, { "name": "languagePreference", "description": "Language preference associated with the generation context.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "resolvedSystemPrompt", "description": "System prompt selected for this generation after prompt precedence is resolved. This field is\nretained in the schema but is not populated; use resolved_prompt_hash for recorded prompt\nidentity.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "profileId", "description": "Agent profile that produced this message (\"\" if none active).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "model", "description": "Model actually used for this generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "promptSource", "description": "Which precedence tier supplied the prompt.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "baseConfig", "description": "Generation configuration resolved before per-call overrides and timeout adjustments, with\nsystem_prompt omitted. The active profile supplies the base when selected; otherwise the\nconversation default does. May be absent on older turns or when neither supplies a\nconfiguration.", "presence": "message", "required": false, "requestRequired": false }, { "name": "overrideConfig", "description": "Per-call generation configuration supplied before the override merge.", "presence": "message", "required": false, "requestRequired": false }, { "name": "profileVersion", "description": "Immutable version of the active agent profile used to render this turn’s prompt. Absent on\nolder turns and turns without a profile template.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "fragmentsVersion", "description": "Version of the prompt-fragment set used to render the profile prompt.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "promptVariables", "description": "Values bound to the prompt template for this generation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "profileRenderFailed", "description": "Whether rendering the profile prompt failed for this generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "resolvedPromptHash", "description": "SHA-256 hash, as 64 hexadecimal characters, of the resolved system prompt before the\ncurrent-time instruction is appended. Identifies prompt content only, excluding model and\nsampling parameters. Absent on older turns without prompt capture.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "resolvedUserContext", "description": "The [User Context] block as rendered into this turn's prompt: the user's\nname, locale, and location conditions (weather/AQI/UV/sun times). This is\nthe literal text the model received, not a reconstruction.\n\nEmpty when the user has no stored location, when enrichment degraded, or\non turns predating capture.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "resolvedMcpServers", "description": "The MCP server list that governed this turn — the tier actually resolved\n(conversation settings -> active profile -> per-turn override_mcp_servers),\nwhich is simultaneously the tool-discovery source and the CallTool\nallow/block basis.\n\nEmpty on turns predating capture and on threads with no MCP servers.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "GenerationContextWebhook", "title": "GenerationContext", "slug": "/api/models/generation-context-webhook", "description": "Snapshot of retrieval inputs, prompt provenance, and turn position that shaped a generated message.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "GenerationContext", "slug": "/api/models/generation-context" }, "usedBy": [], "usedByRoots": [ "llm.message_published" ], "fields": [ { "name": "memories", "description": "Memory records captured in the generation context.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "relations", "description": "Graph relationships captured in the generation context.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "memory_search", "description": "Memory-query parameters and counts recorded for this generation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "turn", "description": "Turn position and limit within the generation run.", "presence": "message", "required": false, "requestRequired": false }, { "name": "language_preference", "description": "Language preference associated with the generation context.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "resolved_system_prompt", "description": "System prompt selected for this generation after prompt precedence is resolved. This field is\nretained in the schema but is not populated; use resolved_prompt_hash for recorded prompt\nidentity.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "profile_id", "description": "Agent profile that produced this message (\"\" if none active).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "model", "description": "Model actually used for this generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "prompt_source", "description": "Which precedence tier supplied the prompt.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "base_config", "description": "Generation configuration resolved before per-call overrides and timeout adjustments, with\nsystem_prompt omitted. The active profile supplies the base when selected; otherwise the\nconversation default does. May be absent on older turns or when neither supplies a\nconfiguration.", "presence": "message", "required": false, "requestRequired": false }, { "name": "override_config", "description": "Per-call generation configuration supplied before the override merge.", "presence": "message", "required": false, "requestRequired": false }, { "name": "profile_version", "description": "Immutable version of the active agent profile used to render this turn’s prompt. Absent on\nolder turns and turns without a profile template.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "fragments_version", "description": "Version of the prompt-fragment set used to render the profile prompt.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "prompt_variables", "description": "Values bound to the prompt template for this generation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "profile_render_failed", "description": "Whether rendering the profile prompt failed for this generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "resolved_prompt_hash", "description": "SHA-256 hash, as 64 hexadecimal characters, of the resolved system prompt before the\ncurrent-time instruction is appended. Identifies prompt content only, excluding model and\nsampling parameters. Absent on older turns without prompt capture.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "resolved_user_context", "description": "The [User Context] block as rendered into this turn's prompt: the user's\nname, locale, and location conditions (weather/AQI/UV/sun times). This is\nthe literal text the model received, not a reconstruction.\n\nEmpty when the user has no stored location, when enrichment degraded, or\non turns predating capture.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "resolved_mcp_servers", "description": "The MCP server list that governed this turn — the tier actually resolved\n(conversation settings -> active profile -> per-turn override_mcp_servers),\nwhich is simultaneously the tool-discovery source and the CallTool\nallow/block basis.\n\nEmpty on turns predating capture and on threads with no MCP servers.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "GetAgentProfileLibraryRequest", "title": "GetAgentProfileLibraryRequest", "slug": "/api/models/get-agent-profile-library-request", "description": "=== Library (metadata only) ===\nInputs for reading profile metadata available for discovery in the project library.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "GetAgentProfileLibraryRequest", "slug": "/api/models/get-agent-profile-library-request" }, "usedBy": [ "agent-profiles:getAgentProfileLibrary" ], "usedByRoots": [], "fields": [ { "name": "projectId", "description": "Identifier of the project associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "GetAgentProfileLibraryResponse", "title": "GetAgentProfileLibraryResponse", "slug": "/api/models/get-agent-profile-library-response", "description": "Result payload for reading profile metadata available for discovery in the project library.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "GetAgentProfileLibraryResponse", "slug": "/api/models/get-agent-profile-library-response" }, "usedBy": [ "agent-profiles:getAgentProfileLibrary" ], "usedByRoots": [], "fields": [ { "name": "library", "description": "Profile identity and selection metadata for the project.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "GetAgentProfileRequest", "title": "GetAgentProfileRequest", "slug": "/api/models/get-agent-profile-request", "description": "=== Get ===\nInputs for retrieving a selected agent profile and its configuration.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "GetAgentProfileRequest", "slug": "/api/models/get-agent-profile-request" }, "usedBy": [ "agent-profiles:getAgentProfile" ], "usedByRoots": [], "fields": [ { "name": "projectId", "description": "Identifier of the project associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "profileId", "description": "Identifier of the agent profile associated with the operation or generation.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "version", "description": "Immutable profile version to retrieve. Zero or omission selects the latest version.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "GetAgentProfileResponse", "title": "GetAgentProfileResponse", "slug": "/api/models/get-agent-profile-response", "description": "Result payload for retrieving a selected agent profile and its configuration.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "GetAgentProfileResponse", "slug": "/api/models/get-agent-profile-response" }, "usedBy": [ "agent-profiles:getAgentProfile" ], "usedByRoots": [], "fields": [ { "name": "profile", "description": "Agent profile returned by the operation.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "GetConversationStateRequest", "title": "GetConversationStateRequest", "slug": "/api/models/get-conversation-state-request", "description": "Input for reading conversation history and current generation state. Supply exactly one of\nconversation_key or external_id; either addresses the same stored conversation.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "GetConversationStateRequest", "slug": "/api/models/get-conversation-state-request" }, "usedBy": [ "conversations:getConversationState" ], "usedByRoots": [], "fields": [ { "name": "conversationKey", "description": "Generated conversation thread ID. Leave empty when addressing by external_id.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "externalId", "description": "Client-supplied conversation identifier from CreateThread, resolved within the caller’s\nownership scope.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "GetConversationStateResponse", "title": "GetConversationStateResponse", "slug": "/api/models/get-conversation-state-response", "description": "Result of reading conversation history and current generation state.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "GetConversationStateResponse", "slug": "/api/models/get-conversation-state-response" }, "usedBy": [ "conversations:getConversationState" ], "usedByRoots": [], "fields": [ { "name": "messageHistory", "description": "Messages recorded in the conversation history.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "defaultGenerationConfig", "description": "Base model and tool configuration for turns in this conversation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "settings", "description": "Conversation settings returned or supplied for this operation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "activeRunId", "description": "Run tracked by the conversation. Older threads can retain the last run ID after it ends;\ninspect active_running before interpreting this as a currently active run.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "activeRunning", "description": "Whether an active run was observed. False may be omitted from JSON; it does not establish\nthat an accepted or queued request completed.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "contextManagementSettings", "description": "Configuration governing the conversation’s context management and compaction.", "presence": "message", "required": false, "requestRequired": false }, { "name": "compactions", "description": "Recorded context compaction operations for the conversation.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "compactionInProgress", "description": "Whether a context compaction is currently in progress.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "totalUsage", "description": "Cumulative token usage and cost for the conversation. Absent when no usage has accrued.", "presence": "message", "required": false, "requestRequired": false }, { "name": "externalId", "description": "Echoed back so a caller addressing by conversation_key can reconcile its\nown identifier without a second lookup. Empty when none was supplied.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "conversationKey", "description": "System thread id keying the conversation, always populated. Mirror of\nexternal_id for the other direction: a caller addressing by external_id\nlearns the thread id without a second lookup.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "lastRunStatus", "description": "Terminal status of the last completed generation run. Unset until a run has ended.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "GetCustomMCPServerRequest", "title": "GetCustomMCPServerRequest", "slug": "/api/models/get-custom-mcp-server-request", "description": "Inputs for reading a tenant-owned MCP server registration.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "GetCustomMCPServerRequest", "slug": "/api/models/get-custom-mcp-server-request" }, "usedBy": [ "mcp-servers:getCustomMcpServer" ], "usedByRoots": [], "fields": [ { "name": "projectId", "description": "Identifier of the project associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "serverId", "description": "Identifier of the MCP server associated with the operation or tool.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "GetCustomMCPServerResponse", "title": "GetCustomMCPServerResponse", "slug": "/api/models/get-custom-mcp-server-response", "description": "Result payload for reading a tenant-owned MCP server registration.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "GetCustomMCPServerResponse", "slug": "/api/models/get-custom-mcp-server-response" }, "usedBy": [ "mcp-servers:getCustomMcpServer" ], "usedByRoots": [], "fields": [ { "name": "server", "description": "MCP server record supplied to or returned by the operation.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "GetDatasetRunRequest", "title": "GetDatasetRunRequest", "slug": "/api/models/get-dataset-run-request", "description": "Inputs for retrieving a named run against an evaluation dataset.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "GetDatasetRunRequest", "slug": "/api/models/get-dataset-run-request" }, "usedBy": [ "evals:getDatasetRun" ], "usedByRoots": [], "fields": [ { "name": "datasetName", "description": "Name used to address the evaluation dataset.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "runName", "description": "Name assigned to the evaluation dataset run.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "GetDatasetRunResponse", "title": "GetDatasetRunResponse", "slug": "/api/models/get-dataset-run-response", "description": "Result of retrieving a named run against an evaluation dataset.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "GetDatasetRunResponse", "slug": "/api/models/get-dataset-run-response" }, "usedBy": [ "evals:getDatasetRun" ], "usedByRoots": [], "fields": [ { "name": "run", "description": "Evaluation dataset run returned by the lookup.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "GetDeliveryStatusRequest", "title": "GetDeliveryStatusRequest", "slug": "/api/models/get-delivery-status-request", "description": "Inputs for reading provider activity for a notification transaction.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "GetDeliveryStatusRequest", "slug": "/api/models/get-delivery-status-request" }, "usedBy": [ "notifications:getDeliveryStatus" ], "usedByRoots": [], "fields": [ { "name": "transactionId", "description": "Identifier correlating a notification trigger with later status or cancellation requests.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "GetDeliveryStatusResponse", "title": "GetDeliveryStatusResponse", "slug": "/api/models/get-delivery-status-response", "description": "Result payload for reading provider activity for a notification transaction.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "GetDeliveryStatusResponse", "slug": "/api/models/get-delivery-status-response" }, "usedBy": [ "notifications:getDeliveryStatus" ], "usedByRoots": [], "fields": [ { "name": "activity", "description": "Notification activity entries returned by the provider.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "GetEndUserRequest", "title": "GetEndUserRequest", "slug": "/api/models/get-end-user-request", "description": "Inputs for retrieving an end-user identity and profile record. This schema declares no request\nfields.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "identity-access", "role": "operation-envelope", "title": "GetEndUserRequest", "slug": "/api/models/get-end-user-request" }, "usedBy": [ "end-users:getEndUser" ], "usedByRoots": [], "fields": [] }, { "schemaName": "GetEndUserResponse", "title": "GetEndUserResponse", "slug": "/api/models/get-end-user-response", "description": "Result of retrieving an end-user identity and profile record.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "identity-access", "role": "operation-envelope", "title": "GetEndUserResponse", "slug": "/api/models/get-end-user-response" }, "usedBy": [ "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "endUser", "description": "End-user identity and profile returned by the lookup. An empty message is returned when no\nmatching end user exists.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "GetFileMetadataRequest", "title": "GetFileMetadataRequest", "slug": "/api/models/get-file-metadata-request", "description": "Inputs for reading a stored file’s attributes without downloading its content.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "GetFileMetadataRequest", "slug": "/api/models/get-file-metadata-request" }, "usedBy": [ "storage:getFileMetadata" ], "usedByRoots": [], "fields": [ { "name": "fileId", "description": "Stable identifier of the stored file.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "GetFileMetadataResponse", "title": "GetFileMetadataResponse", "slug": "/api/models/get-file-metadata-response", "description": "Result payload for reading a stored file’s attributes without downloading its content.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "GetFileMetadataResponse", "slug": "/api/models/get-file-metadata-response" }, "usedBy": [ "storage:getFileMetadata" ], "usedByRoots": [], "fields": [ { "name": "file", "description": "Metadata for the file affected or retrieved by the operation.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "GetInboxFeedRequest", "title": "GetInboxFeedRequest", "slug": "/api/models/get-inbox-feed-request", "description": "Caller user_id derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "GetInboxFeedRequest", "slug": "/api/models/get-inbox-feed-request" }, "usedBy": [ "notifications:getInboxFeed" ], "usedByRoots": [], "fields": [ { "name": "page", "description": "Page number used by this listing operation, starting at 1.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pageSize", "description": "Number of entries requested per page. Zero or omission lets the server choose its default.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "filter", "description": "Selection criteria applied to the listing.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "GetInboxFeedResponse", "title": "GetInboxFeedResponse", "slug": "/api/models/get-inbox-feed-response", "description": "Result payload for paging through a subscriber’s inbox with read-state and category filters.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "GetInboxFeedResponse", "slug": "/api/models/get-inbox-feed-response" }, "usedBy": [ "notifications:getInboxFeed" ], "usedByRoots": [], "fields": [ { "name": "messages", "description": "Inbox messages returned after applying the selected query or state change.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "totalCount", "description": "Total number of matching entries reported by the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "page", "description": "Page number reported for the returned inbox feed.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pageSize", "description": "Page size reported for the returned inbox feed.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "hasMore", "description": "Whether the listing reports additional entries beyond this page.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "GetInboxSessionRequest", "title": "GetInboxSessionRequest", "slug": "/api/models/get-inbox-session-request", "description": "Caller user_id derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "GetInboxSessionRequest", "slug": "/api/models/get-inbox-session-request" }, "usedBy": [ "notifications:getInboxSession" ], "usedByRoots": [], "fields": [] }, { "schemaName": "GetInboxSessionResponse", "title": "GetInboxSessionResponse", "slug": "/api/models/get-inbox-session-response", "description": "Result payload for issuing connection details for a subscriber’s inbox session.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "GetInboxSessionResponse", "slug": "/api/models/get-inbox-session-response" }, "usedBy": [ "notifications:getInboxSession" ], "usedByRoots": [], "fields": [ { "name": "token", "description": "Token issued for the subscriber’s inbox session.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "socketUrl", "description": "WebSocket endpoint provided for the inbox session.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "expiresIn", "description": "Remaining lifetime of the inbox session token, in seconds.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "GetInboxUnseenCountRequest", "title": "GetInboxUnseenCountRequest", "slug": "/api/models/get-inbox-unseen-count-request", "description": "Caller user_id derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "GetInboxUnseenCountRequest", "slug": "/api/models/get-inbox-unseen-count-request" }, "usedBy": [ "notifications:getInboxUnseenCount" ], "usedByRoots": [], "fields": [ { "name": "feedIds", "description": "Feed identifiers used to select inbox messages.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "GetInboxUnseenCountResponse", "title": "GetInboxUnseenCountResponse", "slug": "/api/models/get-inbox-unseen-count-response", "description": "Result payload for counting unseen inbox notifications in selected feeds.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "GetInboxUnseenCountResponse", "slug": "/api/models/get-inbox-unseen-count-response" }, "usedBy": [ "notifications:getInboxUnseenCount" ], "usedByRoots": [], "fields": [ { "name": "unseenCount", "description": "Number of inbox messages reported unseen, capped at 10. Check has_more_unseen\nbefore treating this count as an exact total.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "unreadCount", "description": "Number of inbox messages reported unread, capped at 10. Check has_more_unread\nbefore treating this count as an exact total.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "hasMoreUnseen", "description": "Whether unseen messages exceed the capped count. When true, a badge can display \"9+\".", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "hasMoreUnread", "description": "Whether unread messages exceed the capped count. When true, a badge can display \"9+\".", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "GetJobRequest", "title": "GetJobRequest", "slug": "/api/models/get-job-request", "description": "Inputs for retrieving a scheduled job and its trigger settings.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "scheduling", "role": "operation-envelope", "title": "GetJobRequest", "slug": "/api/models/get-job-request" }, "usedBy": [ "scheduled-jobs:getJob" ], "usedByRoots": [], "fields": [ { "name": "scheduleId", "description": "Identifier of the scheduled job.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "externalId", "description": "Caller-assigned correlation identifier for the scheduled job.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "GetMemoryRequest", "title": "GetMemoryRequest", "slug": "/api/models/get-memory-request", "description": "Input for retrieving a memory record by its identifier.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "memory-knowledge", "role": "operation-envelope", "title": "GetMemoryRequest", "slug": "/api/models/get-memory-request" }, "usedBy": [ "conversations:getMemory" ], "usedByRoots": [], "fields": [ { "name": "memoryId", "description": "Memory ID to retrieve", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "GetMemoryResponse", "title": "GetMemoryResponse", "slug": "/api/models/get-memory-response", "description": "Result of retrieving a memory record by its identifier.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "memory-knowledge", "role": "operation-envelope", "title": "GetMemoryResponse", "slug": "/api/models/get-memory-response" }, "usedBy": [ "conversations:getMemory" ], "usedByRoots": [], "fields": [ { "name": "memory", "description": "The requested memory", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "GetNotificationActivityRequest", "title": "GetNotificationActivityRequest", "slug": "/api/models/get-notification-activity-request", "description": "Caller user_id derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "GetNotificationActivityRequest", "slug": "/api/models/get-notification-activity-request" }, "usedBy": [ "notifications:getNotificationActivity" ], "usedByRoots": [], "fields": [ { "name": "page", "description": "Page number used by this listing operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pageSize", "description": "Number of entries requested per page. Zero or omission lets the server choose its default.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "channels", "description": "Provider delivery-channel names used to restrict the query, such as \"in_app\" and\n\"push\". These are provider strings, not CHANNEL_* enum names.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "from", "description": "Lower time bound for the notification activity query.", "presence": "message", "required": false, "requestRequired": false }, { "name": "to", "description": "Upper time bound for the notification activity query.", "presence": "message", "required": false, "requestRequired": false }, { "name": "subscriberIds", "description": "When supplied, restrict notification activity to these subscriber identifiers.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "GetNotificationActivityResponse", "title": "GetNotificationActivityResponse", "slug": "/api/models/get-notification-activity-response", "description": "Result payload for querying delivery activity for a user across a selected time range.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "GetNotificationActivityResponse", "slug": "/api/models/get-notification-activity-response" }, "usedBy": [ "notifications:getNotificationActivity" ], "usedByRoots": [], "fields": [ { "name": "entries", "description": "Notification delivery activity entries returned for the selected query.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "hasMore", "description": "Whether the listing reports additional entries beyond this page.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "GetOverviewRequest", "title": "GetOverviewRequest", "slug": "/api/models/get-overview-request", "description": "Inputs for retrieving aggregate evaluation activity and score statistics.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "GetOverviewRequest", "slug": "/api/models/get-overview-request" }, "usedBy": [ "evals:getOverview" ], "usedByRoots": [], "fields": [ { "name": "fromTime", "description": "Beginning of the time range used to select evaluation records.", "presence": "message", "required": false, "requestRequired": false }, { "name": "toTime", "description": "End of the time range used to select evaluation records.", "presence": "message", "required": false, "requestRequired": false }, { "name": "profileId", "description": "Identifier of the agent profile associated with the operation or generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "environment", "description": "Environment label used to select evaluation records.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "GetOverviewResponse", "title": "GetOverviewResponse", "slug": "/api/models/get-overview-response", "description": "Result of retrieving aggregate evaluation activity and score statistics.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "GetOverviewResponse", "slug": "/api/models/get-overview-response" }, "usedBy": [ "evals:getOverview" ], "usedByRoots": [], "fields": [ { "name": "overview", "description": "Aggregate evaluation activity and score statistics for the selected scope.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "GetPendingChangesRequest", "title": "GetPendingChangesRequest", "slug": "/api/models/get-pending-changes-request", "description": "tenant_id derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "GetPendingChangesRequest", "slug": "/api/models/get-pending-changes-request" }, "usedBy": [ "notifications:getPendingChanges" ], "usedByRoots": [], "fields": [] }, { "schemaName": "GetPendingChangesResponse", "title": "GetPendingChangesResponse", "slug": "/api/models/get-pending-changes-response", "description": "Result payload for listing notification configuration changes awaiting promotion.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "GetPendingChangesResponse", "slug": "/api/models/get-pending-changes-response" }, "usedBy": [ "notifications:getPendingChanges" ], "usedByRoots": [], "fields": [ { "name": "changes", "description": "Pending notification configuration changes returned by the provider.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "totalCount", "description": "Total number of matching entries reported by the operation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "GetPreferencesRequest", "title": "GetPreferencesRequest", "slug": "/api/models/get-preferences-request", "description": "Caller user_id derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "GetPreferencesRequest", "slug": "/api/models/get-preferences-request" }, "usedBy": [ "notifications:getPreferences" ], "usedByRoots": [], "fields": [] }, { "schemaName": "GetPreferencesResponse", "title": "GetPreferencesResponse", "slug": "/api/models/get-preferences-response", "description": "Result payload for reading global and workflow-specific channel preferences for a subscriber.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "GetPreferencesResponse", "slug": "/api/models/get-preferences-response" }, "usedBy": [ "notifications:getPreferences" ], "usedByRoots": [], "fields": [ { "name": "global", "description": "Subscriber preferences that apply across notification workflows.", "presence": "message", "required": false, "requestRequired": false }, { "name": "workflows", "description": "Subscriber channel preferences for individual notification workflows.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "GetPromptFragmentRequest", "title": "GetPromptFragmentRequest", "slug": "/api/models/get-prompt-fragment-request", "description": "=== Get fragment ===\nInputs for retrieving a reusable prompt fragment by its identifier.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "GetPromptFragmentRequest", "slug": "/api/models/get-prompt-fragment-request" }, "usedBy": [ "agent-profiles:getPromptFragment" ], "usedByRoots": [], "fields": [ { "name": "projectId", "description": "Identifier of the project associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "fragmentId", "description": "Identifier of the reusable prompt fragment.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "GetPromptFragmentResponse", "title": "GetPromptFragmentResponse", "slug": "/api/models/get-prompt-fragment-response", "description": "Result payload for retrieving a reusable prompt fragment by its identifier.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "GetPromptFragmentResponse", "slug": "/api/models/get-prompt-fragment-response" }, "usedBy": [ "agent-profiles:getPromptFragment" ], "usedByRoots": [], "fields": [ { "name": "fragment", "description": "Reusable prompt fragment returned by the operation.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "GetPromptFragmentSetRequest", "title": "GetPromptFragmentSetRequest", "slug": "/api/models/get-prompt-fragment-set-request", "description": "Inputs for reading an immutable version of the project’s prompt-fragment set.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "GetPromptFragmentSetRequest", "slug": "/api/models/get-prompt-fragment-set-request" }, "usedBy": [ "agent-profiles:getPromptFragmentSet" ], "usedByRoots": [], "fields": [ { "name": "projectId", "description": "Identifier of the project associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "setVersion", "description": "Version identifying the immutable prompt-fragment set.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "GetPromptFragmentSetResponse", "title": "GetPromptFragmentSetResponse", "slug": "/api/models/get-prompt-fragment-set-response", "description": "Result payload for reading an immutable version of the project’s prompt-fragment set.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "GetPromptFragmentSetResponse", "slug": "/api/models/get-prompt-fragment-set-response" }, "usedBy": [ "agent-profiles:getPromptFragmentSet" ], "usedByRoots": [], "fields": [ { "name": "setVersion", "description": "Version identifying the immutable prompt-fragment set.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "fragments", "description": "Ordered by fragment_id.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "GetProvidersRequest", "title": "GetProvidersRequest", "slug": "/api/models/get-providers-request", "description": "tenant_id and environment derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "GetProvidersRequest", "slug": "/api/models/get-providers-request" }, "usedBy": [ "notifications:getProviders" ], "usedByRoots": [], "fields": [] }, { "schemaName": "GetProvidersResponse", "title": "GetProvidersResponse", "slug": "/api/models/get-providers-response", "description": "Result payload for reading the configured notification delivery providers.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "GetProvidersResponse", "slug": "/api/models/get-providers-response" }, "usedBy": [ "notifications:getProviders" ], "usedByRoots": [], "fields": [ { "name": "providers", "description": "Configured notification delivery providers.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "GetRegisteredChannelsRequest", "title": "GetRegisteredChannelsRequest", "slug": "/api/models/get-registered-channels-request", "description": "Caller user_id derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "GetRegisteredChannelsRequest", "slug": "/api/models/get-registered-channels-request" }, "usedBy": [ "notifications:getRegisteredChannels" ], "usedByRoots": [], "fields": [] }, { "schemaName": "GetRegisteredChannelsResponse", "title": "GetRegisteredChannelsResponse", "slug": "/api/models/get-registered-channels-response", "description": "Result payload for reading the notification channels with registered delivery credentials.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "GetRegisteredChannelsResponse", "slug": "/api/models/get-registered-channels-response" }, "usedBy": [ "notifications:getRegisteredChannels" ], "usedByRoots": [], "fields": [ { "name": "channels", "description": "Registration status and credential counts for the subscriber’s delivery channels.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "GetSecretMetadataRequest", "title": "GetSecretMetadataRequest", "slug": "/api/models/get-secret-metadata-request", "description": "Selects a project secret whose metadata is returned without its value.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "secrets", "role": "operation-envelope", "title": "GetSecretMetadataRequest", "slug": "/api/models/get-secret-metadata-request" }, "usedBy": [ "secrets:getSecretMetadata" ], "usedByRoots": [], "fields": [ { "name": "name", "description": "Name identifying the secret within its project.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "GetSecretMetadataResponse", "title": "GetSecretMetadataResponse", "slug": "/api/models/get-secret-metadata-response", "description": "Result of retrieving metadata for a project secret without its secret value.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "secrets", "role": "operation-envelope", "title": "GetSecretMetadataResponse", "slug": "/api/models/get-secret-metadata-response" }, "usedBy": [ "secrets:getSecretMetadata" ], "usedByRoots": [], "fields": [ { "name": "metadata", "description": "Stored secret metadata; the secret value is not returned.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "GetSessionRequest", "title": "GetSessionRequest", "slug": "/api/models/get-session-request", "description": "Inputs for retrieving an evaluation session and its associated traces.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "GetSessionRequest", "slug": "/api/models/get-session-request" }, "usedBy": [ "evals:getSession" ], "usedByRoots": [], "fields": [ { "name": "sessionId", "description": "Identifier of the evaluation session grouping related traces.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "GetSessionResponse", "title": "GetSessionResponse", "slug": "/api/models/get-session-response", "description": "Result of retrieving an evaluation session and its associated traces.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "GetSessionResponse", "slug": "/api/models/get-session-response" }, "usedBy": [ "evals:getSession" ], "usedByRoots": [], "fields": [ { "name": "session", "description": "Evaluation session details returned by the lookup.", "presence": "message", "required": false, "requestRequired": false }, { "name": "contentRedacted", "description": "Whether sensitive evaluation content has been removed from the returned view.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "GetStateRequest", "title": "GetStateRequest", "slug": "/api/models/get-state-request", "description": "Inputs for reading the file and folder registry state in object storage.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "GetStateRequest", "slug": "/api/models/get-state-request" }, "usedBy": [ "storage:getState" ], "usedByRoots": [], "fields": [] }, { "schemaName": "GetStateResponse", "title": "GetStateResponse", "slug": "/api/models/get-state-response", "description": "Result payload for reading the file and folder registry state in object storage.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "GetStateResponse", "slug": "/api/models/get-state-response" }, "usedBy": [ "storage:getState" ], "usedByRoots": [], "fields": [ { "name": "state", "description": "State snapshot returned by the actor or workflow.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "GetStorageQuotaRequest", "title": "GetStorageQuotaRequest", "slug": "/api/models/get-storage-quota-request", "description": "Inputs for reading the user’s allocated capacity and current storage usage.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "GetStorageQuotaRequest", "slug": "/api/models/get-storage-quota-request" }, "usedBy": [ "storage:getStorageQuota" ], "usedByRoots": [], "fields": [] }, { "schemaName": "GetStorageQuotaResponse", "title": "GetStorageQuotaResponse", "slug": "/api/models/get-storage-quota-response", "description": "Result payload for reading the user’s allocated capacity and current storage usage.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "GetStorageQuotaResponse", "slug": "/api/models/get-storage-quota-response" }, "usedBy": [ "storage:getStorageQuota" ], "usedByRoots": [], "fields": [ { "name": "usedBytes", "description": "Storage capacity currently attributed to the user, in bytes.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "quotaBytes", "description": "Storage capacity allocated to the user, in bytes.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "fileCount", "description": "Number of files represented by this folder or quota snapshot.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "folderCount", "description": "Number of folders represented by the quota snapshot.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "usagePercentage", "description": "Storage usage expressed as a percentage of the quota.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "GetSubscriberRequest", "title": "GetSubscriberRequest", "slug": "/api/models/get-subscriber-request", "description": "Caller user_id derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "GetSubscriberRequest", "slug": "/api/models/get-subscriber-request" }, "usedBy": [ "notifications:getSubscriber" ], "usedByRoots": [], "fields": [] }, { "schemaName": "GetSubscriberResponse", "title": "GetSubscriberResponse", "slug": "/api/models/get-subscriber-response", "description": "Result payload for retrieving a notification subscriber’s contact and custom attributes.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "GetSubscriberResponse", "slug": "/api/models/get-subscriber-response" }, "usedBy": [ "notifications:getSubscriber" ], "usedByRoots": [], "fields": [ { "name": "subscriberId", "description": "Identifier of the notification subscriber.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "data", "description": "Contact, locale, and custom attributes returned for the subscriber.", "presence": "message", "required": false, "requestRequired": false }, { "name": "channels", "description": "Registration status and credential counts for the subscriber’s delivery channels.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time when this record was created.", "presence": "message", "required": false, "requestRequired": false }, { "name": "updatedAt", "description": "Time when this record was last updated.", "presence": "message", "required": false, "requestRequired": false }, { "name": "globalPreferences", "description": "Subscriber preferences that apply across notification workflows.", "presence": "message", "required": false, "requestRequired": false }, { "name": "workflowPreferences", "description": "Subscriber preferences scoped to individual notification workflows.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "GetToolCallRequest", "title": "GetToolCallRequest", "slug": "/api/models/get-tool-call-request", "description": "Input for locating a tool call within conversation history.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "GetToolCallRequest", "slug": "/api/models/get-tool-call-request" }, "usedBy": [ "conversations:getToolCall" ], "usedByRoots": [], "fields": [ { "name": "conversationKey", "description": "Identifier of the conversation thread.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "toolCallId", "description": "Identifier of the tool call to retrieve.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "GetToolCallResponse", "title": "GetToolCallResponse", "slug": "/api/models/get-tool-call-response", "description": "Result of locating a tool call within conversation history.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "GetToolCallResponse", "slug": "/api/models/get-tool-call-response" }, "usedBy": [ "conversations:getToolCall" ], "usedByRoots": [], "fields": [ { "name": "messageSequence", "description": "Sequence number of the conversation message containing the tool call.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "messageId", "description": "Identifier of the conversation message containing the tool call.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "toolCall", "description": "Tool call retrieved from the identified conversation message.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "GetTraceRequest", "title": "GetTraceRequest", "slug": "/api/models/get-trace-request", "description": "Inputs for retrieving an evaluation trace with its recorded generation details. Supply exactly\none address: trace_id, or both conversation_id and source_user_message_id.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "GetTraceRequest", "slug": "/api/models/get-trace-request" }, "usedBy": [ "evals:getTrace" ], "usedByRoots": [], "fields": [ { "name": "traceId", "description": "Identifier of the evaluation trace.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "conversationId", "description": "Identifier of the conversation associated with the evaluation record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sourceUserMessageId", "description": "Identifier of the user message that started the evaluated turn, not the assistant reply's\nmessage identifier. Supply it together with conversation_id when addressing by turn.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "GetTraceResponse", "title": "GetTraceResponse", "slug": "/api/models/get-trace-response", "description": "Result of retrieving an evaluation trace with its recorded generation details.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "GetTraceResponse", "slug": "/api/models/get-trace-response" }, "usedBy": [ "evals:getTrace" ], "usedByRoots": [], "fields": [ { "name": "trace", "description": "Evaluation trace details returned by the lookup.", "presence": "message", "required": false, "requestRequired": false }, { "name": "contentRedacted", "description": "Whether returned trace content is redacted. Redaction occurs before the trace is recorded, so\nits text is not a faithful copy of the conversation store.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "GetWorkflowRequest", "title": "GetWorkflowRequest", "slug": "/api/models/get-workflow-request", "description": "tenant_id and environment derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "GetWorkflowRequest", "slug": "/api/models/get-workflow-request" }, "usedBy": [ "notifications:getWorkflow" ], "usedByRoots": [], "fields": [ { "name": "workflowId", "description": "Identifier of the notification workflow to execute or configure.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "triggerIdentifier", "description": "Trigger identifier used to address a notification workflow.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "GetWorkflowResponse", "title": "GetWorkflowResponse", "slug": "/api/models/get-workflow-response", "description": "Result payload for retrieving a notification workflow by identifier or trigger name.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "GetWorkflowResponse", "slug": "/api/models/get-workflow-response" }, "usedBy": [ "notifications:getWorkflow" ], "usedByRoots": [], "fields": [ { "name": "workflow", "description": "Notification workflow definition supplied to or returned by the provider.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "GlobalPreferences", "title": "GlobalPreferences", "slug": "/api/models/global-preferences", "description": "Subscriber's global (all-workflow) notification preferences.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "domain-model", "title": "GlobalPreferences", "slug": "/api/models/global-preferences" }, "usedBy": [ "notifications:getPreferences", "notifications:getSubscriber" ], "usedByRoots": [], "fields": [ { "name": "enabled", "description": "Master switch — false disables all non-critical notifications.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "channels", "description": "Channel switches recorded for these subscriber preferences.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "HelpLink", "title": "HelpLink", "slug": "/api/models/help-link", "description": "A help link for error resolution.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "HelpLink", "slug": "/api/models/help-link" }, "usedBy": [ "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "url", "description": "URL to documentation or resolution guide.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Description of what the link provides.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "HelpLinkInput", "title": "HelpLink", "slug": "/api/models/help-link-input", "description": "A help link for error resolution.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "HelpLink", "slug": "/api/models/help-link" }, "usedBy": [ "conversations:submitClientToolResults", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "url", "description": "URL to documentation or resolution guide.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Description of what the link provides.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "HelpLinkWebhook", "title": "HelpLink", "slug": "/api/models/help-link-webhook", "description": "A help link for error resolution.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "HelpLink", "slug": "/api/models/help-link" }, "usedBy": [], "usedByRoots": [ "llm.generation_completed" ], "fields": [ { "name": "url", "description": "URL to documentation or resolution guide.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Description of what the link provides.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "HeyGenConfig", "title": "HeyGenConfig", "slug": "/api/models/hey-gen-config", "description": "HeyGen avatar/video configuration", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "voice-media", "role": "domain-model", "title": "HeyGenConfig", "slug": "/api/models/hey-gen-config" }, "usedBy": [ "conversations:createDailySession" ], "usedByRoots": [], "fields": [ { "name": "enabled", "description": "Whether this configuration is enabled.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "avatarId", "description": "Identifier of the HeyGen avatar used for the session.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "version", "description": "Version of the resource represented by this message.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "quality", "description": "Video-quality setting requested for the HeyGen avatar.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "videoEncoding", "description": "Video codec requested for the HeyGen avatar stream.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "voice", "description": "Voice configuration used by the HeyGen avatar.", "presence": "message", "required": false, "requestRequired": false }, { "name": "knowledgeId", "description": "Identifier of the HeyGen knowledge resource associated with the avatar.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "knowledgeBase", "description": "Knowledge text supplied to the HeyGen avatar configuration.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "disableIdleTimeout", "description": "Whether HeyGen’s session idle timeout is disabled.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "activityIdleTimeout", "description": "HeyGen activity idle timeout, in seconds.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "HeyGenElevenLabsSettings", "title": "HeyGenElevenLabsSettings", "slug": "/api/models/hey-gen-eleven-labs-settings", "description": "ElevenLabs settings used within HeyGen voice configuration", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "voice-media", "role": "domain-model", "title": "HeyGenElevenLabsSettings", "slug": "/api/models/hey-gen-eleven-labs-settings" }, "usedBy": [ "conversations:createDailySession" ], "usedByRoots": [], "fields": [ { "name": "stability", "description": "ElevenLabs voice-stability setting passed through HeyGen.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "similarityBoost", "description": "ElevenLabs voice-similarity setting passed through HeyGen.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "modelId", "description": "ElevenLabs model identifier used for HeyGen voice synthesis.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "style", "description": "Integer style code.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "useSpeakerBoost", "description": "Whether ElevenLabs speaker boost is requested for the HeyGen voice.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "HeyGenVoiceSettings", "title": "HeyGenVoiceSettings", "slug": "/api/models/hey-gen-voice-settings", "description": "HeyGen voice settings", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "voice-media", "role": "domain-model", "title": "HeyGenVoiceSettings", "slug": "/api/models/hey-gen-voice-settings" }, "usedBy": [ "conversations:createDailySession" ], "usedByRoots": [], "fields": [ { "name": "voiceId", "description": "Provider voice identifier used for speech synthesis.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "rate", "description": "Speech-rate setting passed to the HeyGen voice provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "emotion", "description": "Emotion setting passed to HeyGen voice synthesis.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "elevenlabsSettings", "description": "ElevenLabs synthesis settings associated with the HeyGen voice.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ImportAgentProfilesRequest", "title": "ImportAgentProfilesRequest", "slug": "/api/models/import-agent-profiles-request", "description": "Inputs for converting a source prompt library into project profiles. Every shared block\nreferenced by an include must be supplied in fragments so the importer can resolve the library.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "ImportAgentProfilesRequest", "slug": "/api/models/import-agent-profiles-request" }, "usedBy": [ "agent-profiles:importAgentProfiles" ], "usedByRoots": [], "fields": [ { "name": "projectId", "description": "Identifier of the project associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "templates", "description": "Source persona templates to convert into conversational agent profiles.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "fragments", "description": "Shared @include blocks.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "variableTypes", "description": "Optional variable type hints that override types inferred from template usage.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "overwrite", "description": "Update existing profiles and fragments instead of failing ALREADY_EXISTS. An existing\nprofile takes the imported prompt, variable specs, name, when_to_use, keywords and the\ngeneration settings the template sets; its model, MCP servers, description, enabled state\nand disable_default_tools are kept.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "emitFragments", "description": "When false, resolve source includes inline into each profile’s system prompt. When true, emit\nsupplied shared blocks as prompt fragments and reference them through template actions; every\nreferenced shared block must be supplied.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ImportAgentProfilesResponse", "title": "ImportAgentProfilesResponse", "slug": "/api/models/import-agent-profiles-response", "description": "Result payload for converting and importing source prompt templates into project agent profiles.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "ImportAgentProfilesResponse", "slug": "/api/models/import-agent-profiles-response" }, "usedBy": [ "agent-profiles:importAgentProfiles" ], "usedByRoots": [], "fields": [ { "name": "profiles", "description": "Converted + stored (echo).", "presence": "collection", "required": false, "requestRequired": false }, { "name": "fragments", "description": "Reusable prompt fragments returned by the operation.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "InboxFeedFilter", "title": "InboxFeedFilter", "slug": "/api/models/inbox-feed-filter", "description": "Read-state, category, tag, and archive criteria selecting inbox entries.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "domain-model", "title": "InboxFeedFilter", "slug": "/api/models/inbox-feed-filter" }, "usedBy": [ "notifications:getInboxFeed" ], "usedByRoots": [], "fields": [ { "name": "unseenOnly", "description": "Whether the inbox filter selects only unseen messages.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "unreadOnly", "description": "Whether the inbox filter selects only unread messages.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "feedIds", "description": "Filter by Novu feed identifiers.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "categories", "description": "Categories used to select inbox messages.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "tags", "description": "Filter by workflow tags (OR logic per Novu semantics).", "presence": "collection", "required": false, "requestRequired": false }, { "name": "archived", "description": "When true, include archived messages. False or omission selects the live inbox\nand excludes archived messages.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "InboxMessage", "title": "InboxMessage", "slug": "/api/models/inbox-message", "description": "Notification content and interaction state displayed in a subscriber’s inbox.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "domain-model", "title": "InboxMessage", "slug": "/api/models/inbox-message" }, "usedBy": [ "notifications:getInboxFeed" ], "usedByRoots": [], "fields": [ { "name": "messageId", "description": "Identifier of the message represented by this inbox entry.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "notificationId", "description": "Identifier of the notification represented by this inbox entry.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "title", "description": "Title displayed for the inbox notification.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "body", "description": "Body text of the inbox message.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "data", "description": "Additional key-value attributes attached to the inbox notification.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "deepLink", "description": "Application deep link associated with the inbox message.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "imageUrl", "description": "Image URL associated with the inbox message.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "status", "description": "Read, seen, or archived state recorded for the inbox message.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "category", "description": "Category assigned to the inbox message or workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time when this record was created.", "presence": "message", "required": false, "requestRequired": false }, { "name": "seenAt", "description": "Time when the inbox message was marked seen.", "presence": "message", "required": false, "requestRequired": false }, { "name": "readAt", "description": "Time when the inbox message was marked read.", "presence": "message", "required": false, "requestRequired": false }, { "name": "actions", "description": "Interactive actions attached to the inbox message.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "tags", "description": "Workflow tags for tab assignment (OR-filtered in feed).", "presence": "collection", "required": false, "requestRequired": false }, { "name": "archived", "description": "Whether this inbox notification is archived.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "archivedAt", "description": "Time when the inbox message was archived.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "InboxMessageAction", "title": "InboxMessageAction", "slug": "/api/models/inbox-message-action", "description": "Interactive action attached to an inbox message, including completion state.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "domain-model", "title": "InboxMessageAction", "slug": "/api/models/inbox-message-action" }, "usedBy": [ "notifications:getInboxFeed" ], "usedByRoots": [], "fields": [ { "name": "actionId", "description": "Identifier of an action attached to the inbox message.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "label", "description": "Display label for the inbox action.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "url", "description": "Destination URL opened by this inbox action.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "isPrimary", "description": "Whether the inbox action is designated as the primary action.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "completed", "description": "Whether the user has completed this action via CompleteInboxAction.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "completedAt", "description": "Time when this inbox action was marked complete.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "InboxMessageSummary", "title": "InboxMessageSummary", "slug": "/api/models/inbox-message-summary", "description": "Summary of an inbox message after a mark operation.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "domain-model", "title": "InboxMessageSummary", "slug": "/api/models/inbox-message-summary" }, "usedBy": [ "notifications:markInboxMessageAs" ], "usedByRoots": [], "fields": [ { "name": "messageId", "description": "Identifier of the inbox message represented by this summary.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "channel", "description": "Delivery channel reported for this inbox message.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "read", "description": "Whether the inbox message has been marked read.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "seen", "description": "Whether the inbox message has been marked seen.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "archived", "description": "Whether this inbox message is archived.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "content", "description": "Rendered notification content.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "subject", "description": "Subject text for the notification message.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "status", "description": "Status reported by the notification provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time when this record was created.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "lastReadDate", "description": "Most recent timestamp recorded for reading inbox messages.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "lastSeenDate", "description": "Most recent timestamp recorded for seeing inbox messages.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "LatencyPercentileRow", "title": "LatencyPercentileRow", "slug": "/api/models/latency-percentile-row", "description": "Latency percentiles aggregated for one evaluation trace name.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "LatencyPercentileRow", "slug": "/api/models/latency-percentile-row" }, "usedBy": [ "evals:getOverview" ], "usedByRoots": [], "fields": [ { "name": "traceName", "description": "Display name used to group or identify the evaluation trace.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "p50", "description": "50th-percentile latency reported for the trace group.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "p90", "description": "90th-percentile latency reported for the trace group.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "p95", "description": "95th-percentile latency reported for the trace group.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "p99", "description": "99th-percentile latency reported for the trace group.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListAgentProfilesRequest", "title": "ListAgentProfilesRequest", "slug": "/api/models/list-agent-profiles-request", "description": "=== List ===\nInputs for paging through agent profiles available in the project library.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "ListAgentProfilesRequest", "slug": "/api/models/list-agent-profiles-request" }, "usedBy": [ "agent-profiles:listAgentProfiles" ], "usedByRoots": [], "fields": [ { "name": "projectId", "description": "Identifier of the project associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "page", "description": "Page number used by this listing operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pageSize", "description": "Number of entries requested per page. Zero or omission lets the server choose its default.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "includeDisabled", "description": "Include disabled profiles in addition to the enabled selection; otherwise only enabled\nprofiles are returned.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListAgentProfilesResponse", "title": "ListAgentProfilesResponse", "slug": "/api/models/list-agent-profiles-response", "description": "Result payload for paging through agent profiles available in the project library.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "ListAgentProfilesResponse", "slug": "/api/models/list-agent-profiles-response" }, "usedBy": [ "agent-profiles:listAgentProfiles" ], "usedByRoots": [], "fields": [ { "name": "profiles", "description": "Agent profiles returned by the listing or import.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "totalCount", "description": "Total number of matching entries reported by the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "hasMore", "description": "Whether the listing reports additional entries beyond this page.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListAgentProfileVersionsRequest", "title": "ListAgentProfileVersionsRequest", "slug": "/api/models/list-agent-profile-versions-request", "description": "Inputs for listing immutable revisions of an agent profile.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "ListAgentProfileVersionsRequest", "slug": "/api/models/list-agent-profile-versions-request" }, "usedBy": [ "agent-profiles:listAgentProfileVersions" ], "usedByRoots": [], "fields": [ { "name": "projectId", "description": "Identifier of the project associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "profileId", "description": "Identifier of the agent profile associated with the operation or generation.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "ListAgentProfileVersionsResponse", "title": "ListAgentProfileVersionsResponse", "slug": "/api/models/list-agent-profile-versions-response", "description": "Result payload for listing immutable revisions of an agent profile.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "ListAgentProfileVersionsResponse", "slug": "/api/models/list-agent-profile-versions-response" }, "usedBy": [ "agent-profiles:listAgentProfileVersions" ], "usedByRoots": [], "fields": [ { "name": "versions", "description": "Descending (newest first). Empty when the profile has never existed.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "ListAnnotationQueueItemsRequest", "title": "ListAnnotationQueueItemsRequest", "slug": "/api/models/list-annotation-queue-items-request", "description": "Inputs for listing evaluation objects in an annotation queue.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "ListAnnotationQueueItemsRequest", "slug": "/api/models/list-annotation-queue-items-request" }, "usedBy": [ "evals:listAnnotationQueueItems" ], "usedByRoots": [], "fields": [ { "name": "queueId", "description": "Identifier of the evaluation annotation queue.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "page", "description": "Page number requested from the backing service.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pageSize", "description": "Requested maximum number of entries in a result page.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "status", "description": "Annotation state used to restrict the queue listing. Omit to include both pending and\ncompleted items.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListAnnotationQueueItemsResponse", "title": "ListAnnotationQueueItemsResponse", "slug": "/api/models/list-annotation-queue-items-response", "description": "Result of listing evaluation objects in an annotation queue.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "ListAnnotationQueueItemsResponse", "slug": "/api/models/list-annotation-queue-items-response" }, "usedBy": [ "evals:listAnnotationQueueItems" ], "usedByRoots": [], "fields": [ { "name": "items", "description": "Evaluation annotation queue items in this page.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "page", "description": "Page number, page size, and result totals returned by the evaluation provider.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ListAnnotationQueuesRequest", "title": "ListAnnotationQueuesRequest", "slug": "/api/models/list-annotation-queues-request", "description": "Inputs for listing queues of evaluation objects awaiting annotation.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "ListAnnotationQueuesRequest", "slug": "/api/models/list-annotation-queues-request" }, "usedBy": [ "evals:listAnnotationQueues" ], "usedByRoots": [], "fields": [ { "name": "page", "description": "Page number requested from the backing service.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pageSize", "description": "Requested maximum number of entries in a result page.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListAnnotationQueuesResponse", "title": "ListAnnotationQueuesResponse", "slug": "/api/models/list-annotation-queues-response", "description": "Result of listing queues of evaluation objects awaiting annotation.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "ListAnnotationQueuesResponse", "slug": "/api/models/list-annotation-queues-response" }, "usedBy": [ "evals:listAnnotationQueues" ], "usedByRoots": [], "fields": [ { "name": "queues", "description": "Evaluation annotation queues included in this result page.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "page", "description": "Page number, page size, and result totals returned by the evaluation provider.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ListCommentsRequest", "title": "ListCommentsRequest", "slug": "/api/models/list-comments-request", "description": "Inputs for listing comments attached to evaluation objects.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "ListCommentsRequest", "slug": "/api/models/list-comments-request" }, "usedBy": [ "evals:listComments" ], "usedByRoots": [], "fields": [ { "name": "objectType", "description": "Kind of evaluation object to which the comment belongs.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "objectId", "description": "Identifier of the evaluation object to which the comment belongs.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "page", "description": "Page number requested from the backing service.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pageSize", "description": "Requested maximum number of entries in a result page.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListCommentsResponse", "title": "ListCommentsResponse", "slug": "/api/models/list-comments-response", "description": "Result of listing comments attached to evaluation objects.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "ListCommentsResponse", "slug": "/api/models/list-comments-response" }, "usedBy": [ "evals:listComments" ], "usedByRoots": [], "fields": [ { "name": "comments", "description": "Evaluation comments included in this result page.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "page", "description": "Page number, page size, and result totals returned by the evaluation provider.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ListCustomMCPServersRequest", "title": "ListCustomMCPServersRequest", "slug": "/api/models/list-custom-mcp-servers-request", "description": "Inputs for listing MCP server registrations belonging to the tenant.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "ListCustomMCPServersRequest", "slug": "/api/models/list-custom-mcp-servers-request" }, "usedBy": [ "mcp-servers:listCustomMcpServers" ], "usedByRoots": [], "fields": [ { "name": "projectId", "description": "Identifier of the project associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "authSecretNameFilter", "description": "When set, return only MCP servers whose auth_secret_ref names this secret.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "includeDisabled", "description": "Default false → only enabled servers.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListCustomMCPServersResponse", "title": "ListCustomMCPServersResponse", "slug": "/api/models/list-custom-mcp-servers-response", "description": "Result payload for listing MCP server registrations belonging to the tenant.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "ListCustomMCPServersResponse", "slug": "/api/models/list-custom-mcp-servers-response" }, "usedBy": [ "mcp-servers:listCustomMcpServers" ], "usedByRoots": [], "fields": [ { "name": "servers", "description": "MCP server configurations or statuses returned by the operation.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "total", "description": "Total number of entries reported by the listing.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListDatasetItemsRequest", "title": "ListDatasetItemsRequest", "slug": "/api/models/list-dataset-items-request", "description": "Inputs for listing input and expected-output pairs in an evaluation dataset.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "ListDatasetItemsRequest", "slug": "/api/models/list-dataset-items-request" }, "usedBy": [ "evals:listDatasetItems" ], "usedByRoots": [], "fields": [ { "name": "datasetId", "description": "Identifier of the evaluation dataset.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "datasetName", "description": "Name used to address the evaluation dataset.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "page", "description": "Page number requested from the backing service.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pageSize", "description": "Requested maximum number of entries in a result page.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sourceTraceId", "description": "Identifier of the trace used as the source for the dataset item.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "onlyMissingExpectedOutput", "description": "Backs the curation list: items still lacking ground truth.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListDatasetItemsResponse", "title": "ListDatasetItemsResponse", "slug": "/api/models/list-dataset-items-response", "description": "Result of listing input and expected-output pairs in an evaluation dataset.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "ListDatasetItemsResponse", "slug": "/api/models/list-dataset-items-response" }, "usedBy": [ "evals:listDatasetItems" ], "usedByRoots": [], "fields": [ { "name": "items", "description": "Evaluation dataset items in this page.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "page", "description": "Page number, page size, and result totals returned by the evaluation provider.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ListDatasetRunsRequest", "title": "ListDatasetRunsRequest", "slug": "/api/models/list-dataset-runs-request", "description": "Inputs for listing recorded runs against an evaluation dataset.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "ListDatasetRunsRequest", "slug": "/api/models/list-dataset-runs-request" }, "usedBy": [ "evals:listDatasetRuns" ], "usedByRoots": [], "fields": [ { "name": "datasetName", "description": "Name used to address the evaluation dataset.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "pageSize", "description": "Requested maximum number of entries in a result page.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "cursor", "description": "Opaque cursor from the previous response’s cursor_page.next_cursor. Leave empty for the first\npage.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListDatasetRunsResponse", "title": "ListDatasetRunsResponse", "slug": "/api/models/list-dataset-runs-response", "description": "Result of listing recorded runs against an evaluation dataset.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "ListDatasetRunsResponse", "slug": "/api/models/list-dataset-runs-response" }, "usedBy": [ "evals:listDatasetRuns" ], "usedByRoots": [], "fields": [ { "name": "runs", "description": "Evaluation dataset runs included in this result page.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "cursorPage", "description": "Cursor pagination details accompanying this result page.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ListDatasetsRequest", "title": "ListDatasetsRequest", "slug": "/api/models/list-datasets-request", "description": "Inputs for listing evaluation datasets.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "ListDatasetsRequest", "slug": "/api/models/list-datasets-request" }, "usedBy": [ "evals:listDatasets" ], "usedByRoots": [], "fields": [ { "name": "page", "description": "Page number requested from the backing service.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pageSize", "description": "Requested maximum number of entries in a result page.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListDatasetsResponse", "title": "ListDatasetsResponse", "slug": "/api/models/list-datasets-response", "description": "Result of listing evaluation datasets.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "ListDatasetsResponse", "slug": "/api/models/list-datasets-response" }, "usedBy": [ "evals:listDatasets" ], "usedByRoots": [], "fields": [ { "name": "datasets", "description": "Evaluation datasets included in this result page.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "page", "description": "Page number, page size, and result totals returned by the evaluation provider.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ListExecutionsRequest", "title": "ListExecutionsRequest", "slug": "/api/models/list-executions-request", "description": "Inputs for listing the execution history of a scheduled job.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "scheduling", "role": "operation-envelope", "title": "ListExecutionsRequest", "slug": "/api/models/list-executions-request" }, "usedBy": [ "scheduled-jobs:listExecutions" ], "usedByRoots": [], "fields": [ { "name": "scheduleId", "description": "Identifier of the scheduled job.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "pageSize", "description": "Number of entries requested per page. Zero or omission lets the server choose its default.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pageToken", "description": "Continuation token from a previous response; leave empty to start the listing.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "statusFilter", "description": "Execution status used to restrict the execution history.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListExecutionsResponse", "title": "ListExecutionsResponse", "slug": "/api/models/list-executions-response", "description": "Result of listing the execution history of a scheduled job.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "scheduling", "role": "operation-envelope", "title": "ListExecutionsResponse", "slug": "/api/models/list-executions-response" }, "usedBy": [ "scheduled-jobs:listExecutions" ], "usedByRoots": [], "fields": [ { "name": "executions", "description": "Scheduled execution records included in this result page.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "nextPageToken", "description": "Opaque cursor token for the next page. Empty when no further pages exist.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListFilesRequest", "title": "ListFilesRequest", "slug": "/api/models/list-files-request", "description": "Inputs for paging through files and subfolders with metadata filters.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "ListFilesRequest", "slug": "/api/models/list-files-request" }, "usedBy": [ "storage:listFiles" ], "usedByRoots": [], "fields": [ { "name": "folderPath", "description": "Path of the folder within the user’s storage namespace.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "recursive", "description": "Whether the operation includes descendant folders and their contents.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pageSize", "description": "Maximum number of entries requested per page.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pageToken", "description": "Continuation token from a preceding page of results.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "filter", "description": "Selection criteria applied to the listing.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ListFilesResponse", "title": "ListFilesResponse", "slug": "/api/models/list-files-response", "description": "Result payload for paging through files and subfolders with metadata filters.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "ListFilesResponse", "slug": "/api/models/list-files-response" }, "usedBy": [ "storage:listFiles" ], "usedByRoots": [], "fields": [ { "name": "files", "description": "File metadata records returned by the listing or search.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "folders", "description": "Folder metadata records returned by the listing.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "nextPageToken", "description": "Continuation token returned for retrieving the next page.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "totalCount", "description": "Total number of matching entries reported by the operation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListJobsRequest", "title": "ListJobsRequest", "slug": "/api/models/list-jobs-request", "description": "Inputs for listing scheduled jobs and their trigger settings.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "scheduling", "role": "operation-envelope", "title": "ListJobsRequest", "slug": "/api/models/list-jobs-request" }, "usedBy": [ "scheduled-jobs:listJobs" ], "usedByRoots": [], "fields": [ { "name": "pageSize", "description": "Number of entries requested per page. Zero or omission lets the server choose its default.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pageToken", "description": "Continuation token from a previous response; leave empty to start the listing.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "stateFilter", "description": "Schedule lifecycle status used to restrict the job listing.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "targetKindFilter", "description": "Target kind used to restrict the scheduled job listing.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListJobsResponse", "title": "ListJobsResponse", "slug": "/api/models/list-jobs-response", "description": "Result of listing scheduled jobs and their trigger settings.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "scheduling", "role": "operation-envelope", "title": "ListJobsResponse", "slug": "/api/models/list-jobs-response" }, "usedBy": [ "scheduled-jobs:listJobs" ], "usedByRoots": [], "fields": [ { "name": "schedules", "description": "Scheduled jobs included in this result page.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "nextPageToken", "description": "Opaque cursor token for the next page. Empty when no further pages exist.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "totalCount", "description": "Total number of records reported for this listing.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListMemoriesRequest", "title": "ListMemoriesRequest", "slug": "/api/models/list-memories-request", "description": "Input for listing memory records in the caller’s scope.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "memory-knowledge", "role": "operation-envelope", "title": "ListMemoriesRequest", "slug": "/api/models/list-memories-request" }, "usedBy": [ "conversations:listMemories" ], "usedByRoots": [], "fields": [ { "name": "agentId", "description": "Filter by agent/conversation ID (optional)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "limit", "description": "Maximum number of memories to return. Supply explicitly; omission is rejected.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "ListMemoriesResponse", "title": "ListMemoriesResponse", "slug": "/api/models/list-memories-response", "description": "Result of listing memory records in the caller’s scope.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "memory-knowledge", "role": "operation-envelope", "title": "ListMemoriesResponse", "slug": "/api/models/list-memories-response" }, "usedBy": [ "conversations:listMemories" ], "usedByRoots": [], "fields": [ { "name": "memories", "description": "List of user's memories", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "ListObservationsRequest", "title": "ListObservationsRequest", "slug": "/api/models/list-observations-request", "description": "Inputs for listing observations recorded within evaluation traces.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "ListObservationsRequest", "slug": "/api/models/list-observations-request" }, "usedBy": [ "evals:listObservations" ], "usedByRoots": [], "fields": [ { "name": "pageSize", "description": "Requested maximum number of entries in a result page.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "traceId", "description": "Identifier of the evaluation trace.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "type", "description": "Observation type used to restrict the evaluation query.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "level", "description": "Severity level used to restrict evaluation observations or traces.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "parentObservationId", "description": "Identifier of the parent observation used to select child observations.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "userId", "description": "Identifier of the end user associated with this operation or record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Name used to restrict the evaluation record listing.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "environment", "description": "Environment label used to select evaluation records.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "fromTime", "description": "Beginning of the time range used to select evaluation records.", "presence": "message", "required": false, "requestRequired": false }, { "name": "toTime", "description": "End of the time range used to select evaluation records.", "presence": "message", "required": false, "requestRequired": false }, { "name": "filters", "description": "Structured filters applied to the evaluation record query.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "cursor", "description": "Opaque cursor from the previous response’s cursor_page.next_cursor. Leave empty for the first\npage.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListObservationsResponse", "title": "ListObservationsResponse", "slug": "/api/models/list-observations-response", "description": "Result of listing observations recorded within evaluation traces.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "ListObservationsResponse", "slug": "/api/models/list-observations-response" }, "usedBy": [ "evals:listObservations" ], "usedByRoots": [], "fields": [ { "name": "observations", "description": "Evaluation observations included in this result page.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "contentRedacted", "description": "Whether sensitive evaluation content has been removed from the returned view.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "cursorPage", "description": "Cursor pagination details accompanying this result page.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ListPendingApprovalsRequest", "title": "ListPendingApprovalsRequest", "slug": "/api/models/list-pending-approvals-request", "description": "Input for reading tool calls awaiting approval.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "ListPendingApprovalsRequest", "slug": "/api/models/list-pending-approvals-request" }, "usedBy": [ "conversations:listPendingApprovals" ], "usedByRoots": [], "fields": [ { "name": "conversationKey", "description": "Identifier of the conversation thread.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "ListPendingApprovalsResponse", "title": "ListPendingApprovalsResponse", "slug": "/api/models/list-pending-approvals-response", "description": "Result of reading tool calls awaiting approval.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "ListPendingApprovalsResponse", "slug": "/api/models/list-pending-approvals-response" }, "usedBy": [ "conversations:listPendingApprovals" ], "usedByRoots": [], "fields": [ { "name": "toolCalls", "description": "Tool calls waiting for a caller approval decision.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "ListPendingClientToolsRequest", "title": "ListPendingClientToolsRequest", "slug": "/api/models/list-pending-client-tools-request", "description": "Input for reading client-side tool calls awaiting execution.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "ListPendingClientToolsRequest", "slug": "/api/models/list-pending-client-tools-request" }, "usedBy": [ "conversations:listPendingClientTools" ], "usedByRoots": [], "fields": [ { "name": "conversationKey", "description": "Identifier of the conversation thread.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "namePrefixFilters", "description": "When supplied, include only pending client tools whose names match one of these prefixes.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "ListPendingClientToolsResponse", "title": "ListPendingClientToolsResponse", "slug": "/api/models/list-pending-client-tools-response", "description": "Result of reading client-side tool calls awaiting execution.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "ListPendingClientToolsResponse", "slug": "/api/models/list-pending-client-tools-response" }, "usedBy": [ "conversations:listPendingClientTools" ], "usedByRoots": [], "fields": [ { "name": "messageSequences", "description": "Inlined fields aligned by index across the three arrays.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "messageIds", "description": "Message identifiers aligned with the returned tool calls.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "toolCalls", "description": "Client-side tool calls aligned with the returned message identifiers and sequences.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "ListPromptFragmentsRequest", "title": "ListPromptFragmentsRequest", "slug": "/api/models/list-prompt-fragments-request", "description": "=== List fragments ===\nInputs for paging through reusable prompt fragments in the project library.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "ListPromptFragmentsRequest", "slug": "/api/models/list-prompt-fragments-request" }, "usedBy": [ "agent-profiles:listPromptFragments" ], "usedByRoots": [], "fields": [ { "name": "projectId", "description": "Identifier of the project associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "page", "description": "Page number used by this listing operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pageSize", "description": "Number of entries requested per page. Zero or omission lets the server choose its default.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListPromptFragmentsResponse", "title": "ListPromptFragmentsResponse", "slug": "/api/models/list-prompt-fragments-response", "description": "Result payload for paging through reusable prompt fragments in the project library.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "ListPromptFragmentsResponse", "slug": "/api/models/list-prompt-fragments-response" }, "usedBy": [ "agent-profiles:listPromptFragments" ], "usedByRoots": [], "fields": [ { "name": "fragments", "description": "Reusable prompt fragments returned by the operation.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "totalCount", "description": "Total number of matching entries reported by the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "hasMore", "description": "Whether the listing reports additional entries beyond this page.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "setVersion", "description": "Current version of the project’s prompt-fragment set. Zero means no fragments have been\nwritten.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListScoreConfigsRequest", "title": "ListScoreConfigsRequest", "slug": "/api/models/list-score-configs-request", "description": "Inputs for listing definitions and allowed values of evaluation scores.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "ListScoreConfigsRequest", "slug": "/api/models/list-score-configs-request" }, "usedBy": [ "evals:listScoreConfigs" ], "usedByRoots": [], "fields": [ { "name": "page", "description": "Page number requested from the backing service.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pageSize", "description": "Requested maximum number of entries in a result page.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "includeArchived", "description": "Whether archived score configurations are included in the listing. They are excluded when\nthis field is omitted or false.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListScoreConfigsResponse", "title": "ListScoreConfigsResponse", "slug": "/api/models/list-score-configs-response", "description": "Result of listing definitions and allowed values of evaluation scores.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "ListScoreConfigsResponse", "slug": "/api/models/list-score-configs-response" }, "usedBy": [ "evals:listScoreConfigs" ], "usedByRoots": [], "fields": [ { "name": "configs", "description": "Evaluation score configurations included in this result page.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "page", "description": "Page number, page size, and result totals returned by the evaluation provider.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ListScoresRequest", "title": "ListScoresRequest", "slug": "/api/models/list-scores-request", "description": "Inputs for listing scores attached to evaluation objects.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "ListScoresRequest", "slug": "/api/models/list-scores-request" }, "usedBy": [ "evals:listScores" ], "usedByRoots": [], "fields": [ { "name": "pageSize", "description": "Requested maximum number of entries in a result page.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "targetType", "description": "Kind of evaluation object targeted by the score or annotation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "targetId", "description": "Identifier of the evaluation object targeted by the score or annotation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Name used to restrict the evaluation record listing.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "source", "description": "Origin of the evaluation scores selected by this query.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "fromTime", "description": "Beginning of the time range used to select evaluation records.", "presence": "message", "required": false, "requestRequired": false }, { "name": "toTime", "description": "End of the time range used to select evaluation records.", "presence": "message", "required": false, "requestRequired": false }, { "name": "userId", "description": "Identifier of the end user associated with this operation or record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "profileId", "description": "Identifier of the agent profile associated with the operation or generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "minValue", "description": "Lower numeric bound for the score range.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxValue", "description": "Upper numeric bound for the score range.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "conversationId", "description": "Identifier of the conversation associated with the evaluation record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sessionId", "description": "Identifier of the evaluation session grouping related traces.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "dataType", "description": "Value type used to interpret the evaluation score.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "traceId", "description": "Identifier of the evaluation trace.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "filters", "description": "Structured filters applied to the evaluation record query.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "cursor", "description": "Opaque cursor from the previous response’s cursor_page.next_cursor. Leave empty for the first\npage.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListScoresResponse", "title": "ListScoresResponse", "slug": "/api/models/list-scores-response", "description": "Result of listing scores attached to evaluation objects.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "ListScoresResponse", "slug": "/api/models/list-scores-response" }, "usedBy": [ "evals:listScores" ], "usedByRoots": [], "fields": [ { "name": "scores", "description": "Evaluation scores included in this result page.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "filterNarrowed", "description": "Whether additional filtering removed rows from this page. A narrowed page can contain fewer\nthan page_size results while cursor_page.next_cursor still identifies another page.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "cursorPage", "description": "Cursor pagination details accompanying this result page.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ListSecretsRequest", "title": "ListSecretsRequest", "slug": "/api/models/list-secrets-request", "description": "Pagination settings for listing secret metadata within the current project.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "secrets", "role": "operation-envelope", "title": "ListSecretsRequest", "slug": "/api/models/list-secrets-request" }, "usedBy": [ "secrets:listSecrets" ], "usedByRoots": [], "fields": [ { "name": "page", "description": "Page number requested from the backing service.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pageSize", "description": "Number of secret metadata entries requested per page. Zero or omission lets the server choose\nthe page size.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListSecretsResponse", "title": "ListSecretsResponse", "slug": "/api/models/list-secrets-response", "description": "Page of metadata for project secrets, without their values.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "secrets", "role": "operation-envelope", "title": "ListSecretsResponse", "slug": "/api/models/list-secrets-response" }, "usedBy": [ "secrets:listSecrets" ], "usedByRoots": [], "fields": [ { "name": "secrets", "description": "Secret metadata records returned by the listing; secret values are excluded.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "total", "description": "Total number of records reported for this listing.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListSessionsRequest", "title": "ListSessionsRequest", "slug": "/api/models/list-sessions-request", "description": "Inputs for listing evaluation sessions grouping related traces.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "ListSessionsRequest", "slug": "/api/models/list-sessions-request" }, "usedBy": [ "evals:listSessions" ], "usedByRoots": [], "fields": [ { "name": "pageSize", "description": "Requested maximum number of entries in a result page.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "fromTime", "description": "Beginning of the time range used to select evaluation records.", "presence": "message", "required": false, "requestRequired": false }, { "name": "toTime", "description": "End of the time range used to select evaluation records.", "presence": "message", "required": false, "requestRequired": false }, { "name": "environment", "description": "Environment label used to select evaluation records.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "userId", "description": "Identifier of the end user associated with this operation or record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "filters", "description": "Structured filters applied to the evaluation record query.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "cursor", "description": "Opaque cursor from the previous response’s cursor_page.next_cursor. Leave empty for the first\npage.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListSessionsResponse", "title": "ListSessionsResponse", "slug": "/api/models/list-sessions-response", "description": "Result of listing evaluation sessions grouping related traces.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "ListSessionsResponse", "slug": "/api/models/list-sessions-response" }, "usedBy": [ "evals:listSessions" ], "usedByRoots": [], "fields": [ { "name": "sessions", "description": "Evaluation session summaries included in this result page.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "cursorPage", "description": "Cursor pagination details accompanying this result page.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ListSubscribersRequest", "title": "ListSubscribersRequest", "slug": "/api/models/list-subscribers-request", "description": "tenant_id and environment derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "ListSubscribersRequest", "slug": "/api/models/list-subscribers-request" }, "usedBy": [ "notifications:listSubscribers" ], "usedByRoots": [], "fields": [ { "name": "page", "description": "Page number used by this listing operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pageSize", "description": "Number of entries requested per page. Zero or omission lets the server choose its default.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListSubscribersResponse", "title": "ListSubscribersResponse", "slug": "/api/models/list-subscribers-response", "description": "Result payload for paging through notification subscribers and their presence summaries.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "ListSubscribersResponse", "slug": "/api/models/list-subscribers-response" }, "usedBy": [ "notifications:listSubscribers" ], "usedByRoots": [], "fields": [ { "name": "subscribers", "description": "Subscriber records returned by the listing.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "totalCount", "description": "Total number of matching entries reported by the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "hasMore", "description": "Whether the listing reports additional entries beyond this page.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListThreadsRequest", "title": "ListThreadsRequest", "slug": "/api/models/list-threads-request", "description": "Input for listing conversation threads visible to the caller.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "ListThreadsRequest", "slug": "/api/models/list-threads-request" }, "usedBy": [ "conversations:listThreads" ], "usedByRoots": [], "fields": [ { "name": "limit", "description": "Max rows per page. 0 -> service default (50). Values >200 are clamped\nto 200 downstream. Negative values are rejected by proto validation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pageToken", "description": "Opaque base64 cursor returned by prior call. Empty for first page.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListThreadsResponse", "title": "ListThreadsResponse", "slug": "/api/models/list-threads-response", "description": "Result of listing conversation threads visible to the caller.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "ListThreadsResponse", "slug": "/api/models/list-threads-response" }, "usedBy": [ "conversations:listThreads" ], "usedByRoots": [], "fields": [ { "name": "threads", "description": "Conversation summaries returned for this page. An absent JSON list means this page is empty.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "nextPageToken", "description": "Opaque continuation token for requesting the next page.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListTopicSubscribersRequest", "title": "ListTopicSubscribersRequest", "slug": "/api/models/list-topic-subscribers-request", "description": "Inputs for paging through members of a selected notification topic.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "ListTopicSubscribersRequest", "slug": "/api/models/list-topic-subscribers-request" }, "usedBy": [ "notifications:listTopicSubscribers" ], "usedByRoots": [], "fields": [ { "name": "topicKey", "description": "Caller-facing key identifying a notification topic.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "page", "description": "Page number used by this listing operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pageSize", "description": "Number of entries requested per page. Zero or omission lets the server choose its default.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListTopicSubscribersResponse", "title": "ListTopicSubscribersResponse", "slug": "/api/models/list-topic-subscribers-response", "description": "Result payload for paging through members of a selected notification topic.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "ListTopicSubscribersResponse", "slug": "/api/models/list-topic-subscribers-response" }, "usedBy": [ "notifications:listTopicSubscribers" ], "usedByRoots": [], "fields": [ { "name": "userIds", "description": "Identifiers of the users selected by the operation.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "totalCount", "description": "Total number of matching entries reported by the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "hasMore", "description": "Whether the listing reports additional entries beyond this page.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListTracesRequest", "title": "ListTracesRequest", "slug": "/api/models/list-traces-request", "description": "Inputs for listing evaluation trace records.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "ListTracesRequest", "slug": "/api/models/list-traces-request" }, "usedBy": [ "evals:listTraces" ], "usedByRoots": [], "fields": [ { "name": "pageSize", "description": "Requested maximum number of entries in a result page.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "conversationId", "description": "Identifier of the conversation associated with the evaluation record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "profileId", "description": "Identifier of the agent profile associated with the operation or generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "userId", "description": "Identifier of the end user associated with this operation or record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sessionId", "description": "Identifier of the evaluation session grouping related traces.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Name used to restrict the evaluation record listing.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "environment", "description": "Environment label used to select evaluation records.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "version", "description": "Version label used to select evaluation records.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "release", "description": "Application release label attached to evaluation records.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "tags", "description": "Tags used to classify or filter the evaluation record.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "fromTime", "description": "Beginning of the time range used to select evaluation records.", "presence": "message", "required": false, "requestRequired": false }, { "name": "toTime", "description": "End of the time range used to select evaluation records.", "presence": "message", "required": false, "requestRequired": false }, { "name": "level", "description": "Severity level used to restrict evaluation observations or traces.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "orderBy", "description": "Ordering expression passed to the evaluation record query.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "filters", "description": "Structured filters applied to the evaluation record query.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "searchQuery", "description": "Text searched within evaluation trace records.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "searchType", "description": "Search mode applied to the evaluation trace query.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "cursor", "description": "Opaque cursor from the previous response’s cursor_page.next_cursor. Leave empty for the first\npage.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListTracesResponse", "title": "ListTracesResponse", "slug": "/api/models/list-traces-response", "description": "Result of listing evaluation trace records.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "ListTracesResponse", "slug": "/api/models/list-traces-response" }, "usedBy": [ "evals:listTraces" ], "usedByRoots": [], "fields": [ { "name": "traces", "description": "Evaluation trace summaries included in this result page.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "contentRedacted", "description": "Whether returned trace content is redacted. Redaction occurs before the trace is recorded, so\nits text is not a faithful copy of the conversation store.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "cursorPage", "description": "Cursor pagination details accompanying this result page.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ListWebhookDeliveriesRequest", "title": "ListWebhookDeliveriesRequest", "slug": "/api/models/list-webhook-deliveries-request", "description": "Inputs for querying delivery attempts visible through the tenant webhook gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "webhooks", "role": "operation-envelope", "title": "ListWebhookDeliveriesRequest", "slug": "/api/models/list-webhook-deliveries-request" }, "usedBy": [ "webhooks:listWebhookDeliveries" ], "usedByRoots": [], "fields": [ { "name": "endpointId", "description": "Optional: filter by endpoint.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "subscriptionId", "description": "Optional: filter by subscription.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "eventId", "description": "Optional: filter by event.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "status", "description": "Delivery status used to restrict the tenant webhook-delivery query.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAfter", "description": "Optional: filter by creation time.", "presence": "message", "required": false, "requestRequired": false }, { "name": "createdBefore", "description": "Optional: filter by creation time.", "presence": "message", "required": false, "requestRequired": false }, { "name": "page", "description": "Page number used by this listing operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "perPage", "description": "Number of entries requested per page.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListWebhookDeliveriesResponse", "title": "ListWebhookDeliveriesResponse", "slug": "/api/models/list-webhook-deliveries-response", "description": "Result payload for querying delivery attempts visible through the tenant webhook gateway.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "webhooks", "role": "operation-envelope", "title": "ListWebhookDeliveriesResponse", "slug": "/api/models/list-webhook-deliveries-response" }, "usedBy": [ "webhooks:listWebhookDeliveries" ], "usedByRoots": [], "fields": [ { "name": "deliveries", "description": "Webhook delivery records matching the listing query.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "pagination", "description": "Page position and total counts reported with the listing.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ListWebhookEndpointsRequest", "title": "ListWebhookEndpointsRequest", "slug": "/api/models/list-webhook-endpoints-request", "description": "Inputs for listing webhook destinations registered for the tenant.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "webhooks", "role": "operation-envelope", "title": "ListWebhookEndpointsRequest", "slug": "/api/models/list-webhook-endpoints-request" }, "usedBy": [ "webhooks:listWebhookEndpoints" ], "usedByRoots": [], "fields": [ { "name": "page", "description": "Page number used by this listing operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "perPage", "description": "Number of entries requested per page.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListWebhookEndpointsResponse", "title": "ListWebhookEndpointsResponse", "slug": "/api/models/list-webhook-endpoints-response", "description": "Result payload for listing webhook destinations registered for the tenant.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "webhooks", "role": "operation-envelope", "title": "ListWebhookEndpointsResponse", "slug": "/api/models/list-webhook-endpoints-response" }, "usedBy": [ "webhooks:listWebhookEndpoints" ], "usedByRoots": [], "fields": [ { "name": "endpoints", "description": "Webhook endpoints returned by the listing.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "pagination", "description": "Page position and total counts reported with the listing.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ListWebhookSubscriptionsRequest", "title": "ListWebhookSubscriptionsRequest", "slug": "/api/models/list-webhook-subscriptions-request", "description": "Inputs for listing event subscriptions registered for tenant webhook destinations.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "webhooks", "role": "operation-envelope", "title": "ListWebhookSubscriptionsRequest", "slug": "/api/models/list-webhook-subscriptions-request" }, "usedBy": [ "webhooks:listWebhookSubscriptions" ], "usedByRoots": [], "fields": [ { "name": "endpointId", "description": "Optional: filter by endpoint.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "page", "description": "Page number used by this listing operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "perPage", "description": "Number of entries requested per page.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListWebhookSubscriptionsResponse", "title": "ListWebhookSubscriptionsResponse", "slug": "/api/models/list-webhook-subscriptions-response", "description": "Result payload for listing event subscriptions registered for tenant webhook destinations.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "webhooks", "role": "operation-envelope", "title": "ListWebhookSubscriptionsResponse", "slug": "/api/models/list-webhook-subscriptions-response" }, "usedBy": [ "webhooks:listWebhookSubscriptions" ], "usedByRoots": [], "fields": [ { "name": "subscriptions", "description": "Webhook subscriptions returned by the listing.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "pagination", "description": "Page position and total counts reported with the listing.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ListWorkflowsRequest", "title": "ListWorkflowsRequest", "slug": "/api/models/list-workflows-request", "description": "tenant_id and environment derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "ListWorkflowsRequest", "slug": "/api/models/list-workflows-request" }, "usedBy": [ "notifications:listWorkflows" ], "usedByRoots": [], "fields": [ { "name": "page", "description": "Page number used by this listing operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pageSize", "description": "Number of entries requested per page. Zero or omission lets the server choose its default.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ListWorkflowsResponse", "title": "ListWorkflowsResponse", "slug": "/api/models/list-workflows-response", "description": "Result payload for paging through available notification workflow definitions.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "ListWorkflowsResponse", "slug": "/api/models/list-workflows-response" }, "usedBy": [ "notifications:listWorkflows" ], "usedByRoots": [], "fields": [ { "name": "workflows", "description": "Notification workflow definitions returned by the listing.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "totalCount", "description": "Total number of matching entries reported by the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "hasMore", "description": "Whether the listing reports additional entries beyond this page.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "LLMGenerationCompletedEventWebhook", "title": "LLMGenerationCompletedEvent", "slug": "/api/models/llm-generation-completed-event-webhook", "description": "Event emitted when a generation run reaches a terminal state. The event context identifies the\nassociated conversation.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "webhooks", "role": "domain-model", "title": "LLMGenerationCompletedEvent", "slug": "/api/models/llm-generation-completed-event" }, "usedBy": [], "usedByRoots": [ "llm.generation_completed" ], "fields": [ { "name": "event_context", "description": "Event provenance and routing metadata associated with the emitted event.", "presence": "message", "required": false, "requestRequired": false }, { "name": "run_id", "description": "Unique identifier for the workflow run", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "status", "description": "Terminal status of the run", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "loop_count", "description": "Number of agent loops/steps executed", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "duration_ms", "description": "End-to-end run duration in milliseconds", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "usage", "description": "Optional usage accounting for the run", "presence": "message", "required": false, "requestRequired": false }, { "name": "error", "description": "Structured error for FAILED/TIMED_OUT/CANCELED runs.", "presence": "message", "required": false, "requestRequired": false }, { "name": "usage_by_model", "description": "Per-model breakdown of the same usage `usage` aggregates. Additive: `usage`\nstays the run-level total so existing consumers are unaffected, while\nbilling keys its charges on model. Empty when the producer predates it.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "turn_key", "description": "Identifies the conversation turn this run served: the message_id of the\nopening user message, resolved once at run start and stamped on every\nmessage the run emits as Message.source_user_message_id.\n\nEmpty when the producer predates this field, or when the turn is\nunresolvable — never guess one, an empty key means \"no turn attribution\".", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "LLMGenerationStartedEventWebhook", "title": "LLMGenerationStartedEvent", "slug": "/api/models/llm-generation-started-event-webhook", "description": "Event emitted when a generation run starts. The event context identifies the associated\nconversation.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "webhooks", "role": "domain-model", "title": "LLMGenerationStartedEvent", "slug": "/api/models/llm-generation-started-event" }, "usedBy": [], "usedByRoots": [ "llm.generation_started" ], "fields": [ { "name": "event_context", "description": "Event provenance and routing metadata associated with the emitted event.", "presence": "message", "required": false, "requestRequired": false }, { "name": "run_id", "description": "Unique identifier for the workflow run", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "config", "description": "Optional snapshot of generation configuration used for this run", "presence": "message", "required": false, "requestRequired": false }, { "name": "starting_sequence", "description": "Conversation sequence number at the moment the run started (if known)", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "LLMMessagePublishedEventWebhook", "title": "LLMMessagePublishedEvent", "slug": "/api/models/llm-message-published-event-webhook", "description": "Domain event published when a new assistant/tool message is produced.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "webhooks", "role": "domain-model", "title": "LLMMessagePublishedEvent", "slug": "/api/models/llm-message-published-event" }, "usedBy": [], "usedByRoots": [ "llm.message_published" ], "fields": [ { "name": "event_context", "description": "Event provenance and routing metadata associated with the emitted event.", "presence": "message", "required": false, "requestRequired": false }, { "name": "message", "description": "The generated assistant/tool message", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "Location", "title": "Location", "slug": "/api/models/location", "description": "End-user coordinates and associated location metadata.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "identity-access", "role": "domain-model", "title": "Location", "slug": "/api/models/location" }, "usedBy": [ "end-users:getEndUser", "end-users:updateLocation" ], "usedByRoots": [], "fields": [ { "name": "latitude", "description": "Latitude of the location in decimal degrees.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "longitude", "description": "Longitude of the location in decimal degrees.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "city", "description": "City associated with the location; currently left empty because reverse geocoding is not\nimplemented.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "timezone", "description": "IANA time zone associated with the record or schedule. IANA, derived from coordinates\nserver-side.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "updatedAt", "description": "Time this record was most recently updated.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "MarkAllInboxMessagesAsRequest", "title": "MarkAllInboxMessagesAsRequest", "slug": "/api/models/mark-all-inbox-messages-as-request", "description": "Caller user_id derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "MarkAllInboxMessagesAsRequest", "slug": "/api/models/mark-all-inbox-messages-as-request" }, "usedBy": [ "notifications:markAllInboxMessagesAs" ], "usedByRoots": [], "fields": [ { "name": "markAs", "description": "Inbox state to apply to the selected message or messages.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "feedIds", "description": "Feed identifiers used to select inbox messages.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "MarkAllInboxMessagesAsResponse", "title": "MarkAllInboxMessagesAsResponse", "slug": "/api/models/mark-all-inbox-messages-as-response", "description": "Result payload for changing the read or seen state of selected inbox messages.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "MarkAllInboxMessagesAsResponse", "slug": "/api/models/mark-all-inbox-messages-as-response" }, "usedBy": [ "notifications:markAllInboxMessagesAs" ], "usedByRoots": [], "fields": [ { "name": "updatedCount", "description": "Number of preference entries reported updated.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MarkInboxMessageAsRequest", "title": "MarkInboxMessageAsRequest", "slug": "/api/models/mark-inbox-message-as-request", "description": "Caller user_id derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "MarkInboxMessageAsRequest", "slug": "/api/models/mark-inbox-message-as-request" }, "usedBy": [ "notifications:markInboxMessageAs" ], "usedByRoots": [], "fields": [ { "name": "messageId", "description": "Identifier of the inbox message to read or modify.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "markAs", "description": "Inbox state to apply to the selected message or messages.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MarkInboxMessageAsResponse", "title": "MarkInboxMessageAsResponse", "slug": "/api/models/mark-inbox-message-as-response", "description": "Result payload for changing an inbox message’s read or seen state.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "MarkInboxMessageAsResponse", "slug": "/api/models/mark-inbox-message-as-response" }, "usedBy": [ "notifications:markInboxMessageAs" ], "usedByRoots": [], "fields": [ { "name": "messages", "description": "Inbox messages returned after applying the selected query or state change.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "MCPCallToolRequest", "title": "MCPCallToolRequest", "slug": "/api/models/mcp-call-tool-request", "description": "Input for executing a tool through an MCP server.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "MCPCallToolRequest", "slug": "/api/models/mcp-call-tool-request" }, "usedBy": [ "conversations:mcpCallTool" ], "usedByRoots": [], "fields": [ { "name": "toolCall", "description": "Prefer ToolCall with server_id/name and arguments_json (object)", "presence": "message", "required": false, "requestRequired": false }, { "name": "requestId", "description": "Correlation identifier for the MCP tool execution request.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sessionId", "description": "Session routing hint for the MCP operation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MCPCallToolResponse", "title": "MCPCallToolResponse", "slug": "/api/models/mcp-call-tool-response", "description": "Result of executing a tool through an MCP server.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "MCPCallToolResponse", "slug": "/api/models/mcp-call-tool-response" }, "usedBy": [ "conversations:mcpCallTool" ], "usedByRoots": [], "fields": [ { "name": "requestId", "description": "Correlation identifier for the MCP tool execution request.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "toolCall", "description": "Tool call with its arguments, execution state, and available result.", "presence": "message", "required": false, "requestRequired": false }, { "name": "executionTimeMs", "description": "Reported duration of MCP tool execution, in milliseconds.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MCPGetPromptRequest", "title": "MCPGetPromptRequest", "slug": "/api/models/mcp-get-prompt-request", "description": "Input for retrieving an MCP prompt template by name.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "MCPGetPromptRequest", "slug": "/api/models/mcp-get-prompt-request" }, "usedBy": [ "conversations:mcpGetPrompt" ], "usedByRoots": [], "fields": [ { "name": "serverId", "description": "Identifier of the MCP server to query.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Name of the MCP prompt template to retrieve.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sessionId", "description": "Session routing hint for the MCP operation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MCPGetPromptResponse", "title": "MCPGetPromptResponse", "slug": "/api/models/mcp-get-prompt-response", "description": "Result of retrieving an MCP prompt template by name.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "MCPGetPromptResponse", "slug": "/api/models/mcp-get-prompt-response" }, "usedBy": [ "conversations:mcpGetPrompt" ], "usedByRoots": [], "fields": [ { "name": "prompt", "description": "Prompt template returned by the MCP server.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "MCPGetServerInfoRequest", "title": "MCPGetServerInfoRequest", "slug": "/api/models/mcp-get-server-info-request", "description": "Input for reading connection and capability information for an MCP server.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "MCPGetServerInfoRequest", "slug": "/api/models/mcp-get-server-info-request" }, "usedBy": [ "conversations:mcpGetServerInfo" ], "usedByRoots": [], "fields": [ { "name": "serverId", "description": "Identifier of the MCP server to query.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MCPGetServerInfoResponse", "title": "MCPGetServerInfoResponse", "slug": "/api/models/mcp-get-server-info-response", "description": "Result of reading connection and capability information for an MCP server.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "MCPGetServerInfoResponse", "slug": "/api/models/mcp-get-server-info-response" }, "usedBy": [ "conversations:mcpGetServerInfo" ], "usedByRoots": [], "fields": [ { "name": "serverInfo", "description": "Connection and capability information for the selected MCP server.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "MCPListAvailableServersRequest", "title": "MCPListAvailableServersRequest", "slug": "/api/models/mcp-list-available-servers-request", "description": "Server management", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "MCPListAvailableServersRequest", "slug": "/api/models/mcp-list-available-servers-request" }, "usedBy": [ "conversations:mcpListAvailableServers" ], "usedByRoots": [], "fields": [ { "name": "includeDisconnected", "description": "Whether the server listing should include disconnected MCP servers.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "kinds", "description": "Restrict the listing to these ownership classes. Empty = every kind, so an\nexisting caller that omits it sees no behavior change. Lets a console\nrequest a narrow view without standing up a new endpoint.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "MCPListAvailableServersResponse", "title": "MCPListAvailableServersResponse", "slug": "/api/models/mcp-list-available-servers-response", "description": "Result of listing the MCP servers available through the gateway.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "MCPListAvailableServersResponse", "slug": "/api/models/mcp-list-available-servers-response" }, "usedBy": [ "conversations:mcpListAvailableServers" ], "usedByRoots": [], "fields": [ { "name": "servers", "description": "Connection status of each MCP server included in the listing.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "MCPListPromptsRequest", "title": "MCPListPromptsRequest", "slug": "/api/models/mcp-list-prompts-request", "description": "Prompts", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "MCPListPromptsRequest", "slug": "/api/models/mcp-list-prompts-request" }, "usedBy": [ "conversations:mcpListPrompts" ], "usedByRoots": [], "fields": [ { "name": "serverId", "description": "Identifier of the MCP server to query.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "nameFilter", "description": "Filter applied to the names of discovered MCP prompts.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sessionId", "description": "Session routing hint for the MCP operation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MCPListPromptsResponse", "title": "MCPListPromptsResponse", "slug": "/api/models/mcp-list-prompts-response", "description": "Result of discovering prompt templates exposed by an MCP server.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "MCPListPromptsResponse", "slug": "/api/models/mcp-list-prompts-response" }, "usedBy": [ "conversations:mcpListPrompts" ], "usedByRoots": [], "fields": [ { "name": "prompts", "description": "Prompt templates returned by MCP discovery.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "totalCount", "description": "Number of entries reported by the MCP operation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MCPListResourcesRequest", "title": "MCPListResourcesRequest", "slug": "/api/models/mcp-list-resources-request", "description": "Resources", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "MCPListResourcesRequest", "slug": "/api/models/mcp-list-resources-request" }, "usedBy": [ "conversations:mcpListResources" ], "usedByRoots": [], "fields": [ { "name": "serverId", "description": "Identifier of the MCP server to query.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "uriFilter", "description": "Filter applied to the URIs of discovered MCP resources.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sessionId", "description": "Session routing hint for the MCP operation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MCPListResourcesResponse", "title": "MCPListResourcesResponse", "slug": "/api/models/mcp-list-resources-response", "description": "Result of discovering resources exposed by an MCP server.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "MCPListResourcesResponse", "slug": "/api/models/mcp-list-resources-response" }, "usedBy": [ "conversations:mcpListResources" ], "usedByRoots": [], "fields": [ { "name": "resources", "description": "Resource descriptions returned by MCP discovery.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "totalCount", "description": "Number of entries reported by the MCP operation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MCPListToolsRequest", "title": "MCPListToolsRequest", "slug": "/api/models/mcp-list-tools-request", "description": "Tool operations", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "MCPListToolsRequest", "slug": "/api/models/mcp-list-tools-request" }, "usedBy": [ "conversations:mcpListTools" ], "usedByRoots": [], "fields": [ { "name": "servers", "description": "MCP servers to inspect; an empty list requests tools from all available servers.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "sessionId", "description": "Session routing hint for the MCP operation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MCPListToolsResponse", "title": "MCPListToolsResponse", "slug": "/api/models/mcp-list-tools-response", "description": "Result of discovering tools exposed by MCP servers.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "MCPListToolsResponse", "slug": "/api/models/mcp-list-tools-response" }, "usedBy": [ "conversations:mcpListTools" ], "usedByRoots": [], "fields": [ { "name": "tools", "description": "Tool definitions returned by MCP discovery.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "totalCount", "description": "Number of entries reported by the MCP operation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MCPReadResourceRequest", "title": "MCPReadResourceRequest", "slug": "/api/models/mcp-read-resource-request", "description": "Input for reading an MCP resource by URI.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "MCPReadResourceRequest", "slug": "/api/models/mcp-read-resource-request" }, "usedBy": [ "conversations:mcpReadResource" ], "usedByRoots": [], "fields": [ { "name": "serverId", "description": "Identifier of the MCP server to query.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "uri", "description": "URI identifying the MCP resource to read.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sessionId", "description": "Session routing hint for the MCP operation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MCPReadResourceResponse", "title": "MCPReadResourceResponse", "slug": "/api/models/mcp-read-resource-response", "description": "Result of reading an MCP resource by URI.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "MCPReadResourceResponse", "slug": "/api/models/mcp-read-resource-response" }, "usedBy": [ "conversations:mcpReadResource" ], "usedByRoots": [], "fields": [ { "name": "resource", "description": "MCP resource with content when provided by the server.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "MCPServerInfo", "title": "MCPServerInfo", "slug": "/api/models/mcp-server-info", "description": "Detailed server information", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "domain-model", "title": "MCPServerInfo", "slug": "/api/models/mcp-server-info" }, "usedBy": [ "conversations:mcpGetServerInfo" ], "usedByRoots": [], "fields": [ { "name": "serverId", "description": "Identifier of the MCP server associated with the operation or tool.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Display name of the MCP server.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "version", "description": "Version of the resource represented by this message.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "capabilities", "description": "Capabilities reported by the MCP server.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Additional attributes associated with the resource.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "status", "description": "Current connection status reported for the MCP server.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "availableTools", "description": "Tool definitions currently reported by the MCP server.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "kind", "description": "Ownership category of the MCP server definition.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MCPServerReference", "title": "MCPServerReference", "slug": "/api/models/mcp-server-reference", "description": "MCP Server Reference\nLightweight reference to pre-configured MCP servers used by workflows", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "domain-model", "title": "MCPServerReference", "slug": "/api/models/mcp-server-reference" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync", "conversations:updatePromptVariables", "conversations:updateSettings" ], "usedByRoots": [], "fields": [ { "name": "serverId", "description": "ID of pre-configured MCP server (e.g., \"github\", \"filesystem\").", "presence": "implicit", "required": false, "requestRequired": true }, { "name": "enabled", "description": "Whether to use this MCP server. Omission means enabled; only an explicitly false value\nexcludes it from discovery.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "priority", "description": "Priority override for tool selection (higher = preferred).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "allowlistToolPatterns", "description": "Only include tools matching these patterns (e.g., \"github_get_*\", \"search_*\").", "presence": "collection", "required": false, "requestRequired": false }, { "name": "blocklistToolPatterns", "description": "Exclude tools matching these patterns (e.g., \"*_delete\", \"*_destroy\").", "presence": "collection", "required": false, "requestRequired": false }, { "name": "serverOverrides", "description": "Override server settings for this usage.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "MCPServerReferenceInput", "title": "MCPServerReference", "slug": "/api/models/mcp-server-reference-input", "description": "MCP Server Reference\nLightweight reference to pre-configured MCP servers used by workflows", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "domain-model", "title": "MCPServerReference", "slug": "/api/models/mcp-server-reference" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:updateAgentProfile", "conversations:appendMessage", "conversations:createThread", "conversations:mcpListTools", "conversations:sendMessage", "conversations:sendMessageSync", "conversations:updateSettings" ], "usedByRoots": [], "fields": [ { "name": "serverId", "description": "ID of pre-configured MCP server (e.g., \"github\", \"filesystem\").", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "enabled", "description": "Whether to use this MCP server. Omission means enabled; only an explicitly false value\nexcludes it from discovery.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "priority", "description": "Priority override for tool selection (higher = preferred).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "allowlistToolPatterns", "description": "Only include tools matching these patterns (e.g., \"github_get_*\", \"search_*\").", "presence": "collection", "required": false, "requestRequired": false }, { "name": "blocklistToolPatterns", "description": "Exclude tools matching these patterns (e.g., \"*_delete\", \"*_destroy\").", "presence": "collection", "required": false, "requestRequired": false }, { "name": "serverOverrides", "description": "Override server settings for this usage.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "MCPServerReferenceWebhook", "title": "MCPServerReference", "slug": "/api/models/mcp-server-reference-webhook", "description": "MCP Server Reference\nLightweight reference to pre-configured MCP servers used by workflows", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "tools-connections", "role": "domain-model", "title": "MCPServerReference", "slug": "/api/models/mcp-server-reference" }, "usedBy": [], "usedByRoots": [ "llm.message_published" ], "fields": [ { "name": "server_id", "description": "ID of pre-configured MCP server (e.g., \"github\", \"filesystem\").", "presence": "implicit", "required": false, "requestRequired": true }, { "name": "enabled", "description": "Whether to use this MCP server. Omission means enabled; only an explicitly false value\nexcludes it from discovery.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "priority", "description": "Priority override for tool selection (higher = preferred).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "allowlist_tool_patterns", "description": "Only include tools matching these patterns (e.g., \"github_get_*\", \"search_*\").", "presence": "collection", "required": false, "requestRequired": false }, { "name": "blocklist_tool_patterns", "description": "Exclude tools matching these patterns (e.g., \"*_delete\", \"*_destroy\").", "presence": "collection", "required": false, "requestRequired": false }, { "name": "server_overrides", "description": "Override server settings for this usage.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "MCPServerStatus", "title": "MCPServerStatus", "slug": "/api/models/mcp-server-status", "description": "MCP Server Status\nStatus information about an MCP server (used in responses)", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "domain-model", "title": "MCPServerStatus", "slug": "/api/models/mcp-server-status" }, "usedBy": [ "conversations:mcpListAvailableServers" ], "usedByRoots": [], "fields": [ { "name": "serverId", "description": "Identifier of the MCP server associated with the operation or tool.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Display name of the MCP server.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "status", "description": "Current connection status reported for the MCP server.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "toolsDiscovered", "description": "Number of tool definitions found during the last discovery.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "lastDiscoveryDuration", "description": "Elapsed duration of the last MCP tool discovery.", "presence": "message", "required": false, "requestRequired": false }, { "name": "lastError", "description": "Most recent error reported while contacting the MCP server.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "lastDiscoveryTime", "description": "Time when MCP tool discovery last ran.", "presence": "message", "required": false, "requestRequired": false }, { "name": "kind", "description": "Ownership of this server. Populated by ListAvailableServers for every\nsource it merges.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "defaultEnabled", "description": "Whether the built-in catalog recommends this server by default. This is a catalog\nrecommendation, not whether the server is enabled for a particular profile or conversation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "Memory", "title": "Memory", "slug": "/api/memory/models/memory", "description": "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.\n\n`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.\n\nMemory 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.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "memory-knowledge", "role": "domain-model", "title": "Memory", "slug": "/api/memory/models/memory" }, "usedBy": [ "conversations:getMemory", "conversations:listMemories", "conversations:searchMemories" ], "usedByRoots": [], "fields": [ { "name": "id", "description": "Unique memory identifier.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "memory", "description": "Stored fact text. It may be incomplete, stale or incorrect.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "userId", "description": "User associated with the memory.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "agentId", "description": "Agent or conversation associated with the memory.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "appId", "description": "Tenant identifier associated with the memory.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "runId", "description": "Associated run or session identifier.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Additional string-valued metadata attached to the memory.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "score", "description": "Relevance score returned by search. Its scale is provider-specific and is not a probability\nthat the fact is correct.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Creation time as an RFC 3339 timestamp; absent when unavailable.", "presence": "message", "required": false, "requestRequired": false }, { "name": "updatedAt", "description": "Last update time as an RFC 3339 timestamp; absent when unavailable.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "MemoryConfig", "title": "MemoryConfig", "slug": "/api/models/memory-config", "description": "Configuration for searching, injecting and storing semantic memories during generation.\n\nMemory 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)\n(set at thread creation or via `update-default-generation-config`) or per turn via\n[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).\n\nEnabled 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.\n\nReranking 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.\n\n[`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.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "memory-knowledge", "role": "domain-model", "title": "MemoryConfig", "slug": "/api/models/memory-config" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "enabled", "description": "Enable searching for relevant memories, adding them to generation context and extracting new\nmemories after generation. Default: false.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "searchTopK", "description": "Number of memories to retrieve during search.\nHigher values provide more context but increase token usage.\n\nRange: 1-50 (validated only when enabled = true)\nDefault: 5", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "searchThreshold", "description": "Minimum relevance score threshold for memory search results.\nMemories below this threshold are filtered out.\nRange: 0.0-1.0 (validated only when enabled = true)\nDefault: 0.3", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "injectAsSystemContext", "description": "When true, inject found memories into the system prompt context.\nMemories are formatted as a bullet list under a \"[Relevant memories:]\" header.\nDefault: true", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "searchQueryOverride", "description": "Custom search query to use instead of the last user message.\nIf empty, the last user message content is used as the search query.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableRerank", "description": "Enable reranking for improved search relevance.\nReranking provides better results but adds latency.\nDefault: false", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "addMemoriesAsync", "description": "When true, memory extraction happens asynchronously after generation completes.\nThis prevents extraction latency from affecting response time.\nDefault: true", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "customExtractionPrompt", "description": "Custom prompt for memory/fact extraction.\nIf empty, the default extraction prompt is used.\nUse this to customize what types of facts are extracted.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableGraph", "description": "Enable relationship extraction and graph-based memory search when graph memory is configured.\nDefault: false.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "agentIdOverride", "description": "Override the agent_id used for memory scoping.\nBy default, the conversation_id is used as the agent_id.\nUse this to share memories across multiple conversations.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "exposeAsMcpTool", "description": "Expose memory search as an MCP tool during generation.\nWhen true, the LLM can explicitly search memories via tool calls.\nRate limited to 3 searches per generation turn.\nDefault: false", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "includeAssistantMessages", "description": "Include assistant/agent-scoped memories in operations.\nWhen false, skips agent_id for both add and search operations,\nkeeping only user-scoped memories.\nDefault: false", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "injectMemoryTimestamps", "description": "Include created_at/updated_at timestamps on injected memories.\nWhen true, each memory bullet includes a \"(remembered: )\" annotation\nand optionally \"(updated: )\" if the memory was modified after creation.\nDefault: true", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MemoryConfigInput", "title": "MemoryConfig", "slug": "/api/models/memory-config-input", "description": "Configuration for searching, injecting and storing semantic memories during generation.\n\nMemory 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)\n(set at thread creation or via `update-default-generation-config`) or per turn via\n[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).\n\nEnabled 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.\n\nReranking 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.\n\n[`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.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "memory-knowledge", "role": "domain-model", "title": "MemoryConfig", "slug": "/api/models/memory-config" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:appendMessage", "conversations:createThread", "conversations:sendMessage", "conversations:sendMessageSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [ "generation-config" ], "fields": [ { "name": "enabled", "description": "Enable searching for relevant memories, adding them to generation context and extracting new\nmemories after generation. Default: false.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "searchTopK", "description": "Number of memories to retrieve during search.\nHigher values provide more context but increase token usage.\n\nRange: 1-50 (validated only when enabled = true)\nDefault: 5", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "searchThreshold", "description": "Minimum relevance score threshold for memory search results.\nMemories below this threshold are filtered out.\nRange: 0.0-1.0 (validated only when enabled = true)\nDefault: 0.3", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "injectAsSystemContext", "description": "When true, inject found memories into the system prompt context.\nMemories are formatted as a bullet list under a \"[Relevant memories:]\" header.\nDefault: true", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "searchQueryOverride", "description": "Custom search query to use instead of the last user message.\nIf empty, the last user message content is used as the search query.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableRerank", "description": "Enable reranking for improved search relevance.\nReranking provides better results but adds latency.\nDefault: false", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "addMemoriesAsync", "description": "When true, memory extraction happens asynchronously after generation completes.\nThis prevents extraction latency from affecting response time.\nDefault: true", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "customExtractionPrompt", "description": "Custom prompt for memory/fact extraction.\nIf empty, the default extraction prompt is used.\nUse this to customize what types of facts are extracted.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enableGraph", "description": "Enable relationship extraction and graph-based memory search when graph memory is configured.\nDefault: false.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "agentIdOverride", "description": "Override the agent_id used for memory scoping.\nBy default, the conversation_id is used as the agent_id.\nUse this to share memories across multiple conversations.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "exposeAsMcpTool", "description": "Expose memory search as an MCP tool during generation.\nWhen true, the LLM can explicitly search memories via tool calls.\nRate limited to 3 searches per generation turn.\nDefault: false", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "includeAssistantMessages", "description": "Include assistant/agent-scoped memories in operations.\nWhen false, skips agent_id for both add and search operations,\nkeeping only user-scoped memories.\nDefault: false", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "injectMemoryTimestamps", "description": "Include created_at/updated_at timestamps on injected memories.\nWhen true, each memory bullet includes a \"(remembered: )\" annotation\nand optionally \"(updated: )\" if the memory was modified after creation.\nDefault: true", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MemoryConfigWebhook", "title": "MemoryConfig", "slug": "/api/models/memory-config-webhook", "description": "Configuration for searching, injecting and storing semantic memories during generation.\n\nMemory 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)\n(set at thread creation or via `update-default-generation-config`) or per turn via\n[`overrideGenerationConfig`](/api/conversations/send-message#request-field-overridegenerationconfig).\n\nEnabled 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.\n\nReranking 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.\n\n[`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.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "memory-knowledge", "role": "domain-model", "title": "MemoryConfig", "slug": "/api/models/memory-config" }, "usedBy": [], "usedByRoots": [ "llm.generation_started", "llm.message_published" ], "fields": [ { "name": "enabled", "description": "Enable searching for relevant memories, adding them to generation context and extracting new\nmemories after generation. Default: false.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "search_top_k", "description": "Number of memories to retrieve during search.\nHigher values provide more context but increase token usage.\n\nRange: 1-50 (validated only when enabled = true)\nDefault: 5", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "search_threshold", "description": "Minimum relevance score threshold for memory search results.\nMemories below this threshold are filtered out.\nRange: 0.0-1.0 (validated only when enabled = true)\nDefault: 0.3", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "inject_as_system_context", "description": "When true, inject found memories into the system prompt context.\nMemories are formatted as a bullet list under a \"[Relevant memories:]\" header.\nDefault: true", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "search_query_override", "description": "Custom search query to use instead of the last user message.\nIf empty, the last user message content is used as the search query.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enable_rerank", "description": "Enable reranking for improved search relevance.\nReranking provides better results but adds latency.\nDefault: false", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "add_memories_async", "description": "When true, memory extraction happens asynchronously after generation completes.\nThis prevents extraction latency from affecting response time.\nDefault: true", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "custom_extraction_prompt", "description": "Custom prompt for memory/fact extraction.\nIf empty, the default extraction prompt is used.\nUse this to customize what types of facts are extracted.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "enable_graph", "description": "Enable relationship extraction and graph-based memory search when graph memory is configured.\nDefault: false.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "agent_id_override", "description": "Override the agent_id used for memory scoping.\nBy default, the conversation_id is used as the agent_id.\nUse this to share memories across multiple conversations.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "expose_as_mcp_tool", "description": "Expose memory search as an MCP tool during generation.\nWhen true, the LLM can explicitly search memories via tool calls.\nRate limited to 3 searches per generation turn.\nDefault: false", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "include_assistant_messages", "description": "Include assistant/agent-scoped memories in operations.\nWhen false, skips agent_id for both add and search operations,\nkeeping only user-scoped memories.\nDefault: false", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "inject_memory_timestamps", "description": "Include created_at/updated_at timestamps on injected memories.\nWhen true, each memory bullet includes a \"(remembered: )\" annotation\nand optionally \"(updated: )\" if the memory was modified after creation.\nDefault: true", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MemoryReference", "title": "MemoryReference", "slug": "/api/models/memory-reference", "description": "A memory record retrieved and included in generation context.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "memory-knowledge", "role": "domain-model", "title": "MemoryReference", "slug": "/api/models/memory-reference" }, "usedBy": [ "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "memoryId", "description": "Identifier of the retrieved memory record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "score", "description": "Relevance score reported by the memory provider for this match.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "memoryText", "description": "Text of the retrieved memory record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time when this record was created.", "presence": "message", "required": false, "requestRequired": false }, { "name": "updatedAt", "description": "Time when this record was last updated.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "MemoryReferenceInput", "title": "MemoryReference", "slug": "/api/models/memory-reference-input", "description": "A memory record retrieved and included in generation context.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "memory-knowledge", "role": "domain-model", "title": "MemoryReference", "slug": "/api/models/memory-reference" }, "usedBy": [ "conversations:appendMessage", "conversations:sendMessage", "conversations:sendMessageSync" ], "usedByRoots": [], "fields": [ { "name": "memoryId", "description": "Identifier of the retrieved memory record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "score", "description": "Relevance score reported by the memory provider for this match.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "memoryText", "description": "Text of the retrieved memory record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time when this record was created.", "presence": "message", "required": false, "requestRequired": false }, { "name": "updatedAt", "description": "Time when this record was last updated.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "MemoryReferenceWebhook", "title": "MemoryReference", "slug": "/api/models/memory-reference-webhook", "description": "A memory record retrieved and included in generation context.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "memory-knowledge", "role": "domain-model", "title": "MemoryReference", "slug": "/api/models/memory-reference" }, "usedBy": [], "usedByRoots": [ "llm.message_published" ], "fields": [ { "name": "memory_id", "description": "Identifier of the retrieved memory record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "score", "description": "Relevance score reported by the memory provider for this match.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "memory_text", "description": "Text of the retrieved memory record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "created_at", "description": "Time when this record was created.", "presence": "message", "required": false, "requestRequired": false }, { "name": "updated_at", "description": "Time when this record was last updated.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "MemorySearchParams", "title": "MemorySearchParams", "slug": "/api/models/memory-search-params", "description": "Parameters used to retrieve relevant memories during generation.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "memory-knowledge", "role": "domain-model", "title": "MemorySearchParams", "slug": "/api/models/memory-search-params" }, "usedBy": [ "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "query", "description": "Text submitted to memory retrieval for this generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "topK", "description": "Maximum memory matches requested during generation-context retrieval.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "threshold", "description": "Minimum relevance threshold requested for the memory query.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "rerank", "description": "Whether reranking was requested for the memory search.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "resultsReturned", "description": "Number of memory records returned by the search.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "relationsReturned", "description": "Number of graph relationships returned by the search.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MemorySearchParamsInput", "title": "MemorySearchParams", "slug": "/api/models/memory-search-params-input", "description": "Parameters used to retrieve relevant memories during generation.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "memory-knowledge", "role": "domain-model", "title": "MemorySearchParams", "slug": "/api/models/memory-search-params" }, "usedBy": [ "conversations:appendMessage", "conversations:sendMessage", "conversations:sendMessageSync" ], "usedByRoots": [], "fields": [ { "name": "query", "description": "Text submitted to memory retrieval for this generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "topK", "description": "Maximum memory matches requested during generation-context retrieval.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "threshold", "description": "Minimum relevance threshold requested for the memory query.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "rerank", "description": "Whether reranking was requested for the memory search.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "resultsReturned", "description": "Number of memory records returned by the search.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "relationsReturned", "description": "Number of graph relationships returned by the search.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MemorySearchParamsWebhook", "title": "MemorySearchParams", "slug": "/api/models/memory-search-params-webhook", "description": "Parameters used to retrieve relevant memories during generation.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "memory-knowledge", "role": "domain-model", "title": "MemorySearchParams", "slug": "/api/models/memory-search-params" }, "usedBy": [], "usedByRoots": [ "llm.message_published" ], "fields": [ { "name": "query", "description": "Text submitted to memory retrieval for this generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "top_k", "description": "Maximum memory matches requested during generation-context retrieval.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "threshold", "description": "Minimum relevance threshold requested for the memory query.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "rerank", "description": "Whether reranking was requested for the memory search.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "results_returned", "description": "Number of memory records returned by the search.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "relations_returned", "description": "Number of graph relationships returned by the search.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "Message", "title": "Message", "slug": "/api/models/message", "description": "Chat message", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "Message", "slug": "/api/models/message" }, "usedBy": [ "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "role", "description": "Role of the participant that produced the chat message.", "presence": "implicit", "required": false, "requestRequired": true }, { "name": "content", "description": "Content parts composing the chat message.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "toolCalls", "description": "Assistant-to-tool invocations.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "name", "description": "Name identifying the sender of the chat message.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "timestamp", "description": "Timestamp associated with the conversation message or event.", "presence": "message", "required": false, "requestRequired": false }, { "name": "messageId", "description": "Unique message identifier.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "annotations", "description": "Structured annotations (e.g., standardized web search URL citations, PDF reuse tokens)", "presence": "collection", "required": false, "requestRequired": false }, { "name": "sequence", "description": "Monotonic, per-conversation sequence number for stable ordering (1-based)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "generatedBy", "description": "Workflow run id or generator key that produced this message (e.g., workflow run key)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "usage", "description": "Token usage for this generation (populated for assistant messages)", "presence": "message", "required": false, "requestRequired": false }, { "name": "model", "description": "Model that generated this message (e.g., \"anthropic/claude-sonnet-4\")", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "generationContext", "description": "Dynamic context that shaped this generation (memories, search params, turn info)", "presence": "message", "required": false, "requestRequired": false }, { "name": "clientContext", "description": "Arbitrary client-supplied context attached by the client for this message", "presence": "message", "required": false, "requestRequired": false }, { "name": "feedback", "description": "Feedback on an assistant message, with one entry per rater identified by rated_by. A later\nrating by the same rater replaces their earlier entry.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "sourceUserMessageId", "description": "Identifier of the user message that opened this conversation turn. Generated messages in the\nsame turn share this value; a user message carries its own message_id. Empty on historical\nmessages that predate turn attribution.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "finishReason", "description": "Why the model stopped, verbatim from the provider: \"stop\",\n\"tool_calls\", \"length\", \"error\". Empty for historical messages.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MessageFeedback", "title": "MessageFeedback", "slug": "/api/models/message-feedback", "description": "One user's feedback on an assistant-generated message.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "MessageFeedback", "slug": "/api/models/message-feedback" }, "usedBy": [ "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "kind", "description": "Rating representation used to interpret the feedback value.", "presence": "implicit", "required": false, "requestRequired": true }, { "name": "thumbUp", "description": "Positive when true and negative when false; used for THUMB feedback.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "rating", "description": "Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "reason", "description": "Optional explanation for the rating.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "ratedAt", "description": "Timestamp when feedback was submitted (server-set)", "presence": "message", "required": false, "requestRequired": false }, { "name": "ratedBy", "description": "Identifier of the user who submitted this feedback. Set by the server\nfrom the authenticated user identity; never client-supplied. Each user\nhas one feedback entry per message.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MessageFeedbackInput", "title": "MessageFeedback", "slug": "/api/models/message-feedback-input", "description": "One user's feedback on an assistant-generated message.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "MessageFeedback", "slug": "/api/models/message-feedback" }, "usedBy": [ "conversations:appendMessage", "conversations:sendMessage", "conversations:sendMessageSync" ], "usedByRoots": [], "fields": [ { "name": "kind", "description": "Rating representation used to interpret the feedback value.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "thumbUp", "description": "Positive when true and negative when false; used for THUMB feedback.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "rating", "description": "Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "reason", "description": "Optional explanation for the rating.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "ratedAt", "description": "Timestamp when feedback was submitted (server-set)", "presence": "message", "required": false, "requestRequired": false }, { "name": "ratedBy", "description": "Identifier of the user who submitted this feedback. Set by the server\nfrom the authenticated user identity; never client-supplied. Each user\nhas one feedback entry per message.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MessageFeedbackWebhook", "title": "MessageFeedback", "slug": "/api/models/message-feedback-webhook", "description": "One user's feedback on an assistant-generated message.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "MessageFeedback", "slug": "/api/models/message-feedback" }, "usedBy": [], "usedByRoots": [ "llm.message_published" ], "fields": [ { "name": "kind", "description": "Rating representation used to interpret the feedback value.", "presence": "implicit", "required": false, "requestRequired": true }, { "name": "thumb_up", "description": "Positive when true and negative when false; used for THUMB feedback.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "rating", "description": "Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "reason", "description": "Optional explanation for the rating.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "rated_at", "description": "Timestamp when feedback was submitted (server-set)", "presence": "message", "required": false, "requestRequired": false }, { "name": "rated_by", "description": "Identifier of the user who submitted this feedback. Set by the server\nfrom the authenticated user identity; never client-supplied. Each user\nhas one feedback entry per message.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MessageInput", "title": "Message", "slug": "/api/models/message-input", "description": "Chat message", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "Message", "slug": "/api/models/message" }, "usedBy": [ "conversations:appendMessage", "conversations:sendMessage", "conversations:sendMessageSync" ], "usedByRoots": [], "fields": [ { "name": "role", "description": "Role of the participant that produced the chat message.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "content", "description": "Content parts composing the chat message.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "toolCalls", "description": "Assistant-to-tool invocations.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "name", "description": "Name identifying the sender of the chat message.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "timestamp", "description": "Timestamp associated with the conversation message or event.", "presence": "message", "required": false, "requestRequired": false }, { "name": "messageId", "description": "Unique message identifier.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "annotations", "description": "Structured annotations (e.g., standardized web search URL citations, PDF reuse tokens)", "presence": "collection", "required": false, "requestRequired": false }, { "name": "sequence", "description": "Monotonic, per-conversation sequence number for stable ordering (1-based)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "generatedBy", "description": "Workflow run id or generator key that produced this message (e.g., workflow run key)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "usage", "description": "Token usage for this generation (populated for assistant messages)", "presence": "message", "required": false, "requestRequired": false }, { "name": "model", "description": "Model that generated this message (e.g., \"anthropic/claude-sonnet-4\")", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "generationContext", "description": "Dynamic context that shaped this generation (memories, search params, turn info)", "presence": "message", "required": false, "requestRequired": false }, { "name": "clientContext", "description": "Arbitrary client-supplied context attached by the client for this message", "presence": "message", "required": false, "requestRequired": false }, { "name": "feedback", "description": "Feedback on an assistant message, with one entry per rater identified by rated_by. A later\nrating by the same rater replaces their earlier entry.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "sourceUserMessageId", "description": "Identifier of the user message that opened this conversation turn. Generated messages in the\nsame turn share this value; a user message carries its own message_id. Empty on historical\nmessages that predate turn attribution.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "finishReason", "description": "Why the model stopped, verbatim from the provider: \"stop\",\n\"tool_calls\", \"length\", \"error\". Empty for historical messages.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MessageWebhook", "title": "Message", "slug": "/api/models/message-webhook", "description": "Chat message", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "Message", "slug": "/api/models/message" }, "usedBy": [], "usedByRoots": [ "llm.message_published" ], "fields": [ { "name": "role", "description": "Role of the participant that produced the chat message.", "presence": "implicit", "required": false, "requestRequired": true }, { "name": "content", "description": "Content parts composing the chat message.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "tool_calls", "description": "Assistant-to-tool invocations.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "name", "description": "Name identifying the sender of the chat message.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "timestamp", "description": "Timestamp associated with the conversation message or event.", "presence": "message", "required": false, "requestRequired": false }, { "name": "message_id", "description": "Unique message identifier.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "annotations", "description": "Structured annotations (e.g., standardized web search URL citations, PDF reuse tokens)", "presence": "collection", "required": false, "requestRequired": false }, { "name": "sequence", "description": "Monotonic, per-conversation sequence number for stable ordering (1-based)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "generated_by", "description": "Workflow run id or generator key that produced this message (e.g., workflow run key)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "usage", "description": "Token usage for this generation (populated for assistant messages)", "presence": "message", "required": false, "requestRequired": false }, { "name": "model", "description": "Model that generated this message (e.g., \"anthropic/claude-sonnet-4\")", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "generation_context", "description": "Dynamic context that shaped this generation (memories, search params, turn info)", "presence": "message", "required": false, "requestRequired": false }, { "name": "client_context", "description": "Arbitrary client-supplied context attached by the client for this message", "presence": "message", "required": false, "requestRequired": false }, { "name": "feedback", "description": "Feedback on an assistant message, with one entry per rater identified by rated_by. A later\nrating by the same rater replaces their earlier entry.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "source_user_message_id", "description": "Identifier of the user message that opened this conversation turn. Generated messages in the\nsame turn share this value; a user message carries its own message_id. Empty on historical\nmessages that predate turn attribution.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "finish_reason", "description": "Why the model stopped, verbatim from the provider: \"stop\",\n\"tool_calls\", \"length\", \"error\". Empty for historical messages.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MintSttTokenRequest", "title": "MintSttTokenRequest", "slug": "/api/models/mint-stt-token-request", "description": "Mint a short-lived Cartesia STT access token for the calling user.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "MintSttTokenRequest", "slug": "/api/models/mint-stt-token-request" }, "usedBy": [ "conversations:mintSttToken" ], "usedByRoots": [], "fields": [] }, { "schemaName": "MintSttTokenResponse", "title": "MintSttTokenResponse", "slug": "/api/models/mint-stt-token-response", "description": "Result of issuing a short-lived Cartesia speech-to-text access token.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "MintSttTokenResponse", "slug": "/api/models/mint-stt-token-response" }, "usedBy": [ "conversations:mintSttToken" ], "usedByRoots": [], "fields": [ { "name": "token", "description": "Short-lived Cartesia speech-to-text access token.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "expiresInSeconds", "description": "Lifetime of the issued access token, in seconds.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ModelError", "title": "ModelError", "slug": "/api/models/model-error", "description": "Model-specific error context.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "ModelError", "slug": "/api/models/model-error" }, "usedBy": [ "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "modelId", "description": "The model ID that caused the error.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "reason", "description": "Why the model failed (e.g., \"invalid\", \"unavailable\", \"moderation_flagged\").", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "alternativesTried", "description": "Alternative models that were tried or could be tried.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "ModelErrorInput", "title": "ModelError", "slug": "/api/models/model-error-input", "description": "Model-specific error context.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "ModelError", "slug": "/api/models/model-error" }, "usedBy": [ "conversations:submitClientToolResults", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "modelId", "description": "The model ID that caused the error.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "reason", "description": "Why the model failed (e.g., \"invalid\", \"unavailable\", \"moderation_flagged\").", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "alternativesTried", "description": "Alternative models that were tried or could be tried.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "ModelErrorWebhook", "title": "ModelError", "slug": "/api/models/model-error-webhook", "description": "Model-specific error context.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "ModelError", "slug": "/api/models/model-error" }, "usedBy": [], "usedByRoots": [ "llm.generation_completed" ], "fields": [ { "name": "model_id", "description": "The model ID that caused the error.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "reason", "description": "Why the model failed (e.g., \"invalid\", \"unavailable\", \"moderation_flagged\").", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "alternatives_tried", "description": "Alternative models that were tried or could be tried.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "ModelRoutingFilter", "title": "ModelRoutingFilter", "slug": "/api/models/model-routing-filter", "description": "ModelRoutingFilter defines metadata-based criteria for filtering model candidates.\nAll filters are ANDed — a model must pass every specified filter.\nUnset/zero-value fields are ignored (no filtering on that dimension).\n\nUnset 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.\n\n[`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.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "ModelRoutingFilter", "slug": "/api/models/model-routing-filter" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "minContextLength", "description": "Minimum context window (tokens). Models below this are excluded.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "minMaxCompletionTokens", "description": "Minimum max completion tokens. Models below this are excluded.\nModels reporting 0 (unknown) pass through (permissive).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "requiredInputModalities", "description": "Required input modalities (e.g., [\"image\", \"audio\"]). Model must support ALL listed.\nModels with empty input_modalities are filtered out (strict).", "presence": "collection", "required": false, "requestRequired": false }, { "name": "requiredOutputModalities", "description": "Required output modalities (e.g., [\"image\"]). Model must support ALL listed.\nModels with empty output_modalities are filtered out (strict).", "presence": "collection", "required": false, "requestRequired": false }, { "name": "maxPromptCost", "description": "Maximum cost per prompt token (e.g., 0.000003). 0 = no limit.\nUnparseable pricing strings pass through (permissive).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxCompletionCost", "description": "Maximum cost per completion token. 0 = no limit.\nUnparseable pricing strings pass through (permissive).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "excludeModerated", "description": "Exclude models with content moderation enabled.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "requiredParameters", "description": "Required supported parameters (e.g., [\"tools\", \"response_format\"]).\nModel must support ALL listed.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "ModelRoutingFilterInput", "title": "ModelRoutingFilter", "slug": "/api/models/model-routing-filter-input", "description": "ModelRoutingFilter defines metadata-based criteria for filtering model candidates.\nAll filters are ANDed — a model must pass every specified filter.\nUnset/zero-value fields are ignored (no filtering on that dimension).\n\nUnset 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.\n\n[`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.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "ModelRoutingFilter", "slug": "/api/models/model-routing-filter" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:appendMessage", "conversations:createThread", "conversations:sendMessage", "conversations:sendMessageSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [ "generation-config" ], "fields": [ { "name": "minContextLength", "description": "Minimum context window (tokens). Models below this are excluded.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "minMaxCompletionTokens", "description": "Minimum max completion tokens. Models below this are excluded.\nModels reporting 0 (unknown) pass through (permissive).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "requiredInputModalities", "description": "Required input modalities (e.g., [\"image\", \"audio\"]). Model must support ALL listed.\nModels with empty input_modalities are filtered out (strict).", "presence": "collection", "required": false, "requestRequired": false }, { "name": "requiredOutputModalities", "description": "Required output modalities (e.g., [\"image\"]). Model must support ALL listed.\nModels with empty output_modalities are filtered out (strict).", "presence": "collection", "required": false, "requestRequired": false }, { "name": "maxPromptCost", "description": "Maximum cost per prompt token (e.g., 0.000003). 0 = no limit.\nUnparseable pricing strings pass through (permissive).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxCompletionCost", "description": "Maximum cost per completion token. 0 = no limit.\nUnparseable pricing strings pass through (permissive).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "excludeModerated", "description": "Exclude models with content moderation enabled.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "requiredParameters", "description": "Required supported parameters (e.g., [\"tools\", \"response_format\"]).\nModel must support ALL listed.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "ModelRoutingFilterWebhook", "title": "ModelRoutingFilter", "slug": "/api/models/model-routing-filter-webhook", "description": "ModelRoutingFilter defines metadata-based criteria for filtering model candidates.\nAll filters are ANDed — a model must pass every specified filter.\nUnset/zero-value fields are ignored (no filtering on that dimension).\n\nUnset 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.\n\n[`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.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "ModelRoutingFilter", "slug": "/api/models/model-routing-filter" }, "usedBy": [], "usedByRoots": [ "llm.generation_started", "llm.message_published" ], "fields": [ { "name": "min_context_length", "description": "Minimum context window (tokens). Models below this are excluded.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "min_max_completion_tokens", "description": "Minimum max completion tokens. Models below this are excluded.\nModels reporting 0 (unknown) pass through (permissive).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "required_input_modalities", "description": "Required input modalities (e.g., [\"image\", \"audio\"]). Model must support ALL listed.\nModels with empty input_modalities are filtered out (strict).", "presence": "collection", "required": false, "requestRequired": false }, { "name": "required_output_modalities", "description": "Required output modalities (e.g., [\"image\"]). Model must support ALL listed.\nModels with empty output_modalities are filtered out (strict).", "presence": "collection", "required": false, "requestRequired": false }, { "name": "max_prompt_cost", "description": "Maximum cost per prompt token (e.g., 0.000003). 0 = no limit.\nUnparseable pricing strings pass through (permissive).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "max_completion_cost", "description": "Maximum cost per completion token. 0 = no limit.\nUnparseable pricing strings pass through (permissive).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "exclude_moderated", "description": "Exclude models with content moderation enabled.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "required_parameters", "description": "Required supported parameters (e.g., [\"tools\", \"response_format\"]).\nModel must support ALL listed.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "MoveFileRequest", "title": "MoveFileRequest", "slug": "/api/models/move-file-request", "description": "MoveFileRequest moves/renames a file (identity is the file_id; path is a label)", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "MoveFileRequest", "slug": "/api/models/move-file-request" }, "usedBy": [ "storage:moveFile" ], "usedByRoots": [], "fields": [ { "name": "fileId", "description": "Stable identifier of the stored file.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "destinationFolder", "description": "Destination folder path for the file move.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "newName", "description": "Replacement file name for the moved file. Omit to preserve its current name.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "MoveFileResponse", "title": "MoveFileResponse", "slug": "/api/models/move-file-response", "description": "Result payload for changing a stored file’s folder location and optional name.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "MoveFileResponse", "slug": "/api/models/move-file-response" }, "usedBy": [ "storage:moveFile" ], "usedByRoots": [], "fields": [ { "name": "file", "description": "Metadata for the file affected or retrieved by the operation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "moved", "description": "Whether the file move operation reports completion.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "NamedCount", "title": "NamedCount", "slug": "/api/models/named-count", "description": "Count of evaluation records grouped under a shared label.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "NamedCount", "slug": "/api/models/named-count" }, "usedBy": [ "evals:getOverview" ], "usedByRoots": [], "fields": [ { "name": "name", "description": "Grouping label associated with this record count.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "count", "description": "Number of evaluation records represented by this group.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ObjectRef", "title": "ObjectRef", "slug": "/api/models/object-ref", "description": "ObjectRef references an object in storage", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "domain-model", "title": "ObjectRef", "slug": "/api/models/object-ref" }, "usedBy": [ "storage:generateDownloadUrl", "storage:getFileMetadata", "storage:getState", "storage:listFiles", "storage:moveFile", "storage:registerUploadedFile", "storage:searchFiles", "storage:updateFileMetadata", "storage:uploadFile" ], "usedByRoots": [], "fields": [ { "name": "bucket", "description": "Storage bucket containing the object.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "key", "description": "Object key within the selected storage bucket.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "provider", "description": "Storage provider used to access the object.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "Observation", "title": "Observation", "slug": "/api/models/observation", "description": "Timed evaluation span or generation record with model usage, inputs, outputs, and scores.\nA generation observation originates the profile and configuration attribution promoted to\nits trace; callers can read those links directly on either record.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "Observation", "slug": "/api/models/observation" }, "usedBy": [ "evals:getTrace", "evals:listObservations" ], "usedByRoots": [], "fields": [ { "name": "observationId", "description": "Identifier of the evaluation observation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "traceId", "description": "Identifier of the evaluation trace.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "parentObservationId", "description": "Identifier of the parent observation within the trace.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "type", "description": "Observation kind reported by the evaluation provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Operation name recorded for the evaluation observation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "level", "description": "Observation log level reported by the evaluation provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "statusMessage", "description": "Diagnostic text explaining the reported state.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "startTime", "description": "Beginning of the time interval represented by this operation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "endTime", "description": "End of the time interval represented by this operation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "completionStartTime", "description": "Time to first token, generations only.", "presence": "message", "required": false, "requestRequired": false }, { "name": "latencySeconds", "description": "Elapsed observation latency, in seconds.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "inputJson", "description": "Evaluation input serialized as JSON.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "outputJson", "description": "Evaluation output serialized as JSON.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadataJson", "description": "Additional attributes serialized as a JSON object.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "model", "description": "Model identifier recorded for the evaluated generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "modelParametersJson", "description": "Model parameters recorded as a serialized JSON object.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "inputTokens", "description": "Input-token usage reported for the evaluated generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "outputTokens", "description": "Output-token usage reported for the evaluated generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "totalTokens", "description": "Total token usage reported for the evaluated generation or aggregate.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "inputCost", "description": "Cost attributed to model input by the evaluation provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "outputCost", "description": "Cost attributed to model output by the evaluation provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "totalCost", "description": "Total cost reported for the evaluated generation or aggregate.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "environment", "description": "Environment label attached to the evaluation record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "version", "description": "Version of the resource represented by this message.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "promptName", "description": "Name of the versioned prompt associated with the generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "promptVersion", "description": "Version of the prompt associated with the generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "scores", "description": "Evaluation scores returned for the selected objects or query.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "commentCount", "description": "Number of comments reported on the evaluation object.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "conversationId", "description": "Identifier of the conversation associated with this evaluation observation, when recorded.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sourceUserMessageId", "description": "Identifier of the user message that opened the evaluated generation turn.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "profileId", "description": "Identifier of the agent profile associated with the generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "configHash", "description": "Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation\nresults. Other settings are excluded; this is not an immutable profile revision.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "OperationStatus", "title": "OperationStatus", "slug": "/api/models/operation-status", "description": "Mirrors Novu's common delete/mutate acknowledgement response.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "domain-model", "title": "OperationStatus", "slug": "/api/models/operation-status" }, "usedBy": [ "notifications:archiveInboxMessage", "notifications:completeInboxAction", "notifications:deleteInboxMessage", "notifications:deleteSubscriber", "notifications:deleteTopic", "notifications:revertInboxAction", "notifications:unarchiveInboxMessage" ], "usedByRoots": [], "fields": [ { "name": "acknowledged", "description": "Whether the provider acknowledged the requested operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "status", "description": "Status reported by the notification provider.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PaginationInfo", "title": "PaginationInfo", "slug": "/api/models/pagination-info", "description": "Page position and aggregate counts accompanying a paginated provider listing.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "webhooks", "role": "domain-model", "title": "PaginationInfo", "slug": "/api/models/pagination-info" }, "usedBy": [ "webhooks:listWebhookDeliveries", "webhooks:listWebhookEndpoints", "webhooks:listWebhookSubscriptions" ], "usedByRoots": [], "fields": [ { "name": "total", "description": "Total number of entries reported by the listing.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "page", "description": "Page number used by this listing operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "perPage", "description": "Number of entries requested per page.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "totalPages", "description": "Total number of pages reported for the current query.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PauseJobRequest", "title": "PauseJobRequest", "slug": "/api/models/pause-job-request", "description": "Inputs for pausing a scheduled job and its trigger settings.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "scheduling", "role": "operation-envelope", "title": "PauseJobRequest", "slug": "/api/models/pause-job-request" }, "usedBy": [ "scheduled-jobs:pauseJob" ], "usedByRoots": [], "fields": [ { "name": "scheduleId", "description": "Identifier of the scheduled job.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "reason", "description": "Explanation recorded for pausing the scheduled job.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "externalId", "description": "Caller-assigned correlation identifier for the scheduled job.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PdfAnnotation", "title": "PdfAnnotation", "slug": "/api/models/pdf-annotation", "description": "Provider annotation identifying a parsed PDF and reusable parsing output.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "PdfAnnotation", "slug": "/api/models/pdf-annotation" }, "usedBy": [ "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "filename", "description": "Optional identifying information about the original file", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "engine", "description": "PDF parsing engine used by provider (e.g., \"pdf-text\", \"mistral-ocr\", \"native\")", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "token", "description": "Opaque provider token or handle allowing reuse without re-parsing", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sourceUrl", "description": "Optional: original source reference (public URL or data: URL)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "hash", "description": "Provider-supplied hash identifying the parsed file.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "content", "description": "Optional structured content returned by provider annotations (text, image URLs, etc.)\nNote: This can be large; include only if you need to round-trip provider annotations.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "PdfAnnotationInput", "title": "PdfAnnotation", "slug": "/api/models/pdf-annotation-input", "description": "Provider annotation identifying a parsed PDF and reusable parsing output.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "PdfAnnotation", "slug": "/api/models/pdf-annotation" }, "usedBy": [ "conversations:appendMessage", "conversations:sendMessage", "conversations:sendMessageSync" ], "usedByRoots": [], "fields": [ { "name": "filename", "description": "Optional identifying information about the original file", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "engine", "description": "PDF parsing engine used by provider (e.g., \"pdf-text\", \"mistral-ocr\", \"native\")", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "token", "description": "Opaque provider token or handle allowing reuse without re-parsing", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sourceUrl", "description": "Optional: original source reference (public URL or data: URL)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "hash", "description": "Provider-supplied hash identifying the parsed file.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "content", "description": "Optional structured content returned by provider annotations (text, image URLs, etc.)\nNote: This can be large; include only if you need to round-trip provider annotations.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "PdfAnnotationWebhook", "title": "PdfAnnotation", "slug": "/api/models/pdf-annotation-webhook", "description": "Provider annotation identifying a parsed PDF and reusable parsing output.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "PdfAnnotation", "slug": "/api/models/pdf-annotation" }, "usedBy": [], "usedByRoots": [ "llm.message_published" ], "fields": [ { "name": "filename", "description": "Optional identifying information about the original file", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "engine", "description": "PDF parsing engine used by provider (e.g., \"pdf-text\", \"mistral-ocr\", \"native\")", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "token", "description": "Opaque provider token or handle allowing reuse without re-parsing", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "source_url", "description": "Optional: original source reference (public URL or data: URL)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "hash", "description": "Provider-supplied hash identifying the parsed file.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "content", "description": "Optional structured content returned by provider annotations (text, image URLs, etc.)\nNote: This can be large; include only if you need to round-trip provider annotations.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "PendingChange", "title": "PendingChange", "slug": "/api/models/pending-change", "description": "Notification configuration change awaiting promotion to another provider environment.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "domain-model", "title": "PendingChange", "slug": "/api/models/pending-change" }, "usedBy": [ "notifications:getPendingChanges" ], "usedByRoots": [], "fields": [ { "name": "changeId", "description": "Identifier of a pending notification configuration change.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "type", "description": "Kind of notification resource affected by the pending configuration change.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "entityName", "description": "Name of the notification resource affected by the pending change.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "entityId", "description": "Identifier of the notification resource affected by the pending change.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time when this record was created.", "presence": "message", "required": false, "requestRequired": false }, { "name": "createdBy", "description": "Identifier of the actor that created the pending change.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PercentileThreshold", "title": "PercentileThreshold", "slug": "/api/models/percentile-threshold", "description": "Percentile thresholds for provider performance metrics", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "PercentileThreshold", "slug": "/api/models/percentile-threshold" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "p50", "description": "Threshold applied to the provider metric’s 50th percentile.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "p90", "description": "Threshold applied to the provider metric’s 90th percentile.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PercentileThresholdInput", "title": "PercentileThreshold", "slug": "/api/models/percentile-threshold-input", "description": "Percentile thresholds for provider performance metrics", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "PercentileThreshold", "slug": "/api/models/percentile-threshold" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:appendMessage", "conversations:createThread", "conversations:sendMessage", "conversations:sendMessageSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [ "generation-config" ], "fields": [ { "name": "p50", "description": "Threshold applied to the provider metric’s 50th percentile.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "p90", "description": "Threshold applied to the provider metric’s 90th percentile.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PercentileThresholdWebhook", "title": "PercentileThreshold", "slug": "/api/models/percentile-threshold-webhook", "description": "Percentile thresholds for provider performance metrics", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "PercentileThreshold", "slug": "/api/models/percentile-threshold" }, "usedBy": [], "usedByRoots": [ "llm.generation_started", "llm.message_published" ], "fields": [ { "name": "p50", "description": "Threshold applied to the provider metric’s 50th percentile.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "p90", "description": "Threshold applied to the provider metric’s 90th percentile.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PipedreamCreateConnectTokenRequest", "title": "PipedreamCreateConnectTokenRequest", "slug": "/api/models/pipedream-create-connect-token-request", "description": "Inputs for issuing a token and hosted link for connecting an end-user account.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "PipedreamCreateConnectTokenRequest", "slug": "/api/models/pipedream-create-connect-token-request" }, "usedBy": [ "connected-apps:pipedreamCreateConnectToken" ], "usedByRoots": [], "fields": [ { "name": "state", "description": "Optional opaque state to round-trip in redirect", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "redirectUri", "description": "Optional universal redirect (success) URI override", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "allowedOrigins", "description": "CORS allowed origins for hosted Connect (iframe)", "presence": "collection", "required": false, "requestRequired": false }, { "name": "successRedirectUrl", "description": "Optional explicit success/error redirects", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "errorRedirectUrl", "description": "URL to which the account-connection flow redirects on error.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "webhookUrl", "description": "Optional webhook for Connect notifications", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "appSlug", "description": "App slug the end user should connect (e.g. \"github\", \"strava\").", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PipedreamCreateConnectTokenResponse", "title": "PipedreamCreateConnectTokenResponse", "slug": "/api/models/pipedream-create-connect-token-response", "description": "Result payload for issuing a token and hosted link for connecting an end-user account.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "PipedreamCreateConnectTokenResponse", "slug": "/api/models/pipedream-create-connect-token-response" }, "usedBy": [ "connected-apps:pipedreamCreateConnectToken" ], "usedByRoots": [], "fields": [ { "name": "token", "description": "Short-lived Pipedream Connect token returned by the provider.", "presence": "implicit", "required": false, "requestRequired": true }, { "name": "connectLinkUrl", "description": "Pipedream Connect URL used to authorize an account connection.", "presence": "implicit", "required": false, "requestRequired": true }, { "name": "expiresAt", "description": "Time when the credential or resource expires.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "PipedreamDeleteAccountForCurrentUserRequest", "title": "PipedreamDeleteAccountForCurrentUserRequest", "slug": "/api/models/pipedream-delete-account-for-current-user-request", "description": "Inputs for removing a Pipedream account connection for the calling user.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "PipedreamDeleteAccountForCurrentUserRequest", "slug": "/api/models/pipedream-delete-account-for-current-user-request" }, "usedBy": [ "connected-apps:pipedreamDeleteAccountForCurrentUser" ], "usedByRoots": [], "fields": [ { "name": "accountId", "description": "Which connected account to disconnect. Ownership is enforced downstream\nagainst the caller's own accounts — an id belonging to anyone else reads\nback as not found.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "PipedreamDeleteAccountForCurrentUserResponse", "title": "PipedreamDeleteAccountForCurrentUserResponse", "slug": "/api/models/pipedream-delete-account-for-current-user-response", "description": "Result payload for removing a Pipedream account connection for the calling user.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "PipedreamDeleteAccountForCurrentUserResponse", "slug": "/api/models/pipedream-delete-account-for-current-user-response" }, "usedBy": [ "connected-apps:pipedreamDeleteAccountForCurrentUser" ], "usedByRoots": [], "fields": [ { "name": "deleted", "description": "Whether the deletion operation reports the resource removed.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PipedreamDeleteExternalUserForCurrentUserRequest", "title": "PipedreamDeleteExternalUserForCurrentUserRequest", "slug": "/api/models/pipedream-delete-external-user-for-current-user-request", "description": "Inputs for removing the calling user’s Pipedream identity and connected accounts.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "PipedreamDeleteExternalUserForCurrentUserRequest", "slug": "/api/models/pipedream-delete-external-user-for-current-user-request" }, "usedBy": [ "connected-apps:pipedreamDeleteExternalUserForCurrentUser" ], "usedByRoots": [], "fields": [] }, { "schemaName": "PipedreamDeleteExternalUserForCurrentUserResponse", "title": "PipedreamDeleteExternalUserForCurrentUserResponse", "slug": "/api/models/pipedream-delete-external-user-for-current-user-response", "description": "Result payload for removing the calling user’s Pipedream identity and connected accounts.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "PipedreamDeleteExternalUserForCurrentUserResponse", "slug": "/api/models/pipedream-delete-external-user-for-current-user-response" }, "usedBy": [ "connected-apps:pipedreamDeleteExternalUserForCurrentUser" ], "usedByRoots": [], "fields": [ { "name": "deleted", "description": "Whether the deletion operation reports the resource removed.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "accountsDeleted", "description": "How many connected accounts went with the user. Counted from a read taken\njust before the delete, since Pipedream answers 204 with no body — a\nconnection added between the two calls is still deleted, just not counted.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PipedreamListAccountsForCurrentUserRequest", "title": "PipedreamListAccountsForCurrentUserRequest", "slug": "/api/models/pipedream-list-accounts-for-current-user-request", "description": "Inputs for listing Pipedream account connections belonging to the calling user.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "PipedreamListAccountsForCurrentUserRequest", "slug": "/api/models/pipedream-list-accounts-for-current-user-request" }, "usedBy": [ "connected-apps:pipedreamListAccountsForCurrentUser" ], "usedByRoots": [], "fields": [ { "name": "after", "description": "Cursor selecting entries after the specified position in the provider listing.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "before", "description": "Cursor selecting entries before the specified position in the provider listing.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "limit", "description": "Maximum number of entries requested from the listing.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "oauthAppId", "description": "OAuth application identifier used to select connected accounts.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "app", "description": "Pipedream app slug used to restrict the operation to one connected app.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "includeCredentials", "description": "Whether the provider should include account credentials in its response.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PipedreamListAccountsForCurrentUserResponse", "title": "PipedreamListAccountsForCurrentUserResponse", "slug": "/api/models/pipedream-list-accounts-for-current-user-response", "description": "Result payload for listing Pipedream account connections belonging to the calling user.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "PipedreamListAccountsForCurrentUserResponse", "slug": "/api/models/pipedream-list-accounts-for-current-user-response" }, "usedBy": [ "connected-apps:pipedreamListAccountsForCurrentUser" ], "usedByRoots": [], "fields": [ { "name": "data", "description": "Pipedream connected accounts returned for this page.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "pageInfo", "description": "Cursor and count information returned with the provider listing.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "PipedreamListAppCategoriesRequest", "title": "PipedreamListAppCategoriesRequest", "slug": "/api/models/pipedream-list-app-categories-request", "description": "Inputs for discovering the categories used by the Pipedream app catalog.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "PipedreamListAppCategoriesRequest", "slug": "/api/models/pipedream-list-app-categories-request" }, "usedBy": [ "connected-apps:pipedreamListAppCategories" ], "usedByRoots": [], "fields": [ { "name": "after", "description": "Cursor selecting entries after the specified position in the provider listing.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "before", "description": "Cursor selecting entries before the specified position in the provider listing.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "limit", "description": "Maximum number of entries requested from the listing.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PipedreamListAppCategoriesResponse", "title": "PipedreamListAppCategoriesResponse", "slug": "/api/models/pipedream-list-app-categories-response", "description": "Result payload for discovering the categories used by the Pipedream app catalog.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "PipedreamListAppCategoriesResponse", "slug": "/api/models/pipedream-list-app-categories-response" }, "usedBy": [ "connected-apps:pipedreamListAppCategories" ], "usedByRoots": [], "fields": [ { "name": "data", "description": "Pipedream app categories returned for this page.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "pageInfo", "description": "Cursor and count information returned with the provider listing.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "PipedreamListAppsRequest", "title": "PipedreamListAppsRequest", "slug": "/api/models/pipedream-list-apps-request", "description": "Inputs for searching the Pipedream app catalog with pagination and sorting.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "PipedreamListAppsRequest", "slug": "/api/models/pipedream-list-apps-request" }, "usedBy": [ "connected-apps:pipedreamListApps" ], "usedByRoots": [], "fields": [ { "name": "after", "description": "Cursor selecting entries after the specified position in the provider listing.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "before", "description": "Cursor selecting entries before the specified position in the provider listing.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "limit", "description": "Maximum number of entries requested from the listing.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "q", "description": "Free-text search over app names in the integration catalog.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "categoryIds", "description": "Integration app category identifiers used to restrict the listing.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "sortKey", "description": "Provider field used to order catalog results.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sortDirection", "description": "Direction in which the provider should order catalog results.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PipedreamListAppsResponse", "title": "PipedreamListAppsResponse", "slug": "/api/models/pipedream-list-apps-response", "description": "Result payload for searching the Pipedream app catalog with pagination and sorting.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "PipedreamListAppsResponse", "slug": "/api/models/pipedream-list-apps-response" }, "usedBy": [ "connected-apps:pipedreamListApps" ], "usedByRoots": [], "fields": [ { "name": "data", "description": "Pipedream app catalog entries returned for this page.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "pageInfo", "description": "Cursor and count information returned with the provider listing.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "PipedreamPageInfo", "title": "PipedreamPageInfo", "slug": "/api/models/pipedream-page-info", "description": "Pagination information returned in list responses", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "domain-model", "title": "PipedreamPageInfo", "slug": "/api/models/pipedream-page-info" }, "usedBy": [ "connected-apps:pipedreamListAccountsForCurrentUser", "connected-apps:pipedreamListAppCategories", "connected-apps:pipedreamListApps" ], "usedByRoots": [], "fields": [ { "name": "count", "description": "Items in current page.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "totalCount", "description": "Total items matching query.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "startCursor", "description": "Cursor for start of page.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "endCursor", "description": "Cursor for end of page.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PipedreamProxyForCurrentUserRequest", "title": "PipedreamProxyForCurrentUserRequest", "slug": "/api/models/pipedream-proxy-for-current-user-request", "description": "Inputs for making an authenticated app API request through the calling user’s connected account.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "PipedreamProxyForCurrentUserRequest", "slug": "/api/models/pipedream-proxy-for-current-user-request" }, "usedBy": [ "connected-apps:pipedreamProxyForCurrentUser" ], "usedByRoots": [], "fields": [ { "name": "accountId", "description": "One of the caller's own connected accounts (id from list-accounts).\nAny other id reads back as not found.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "method", "description": "HTTP method used for the proxied or signed request.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "url", "description": "URL associated with the resource or outbound request.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "headers", "description": "Forwarded upstream (sent as x-pd-proxy-).", "presence": "collection", "required": false, "requestRequired": false }, { "name": "body", "description": "Raw request body (base64 on the wire). Empty for GET/HEAD.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PipedreamProxyForCurrentUserResponse", "title": "PipedreamProxyForCurrentUserResponse", "slug": "/api/models/pipedream-proxy-for-current-user-response", "description": "Result payload for making an authenticated app API request through the calling user’s connected account.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "PipedreamProxyForCurrentUserResponse", "slug": "/api/models/pipedream-proxy-for-current-user-response" }, "usedBy": [ "connected-apps:pipedreamProxyForCurrentUser" ], "usedByRoots": [], "fields": [ { "name": "status", "description": "HTTP status code returned by the connected app’s API.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "headers", "description": "HTTP response headers returned by the connected app’s API.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "body", "description": "Raw upstream body (base64 on the wire), capped at 4 MiB. Larger bodies are rejected rather\nthan truncated, with OUT_OF_RANGE and reason RESPONSE_TOO_LARGE.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PipedreamRetrieveAppRequest", "title": "PipedreamRetrieveAppRequest", "slug": "/api/models/pipedream-retrieve-app-request", "description": "Inputs for retrieving app catalog metadata by its Pipedream slug.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "PipedreamRetrieveAppRequest", "slug": "/api/models/pipedream-retrieve-app-request" }, "usedBy": [ "connected-apps:pipedreamRetrieveApp" ], "usedByRoots": [], "fields": [ { "name": "nameSlug", "description": "Pipedream app slug identifying the catalog entry.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "PipedreamRetrieveAppResponse", "title": "PipedreamRetrieveAppResponse", "slug": "/api/models/pipedream-retrieve-app-response", "description": "Result payload for retrieving app catalog metadata by its Pipedream slug.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "PipedreamRetrieveAppResponse", "slug": "/api/models/pipedream-retrieve-app-response" }, "usedBy": [ "connected-apps:pipedreamRetrieveApp" ], "usedByRoots": [], "fields": [ { "name": "app", "description": "Catalog metadata returned for the selected Pipedream app.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "PluginConfig", "title": "PluginConfig", "slug": "/api/models/plugin-config", "description": "Provider plugin identifier and its parser, search, or additional configuration.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "PluginConfig", "slug": "/api/models/plugin-config" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "id", "description": "Provider plugin identifier, such as file-parser.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pdf", "description": "PDF annotation or parser configuration selected by the enclosing message.", "presence": "message", "required": false, "requestRequired": false }, { "name": "web", "description": "Web-search configuration for the selected generation plugin.", "presence": "message", "required": false, "requestRequired": false }, { "name": "params", "description": "Additional provider-specific plugin parameters.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "PluginConfigInput", "title": "PluginConfig", "slug": "/api/models/plugin-config-input", "description": "Provider plugin identifier and its parser, search, or additional configuration.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "PluginConfig", "slug": "/api/models/plugin-config" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:appendMessage", "conversations:createThread", "conversations:sendMessage", "conversations:sendMessageSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [ "generation-config" ], "fields": [ { "name": "id", "description": "Provider plugin identifier, such as file-parser.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pdf", "description": "PDF annotation or parser configuration selected by the enclosing message.", "presence": "message", "required": false, "requestRequired": false }, { "name": "web", "description": "Web-search configuration for the selected generation plugin.", "presence": "message", "required": false, "requestRequired": false }, { "name": "params", "description": "Additional provider-specific plugin parameters.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "PluginConfigWebhook", "title": "PluginConfig", "slug": "/api/models/plugin-config-webhook", "description": "Provider plugin identifier and its parser, search, or additional configuration.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "PluginConfig", "slug": "/api/models/plugin-config" }, "usedBy": [], "usedByRoots": [ "llm.generation_started", "llm.message_published" ], "fields": [ { "name": "id", "description": "Provider plugin identifier, such as file-parser.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pdf", "description": "PDF annotation or parser configuration selected by the enclosing message.", "presence": "message", "required": false, "requestRequired": false }, { "name": "web", "description": "Web-search configuration for the selected generation plugin.", "presence": "message", "required": false, "requestRequired": false }, { "name": "params", "description": "Additional provider-specific plugin parameters.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "PluginPDFConfig", "title": "PluginPDFConfig", "slug": "/api/models/plugin-pdf-config", "description": "Plugins for pre/post-processing (generic representation)", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "PluginPDFConfig", "slug": "/api/models/plugin-pdf-config" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "engine", "description": "PDF parsing engine selected for the provider plugin.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PluginPDFConfigInput", "title": "PluginPDFConfig", "slug": "/api/models/plugin-pdf-config-input", "description": "Plugins for pre/post-processing (generic representation)", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "PluginPDFConfig", "slug": "/api/models/plugin-pdf-config" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:appendMessage", "conversations:createThread", "conversations:sendMessage", "conversations:sendMessageSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [ "generation-config" ], "fields": [ { "name": "engine", "description": "PDF parsing engine selected for the provider plugin.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PluginPDFConfigWebhook", "title": "PluginPDFConfig", "slug": "/api/models/plugin-pdf-config-webhook", "description": "Plugins for pre/post-processing (generic representation)", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "PluginPDFConfig", "slug": "/api/models/plugin-pdf-config" }, "usedBy": [], "usedByRoots": [ "llm.generation_started", "llm.message_published" ], "fields": [ { "name": "engine", "description": "PDF parsing engine selected for the provider plugin.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PluginWebConfig", "title": "PluginWebConfig", "slug": "/api/models/plugin-web-config", "description": "Provider web-search configuration used to augment a generation request.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "PluginWebConfig", "slug": "/api/models/plugin-web-config" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "engine", "description": "Search engine selected for the provider’s web-search plugin.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxResults", "description": "Maximum web-search result count requested by the plugin.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "searchPrompt", "description": "Instructions supplied to the web-search plugin.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "webSearchOptions", "description": "Options controlling the amount of web-search context requested.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "PluginWebConfigInput", "title": "PluginWebConfig", "slug": "/api/models/plugin-web-config-input", "description": "Provider web-search configuration used to augment a generation request.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "PluginWebConfig", "slug": "/api/models/plugin-web-config" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:appendMessage", "conversations:createThread", "conversations:sendMessage", "conversations:sendMessageSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [ "generation-config" ], "fields": [ { "name": "engine", "description": "Search engine selected for the provider’s web-search plugin.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxResults", "description": "Maximum web-search result count requested by the plugin.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "searchPrompt", "description": "Instructions supplied to the web-search plugin.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "webSearchOptions", "description": "Options controlling the amount of web-search context requested.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "PluginWebConfigWebhook", "title": "PluginWebConfig", "slug": "/api/models/plugin-web-config-webhook", "description": "Provider web-search configuration used to augment a generation request.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "PluginWebConfig", "slug": "/api/models/plugin-web-config" }, "usedBy": [], "usedByRoots": [ "llm.generation_started", "llm.message_published" ], "fields": [ { "name": "engine", "description": "Search engine selected for the provider’s web-search plugin.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "max_results", "description": "Maximum web-search result count requested by the plugin.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "search_prompt", "description": "Instructions supplied to the web-search plugin.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "web_search_options", "description": "Options controlling the amount of web-search context requested.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ProfileQualityRow", "title": "ProfileQualityRow", "slug": "/api/models/profile-quality-row", "description": "Aggregated evaluation results and usage for one agent profile.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "ProfileQualityRow", "slug": "/api/models/profile-quality-row" }, "usedBy": [ "evals:getOverview" ], "usedByRoots": [], "fields": [ { "name": "profileId", "description": "Identifier of the agent profile associated with the generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "traceCount", "description": "Number of traces represented by this summary or group.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "avgEndUserRating", "description": "Average end-user rating reported for the selected generation group.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "avgJudgeScore", "description": "Average automated judge score reported for the selected generation group.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "thumbsDownCount", "description": "Number of negative thumb ratings reported for the selected group.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PromoteAllChangesRequest", "title": "PromoteAllChangesRequest", "slug": "/api/models/promote-all-changes-request", "description": "tenant_id derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "PromoteAllChangesRequest", "slug": "/api/models/promote-all-changes-request" }, "usedBy": [ "notifications:promoteAllChanges" ], "usedByRoots": [], "fields": [ { "name": "changeIds", "description": "Identifiers of notification configuration changes selected for promotion.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "PromoteAllChangesResponse", "title": "PromoteAllChangesResponse", "slug": "/api/models/promote-all-changes-response", "description": "Result payload for promoting selected notification configuration changes between provider environments.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "PromoteAllChangesResponse", "slug": "/api/models/promote-all-changes-response" }, "usedBy": [ "notifications:promoteAllChanges" ], "usedByRoots": [], "fields": [ { "name": "promotedCount", "description": "Number of configuration changes reported promoted.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "promotedIds", "description": "Identifiers of configuration changes reported promoted.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "errors", "description": "Errors reported while processing notification requests.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "PromoteChangeRequest", "title": "PromoteChangeRequest", "slug": "/api/models/promote-change-request", "description": "tenant_id derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "PromoteChangeRequest", "slug": "/api/models/promote-change-request" }, "usedBy": [ "notifications:promoteChange" ], "usedByRoots": [], "fields": [ { "name": "changeId", "description": "Identifier of a pending notification configuration change.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "PromoteChangeResponse", "title": "PromoteChangeResponse", "slug": "/api/models/promote-change-response", "description": "Result payload for promoting a notification configuration change between provider environments.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "PromoteChangeResponse", "slug": "/api/models/promote-change-response" }, "usedBy": [ "notifications:promoteChange" ], "usedByRoots": [], "fields": [ { "name": "success", "description": "Whether the operation reports a successful result.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "productionEntityId", "description": "Identifier assigned to the promoted resource in the target environment.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PromotionError", "title": "PromotionError", "slug": "/api/models/promotion-error", "description": "Failure associated with promotion of one notification configuration change.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "domain-model", "title": "PromotionError", "slug": "/api/models/promotion-error" }, "usedBy": [ "notifications:promoteAllChanges" ], "usedByRoots": [], "fields": [ { "name": "changeId", "description": "Identifier of a pending notification configuration change.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "error", "description": "Error information reported for this operation or item.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PromptDefinition", "title": "PromptDefinition", "slug": "/api/models/prompt-definition", "description": "A prompt definition exposed by an MCP server", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "domain-model", "title": "PromptDefinition", "slug": "/api/models/prompt-definition" }, "usedBy": [ "conversations:mcpGetPrompt", "conversations:mcpListPrompts" ], "usedByRoots": [], "fields": [ { "name": "name", "description": "Name identifying the prompt template on the MCP server.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "title", "description": "Display title of the MCP prompt template.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Description of the MCP prompt template’s purpose.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "parameters", "description": "Parameter definitions accepted by the prompt template.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "template", "description": "Template string; clients may render with parameters.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PromptFragment", "title": "PromptFragment", "slug": "/api/models/prompt-fragment", "description": "Project-scoped reusable prompt-template text. Profiles and other fragments include it with\n`{{template \"fragment_id\" .}}`; variables come from the conversation’s prompt_variables.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "domain-model", "title": "PromptFragment", "slug": "/api/models/prompt-fragment" }, "usedBy": [ "agent-profiles:createPromptFragment", "agent-profiles:getPromptFragment", "agent-profiles:getPromptFragmentSet", "agent-profiles:importAgentProfiles", "agent-profiles:listPromptFragments", "agent-profiles:updatePromptFragment" ], "usedByRoots": [], "fields": [ { "name": "fragmentId", "description": "Stable template name, unique within the project library and used by include actions.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Display name for the reusable prompt fragment.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "content", "description": "Raw template text, supporting `{{.variable}}` placeholders and nested `{{template \"id\" .}}` includes.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PromptFragmentInput", "title": "PromptFragment", "slug": "/api/models/prompt-fragment-input", "description": "Project-scoped reusable prompt-template text. Profiles and other fragments include it with\n`{{template \"fragment_id\" .}}`; variables come from the conversation’s prompt_variables.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "domain-model", "title": "PromptFragment", "slug": "/api/models/prompt-fragment" }, "usedBy": [ "agent-profiles:createPromptFragment", "agent-profiles:updatePromptFragment" ], "usedByRoots": [], "fields": [ { "name": "fragmentId", "description": "Stable template name, unique within the project library and used by include actions.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Display name for the reusable prompt fragment.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "content", "description": "Raw template text, supporting `{{.variable}}` placeholders and nested `{{template \"id\" .}}` includes.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PromptParameter", "title": "PromptParameter", "slug": "/api/models/prompt-parameter", "description": "A parameter used by a prompt template", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "domain-model", "title": "PromptParameter", "slug": "/api/models/prompt-parameter" }, "usedBy": [ "conversations:mcpGetPrompt", "conversations:mcpListPrompts" ], "usedByRoots": [], "fields": [ { "name": "name", "description": "Name used to bind a value to this prompt-template parameter.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Explanation of the value expected for this prompt parameter.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "type", "description": "Free-form type hint, e.g. \"string\", \"number\"", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "required", "description": "Whether the prompt parameter must be supplied by the caller.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PromptTokensDetails", "title": "PromptTokensDetails", "slug": "/api/models/prompt-tokens-details", "description": "Breakdown of prompt token usage by category (input-side cache accounting)", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "PromptTokensDetails", "slug": "/api/models/prompt-tokens-details" }, "usedBy": [ "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "cachedTokens", "description": "Prompt tokens served from cache (cache READ).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "cacheWriteTokens", "description": "Prompt tokens written to cache this call (cache WRITE).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "audioTokens", "description": "Prompt tokens from audio input (multimodal).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "videoTokens", "description": "Prompt tokens from video input (multimodal).", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PromptTokensDetailsInput", "title": "PromptTokensDetails", "slug": "/api/models/prompt-tokens-details-input", "description": "Breakdown of prompt token usage by category (input-side cache accounting)", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "PromptTokensDetails", "slug": "/api/models/prompt-tokens-details" }, "usedBy": [ "conversations:appendMessage", "conversations:sendMessage", "conversations:sendMessageSync" ], "usedByRoots": [], "fields": [ { "name": "cachedTokens", "description": "Prompt tokens served from cache (cache READ).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "cacheWriteTokens", "description": "Prompt tokens written to cache this call (cache WRITE).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "audioTokens", "description": "Prompt tokens from audio input (multimodal).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "videoTokens", "description": "Prompt tokens from video input (multimodal).", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PromptTokensDetailsWebhook", "title": "PromptTokensDetails", "slug": "/api/models/prompt-tokens-details-webhook", "description": "Breakdown of prompt token usage by category (input-side cache accounting)", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "PromptTokensDetails", "slug": "/api/models/prompt-tokens-details" }, "usedBy": [], "usedByRoots": [ "llm.generation_completed", "llm.message_published" ], "fields": [ { "name": "cached_tokens", "description": "Prompt tokens served from cache (cache READ).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "cache_write_tokens", "description": "Prompt tokens written to cache this call (cache WRITE).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "audio_tokens", "description": "Prompt tokens from audio input (multimodal).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "video_tokens", "description": "Prompt tokens from video input (multimodal).", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PromptVariableSpec", "title": "PromptVariableSpec", "slug": "/api/models/prompt-variable-spec", "description": "Declares a variable used by a profile's system-prompt template. Values are supplied\nthrough the conversation's prompt_variables.\n\nWhen creating a conversation with an explicitly selected profile, a\n[`variableSpecs`](/api/models/agent-profile#request-field-variablespecs) entry with\n`required: true` and no nonempty [`defaultValue`](/api/models/prompt-variable-spec#request-field-defaultvalue)\ncauses `MISSING_REQUIRED_PROMPT_VARIABLES` if the variable is missing. Supply the\nvalue at creation. This validation is not repeated for each send or queued turn.\n\nSet intended values explicitly even when the spec declares a default. A nonempty\n`defaultValue` suppresses the creation-time missing-required error but is not\nautomatically inserted into the rendered prompt.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "domain-model", "title": "PromptVariableSpec", "slug": "/api/models/prompt-variable-spec" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile" ], "usedByRoots": [], "fields": [ { "name": "name", "description": "Variable name referenced by the profile’s system-prompt template.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Console hint + caller documentation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "required", "description": "Whether a value is required for a profile explicitly selected at conversation creation.\nThe current validation does not run for every send or queued turn.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "defaultValue", "description": "A nonempty value suppresses the creation-time missing-required error. It is not\nautomatically inserted into the rendered prompt; supply intended values explicitly.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "type", "description": "\"\" preserves the missing→empty behavior", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "PromptVariableSpecInput", "title": "PromptVariableSpec", "slug": "/api/models/prompt-variable-spec-input", "description": "Declares a variable used by a profile's system-prompt template. Values are supplied\nthrough the conversation's prompt_variables.\n\nWhen creating a conversation with an explicitly selected profile, a\n[`variableSpecs`](/api/models/agent-profile#request-field-variablespecs) entry with\n`required: true` and no nonempty [`defaultValue`](/api/models/prompt-variable-spec#request-field-defaultvalue)\ncauses `MISSING_REQUIRED_PROMPT_VARIABLES` if the variable is missing. Supply the\nvalue at creation. This validation is not repeated for each send or queued turn.\n\nSet intended values explicitly even when the spec declares a default. A nonempty\n`defaultValue` suppresses the creation-time missing-required error but is not\nautomatically inserted into the rendered prompt.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "domain-model", "title": "PromptVariableSpec", "slug": "/api/models/prompt-variable-spec" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:updateAgentProfile" ], "usedByRoots": [], "fields": [ { "name": "name", "description": "Variable name referenced by the profile’s system-prompt template.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Console hint + caller documentation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "required", "description": "Whether a value is required for a profile explicitly selected at conversation creation.\nThe current validation does not run for every send or queued turn.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "defaultValue", "description": "A nonempty value suppresses the creation-time missing-required error. It is not\nautomatically inserted into the rendered prompt; supply intended values explicitly.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "type", "description": "\"\" preserves the missing→empty behavior", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ProtobufEmpty", "title": "Empty", "slug": "/api/models/protobuf-empty", "description": "An empty JSON object.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "shared", "role": "operation-envelope", "title": "Empty", "slug": "/api/models/protobuf-empty" }, "usedBy": [ "notifications:updateGlobalPreference", "notifications:updateWorkflowPreference" ], "usedByRoots": [], "fields": [] }, { "schemaName": "ProviderInfo", "title": "ProviderInfo", "slug": "/api/models/provider-info", "description": "Configured notification provider and its integration identifier and active state.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "domain-model", "title": "ProviderInfo", "slug": "/api/models/provider-info" }, "usedBy": [ "notifications:getProviders" ], "usedByRoots": [], "fields": [ { "name": "provider", "description": "Notification delivery provider being configured or reported.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "integrationId", "description": "Identifier of the provider integration in Novu.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "active", "description": "Whether the resource is marked active.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ProviderMaxPrice", "title": "ProviderMaxPrice", "slug": "/api/models/provider-max-price", "description": "Routing / provider preferences (generic superset)", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "ProviderMaxPrice", "slug": "/api/models/provider-max-price" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "prompt", "description": "$/1M prompt tokens.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "completion", "description": "$/1M completion tokens.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "request", "description": "Maximum provider cost allowed per request, in US dollars.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "image", "description": "Maximum provider cost allowed per image, in US dollars.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "audio", "description": "$/1M audio tokens.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ProviderMaxPriceInput", "title": "ProviderMaxPrice", "slug": "/api/models/provider-max-price-input", "description": "Routing / provider preferences (generic superset)", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "ProviderMaxPrice", "slug": "/api/models/provider-max-price" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:appendMessage", "conversations:createThread", "conversations:sendMessage", "conversations:sendMessageSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [ "generation-config" ], "fields": [ { "name": "prompt", "description": "$/1M prompt tokens.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "completion", "description": "$/1M completion tokens.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "request", "description": "Maximum provider cost allowed per request, in US dollars.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "image", "description": "Maximum provider cost allowed per image, in US dollars.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "audio", "description": "$/1M audio tokens.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ProviderMaxPriceWebhook", "title": "ProviderMaxPrice", "slug": "/api/models/provider-max-price-webhook", "description": "Routing / provider preferences (generic superset)", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "ProviderMaxPrice", "slug": "/api/models/provider-max-price" }, "usedBy": [], "usedByRoots": [ "llm.generation_started", "llm.message_published" ], "fields": [ { "name": "prompt", "description": "$/1M prompt tokens.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "completion", "description": "$/1M completion tokens.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "request", "description": "Maximum provider cost allowed per request, in US dollars.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "image", "description": "Maximum provider cost allowed per image, in US dollars.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "audio", "description": "$/1M audio tokens.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ProviderPreferences", "title": "ProviderPreferences", "slug": "/api/models/provider-preferences", "description": "Routing preferences restricting and ordering the model providers eligible for a request.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "ProviderPreferences", "slug": "/api/models/provider-preferences" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "order", "description": "Preferred ordering of model providers for routing.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "allowFallbacks", "description": "Whether provider routing may fall back beyond the preferred order.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "requireParameters", "description": "Whether routing requires providers to support the requested parameters.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "dataCollection", "description": "Provider data-collection preference used when routing the request.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "zdr", "description": "Whether routing requests providers offering zero data retention.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "only", "description": "Provider identifiers allowed by the routing preference.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "ignore", "description": "Provider identifiers excluded by the routing preference.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "quantizations", "description": "Model quantization formats allowed by the routing preference.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "sort", "description": "Metric used to order eligible model providers.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxPrice", "description": "Upper price bounds used when selecting a model provider.", "presence": "message", "required": false, "requestRequired": false }, { "name": "enforceDistillableText", "description": "Embeddings: enforce distillable text.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "preferredMinThroughput", "description": "Deprioritize providers below this throughput (tokens/sec).\nDoes not exclude — just pushes to end of preference list.", "presence": "message", "required": false, "requestRequired": false }, { "name": "preferredMaxLatency", "description": "Deprioritize providers above this latency (ms).", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ProviderPreferencesInput", "title": "ProviderPreferences", "slug": "/api/models/provider-preferences-input", "description": "Routing preferences restricting and ordering the model providers eligible for a request.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "ProviderPreferences", "slug": "/api/models/provider-preferences" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:appendMessage", "conversations:createThread", "conversations:sendMessage", "conversations:sendMessageSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [ "generation-config" ], "fields": [ { "name": "order", "description": "Preferred ordering of model providers for routing.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "allowFallbacks", "description": "Whether provider routing may fall back beyond the preferred order.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "requireParameters", "description": "Whether routing requires providers to support the requested parameters.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "dataCollection", "description": "Provider data-collection preference used when routing the request.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "zdr", "description": "Whether routing requests providers offering zero data retention.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "only", "description": "Provider identifiers allowed by the routing preference.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "ignore", "description": "Provider identifiers excluded by the routing preference.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "quantizations", "description": "Model quantization formats allowed by the routing preference.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "sort", "description": "Metric used to order eligible model providers.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxPrice", "description": "Upper price bounds used when selecting a model provider.", "presence": "message", "required": false, "requestRequired": false }, { "name": "enforceDistillableText", "description": "Embeddings: enforce distillable text.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "preferredMinThroughput", "description": "Deprioritize providers below this throughput (tokens/sec).\nDoes not exclude — just pushes to end of preference list.", "presence": "message", "required": false, "requestRequired": false }, { "name": "preferredMaxLatency", "description": "Deprioritize providers above this latency (ms).", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ProviderPreferencesWebhook", "title": "ProviderPreferences", "slug": "/api/models/provider-preferences-webhook", "description": "Routing preferences restricting and ordering the model providers eligible for a request.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "ProviderPreferences", "slug": "/api/models/provider-preferences" }, "usedBy": [], "usedByRoots": [ "llm.generation_started", "llm.message_published" ], "fields": [ { "name": "order", "description": "Preferred ordering of model providers for routing.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "allow_fallbacks", "description": "Whether provider routing may fall back beyond the preferred order.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "require_parameters", "description": "Whether routing requires providers to support the requested parameters.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "data_collection", "description": "Provider data-collection preference used when routing the request.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "zdr", "description": "Whether routing requests providers offering zero data retention.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "only", "description": "Provider identifiers allowed by the routing preference.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "ignore", "description": "Provider identifiers excluded by the routing preference.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "quantizations", "description": "Model quantization formats allowed by the routing preference.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "sort", "description": "Metric used to order eligible model providers.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "max_price", "description": "Upper price bounds used when selecting a model provider.", "presence": "message", "required": false, "requestRequired": false }, { "name": "enforce_distillable_text", "description": "Embeddings: enforce distillable text.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "preferred_min_throughput", "description": "Deprioritize providers below this throughput (tokens/sec).\nDoes not exclude — just pushes to end of preference list.", "presence": "message", "required": false, "requestRequired": false }, { "name": "preferred_max_latency", "description": "Deprioritize providers above this latency (ms).", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "PutSecretRequest", "title": "PutSecretRequest", "slug": "/api/models/put-secret-request", "description": "Inputs for writing a project secret and its metadata.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "secrets", "role": "operation-envelope", "title": "PutSecretRequest", "slug": "/api/models/put-secret-request" }, "usedBy": [ "secrets:putSecret" ], "usedByRoots": [], "fields": [ { "name": "name", "description": "Name identifying the secret within its project.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "value", "description": "Secret value, limited to 64 KiB of UTF-8 bytes. Binary material is supplied as base64 by\ncaller convention. Read operations return metadata without the secret value.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "description", "description": "Human-readable explanation of the secret.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "labels", "description": "Free-form labels used to organize and identify secrets.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "PutSecretResponse", "title": "PutSecretResponse", "slug": "/api/models/put-secret-response", "description": "Stored metadata returned after writing a project secret; the secret value is not returned.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "secrets", "role": "operation-envelope", "title": "PutSecretResponse", "slug": "/api/models/put-secret-response" }, "usedBy": [ "secrets:putSecret" ], "usedByRoots": [], "fields": [ { "name": "metadata", "description": "Stored secret metadata; the secret value is not returned.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "RateMessageRequest", "title": "RateMessageRequest", "slug": "/api/models/rate-message-request", "description": "Rate an assistant message in a thread. The rater is derived server-side\nfrom the verified request headers — never supplied by the client body.\nFor THUMB feedback, thumb_up supplies the choice and rating must be zero or omitted.\nFor SCALE feedback, rating must be from 1 through 10.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "RateMessageRequest", "slug": "/api/models/rate-message-request" }, "usedBy": [ "conversations:rateMessage" ], "usedByRoots": [], "fields": [ { "name": "conversationKey", "description": "Identifier of the conversation thread.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "messageSequence", "description": "Per-conversation sequence number of the assistant-generated message to rate.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "kind", "description": "Rating representation used to interpret the thumb or scale value.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "thumbUp", "description": "Positive when true and negative when false; used for THUMB feedback.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "rating", "description": "Numeric quality rating for SCALE feedback; the scale endpoints mean poor and excellent.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "reason", "description": "Optional explanation for the rating.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "RateMessageResponse", "title": "RateMessageResponse", "slug": "/api/models/rate-message-response", "description": "Result of recording the caller’s rating on a conversation message.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "RateMessageResponse", "slug": "/api/models/rate-message-response" }, "usedBy": [ "conversations:rateMessage" ], "usedByRoots": [], "fields": [ { "name": "ratedMessage", "description": "The rated message with the full (all-rater) feedback list applied", "presence": "message", "required": false, "requestRequired": false }, { "name": "isUpdate", "description": "True when this replaced the caller's previous rating on this message", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ReasoningOptions", "title": "ReasoningOptions", "slug": "/api/models/reasoning-options", "description": "Reasoning options\n\nSupported 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.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "ReasoningOptions", "slug": "/api/models/reasoning-options" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "effort", "description": "Requested model reasoning effort.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxTokens", "description": "Maximum reasoning-token count requested from the model provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "exclude", "description": "Whether the provider should omit reasoning content from its response.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "includeReasoningHistory", "description": "When true (default), reasoning content from previous turns is included\nin multi-turn requests to enable provider continuity.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ReasoningOptionsInput", "title": "ReasoningOptions", "slug": "/api/models/reasoning-options-input", "description": "Reasoning options\n\nSupported 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.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "ReasoningOptions", "slug": "/api/models/reasoning-options" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:appendMessage", "conversations:createThread", "conversations:sendMessage", "conversations:sendMessageSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [ "generation-config" ], "fields": [ { "name": "effort", "description": "Requested model reasoning effort.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxTokens", "description": "Maximum reasoning-token count requested from the model provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "exclude", "description": "Whether the provider should omit reasoning content from its response.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "includeReasoningHistory", "description": "When true (default), reasoning content from previous turns is included\nin multi-turn requests to enable provider continuity.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ReasoningOptionsWebhook", "title": "ReasoningOptions", "slug": "/api/models/reasoning-options-webhook", "description": "Reasoning options\n\nSupported 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.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "ReasoningOptions", "slug": "/api/models/reasoning-options" }, "usedBy": [], "usedByRoots": [ "llm.generation_started", "llm.message_published" ], "fields": [ { "name": "effort", "description": "Requested model reasoning effort.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "max_tokens", "description": "Maximum reasoning-token count requested from the model provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "exclude", "description": "Whether the provider should omit reasoning content from its response.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "include_reasoning_history", "description": "When true (default), reasoning content from previous turns is included\nin multi-turn requests to enable provider continuity.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "RecordDatasetRunRequest", "title": "RecordDatasetRunRequest", "slug": "/api/models/record-dataset-run-request", "description": "Records a dataset run. This is the RPC that motivated a public eval surface:\na harness executes a run and has to be able to post it, and until now the\nonly route in was the console's own admin edge.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "RecordDatasetRunRequest", "slug": "/api/models/record-dataset-run-request" }, "usedBy": [ "evals:recordDatasetRun" ], "usedByRoots": [], "fields": [ { "name": "datasetId", "description": "Identifier of the evaluation dataset.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "runName", "description": "Name assigned to the evaluation dataset run.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "profileRevisionHash", "description": "Content hash identifying the agent profile revision recorded for the dataset run.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadataJson", "description": "Additional evaluation metadata serialized as JSON text.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Human-readable explanation of the evaluation record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "items", "description": "Dataset-item and generated-trace pairs included in the run.", "presence": "collection", "required": true, "requestRequired": true } ] }, { "schemaName": "RecordDatasetRunResponse", "title": "RecordDatasetRunResponse", "slug": "/api/models/record-dataset-run-response", "description": "Result of recording a named run against an evaluation dataset.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "RecordDatasetRunResponse", "slug": "/api/models/record-dataset-run-response" }, "usedBy": [ "evals:recordDatasetRun" ], "usedByRoots": [], "fields": [ { "name": "runId", "description": "Identifier of the recorded evaluation dataset run.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "RecordingBucketConfig", "title": "RecordingBucketConfig", "slug": "/api/models/recording-bucket-config", "description": "Storage configs\nObject-storage destination and access settings for Daily recordings.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "voice-media", "role": "domain-model", "title": "RecordingBucketConfig", "slug": "/api/models/recording-bucket-config" }, "usedBy": [ "conversations:createDailySession" ], "usedByRoots": [], "fields": [ { "name": "bucketName", "description": "Object-storage bucket used for Daily recordings or transcriptions.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "bucketRegion", "description": "Region containing the Daily recording or transcription bucket.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "assumeRoleArn", "description": "Role ARN Daily uses when accessing the storage bucket.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "allowApiAccess", "description": "Whether Daily API access to bucket content is enabled.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "allowStreamingFromBucket", "description": "Whether streaming directly from the recording bucket is enabled.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "RecordingBucketConfigInput", "title": "RecordingBucketConfig", "slug": "/api/models/recording-bucket-config-input", "description": "Storage configs\nObject-storage destination and access settings for Daily recordings.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "voice-media", "role": "domain-model", "title": "RecordingBucketConfig", "slug": "/api/models/recording-bucket-config" }, "usedBy": [ "conversations:createDailySession" ], "usedByRoots": [], "fields": [ { "name": "bucketName", "description": "Object-storage bucket used for Daily recordings or transcriptions.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "bucketRegion", "description": "Region containing the Daily recording or transcription bucket.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "assumeRoleArn", "description": "Role ARN Daily uses when accessing the storage bucket.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "allowApiAccess", "description": "Whether Daily API access to bucket content is enabled.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "allowStreamingFromBucket", "description": "Whether streaming directly from the recording bucket is enabled.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "RecordScoreRequest", "title": "RecordScoreRequest", "slug": "/api/models/record-score-request", "description": "Inputs for recording an evaluation score. Supply exactly one target address: target_id,\nmessage_id, or both conversation_id and source_user_message_id. Authorship comes from the\nauthenticated caller; the score source is assigned for this reviewer operation.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "RecordScoreRequest", "slug": "/api/models/record-score-request" }, "usedBy": [ "evals:recordScore" ], "usedByRoots": [], "fields": [ { "name": "targetType", "description": "Kind of evaluation object targeted by the score or annotation.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "targetId", "description": "Not required — a caller may address by message or by turn instead.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Name identifying the scoring dimension recorded for the evaluation target.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "dataType", "description": "Value type used to interpret the evaluation score.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "numericValue", "description": "Numeric score value for a numeric score configuration.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "stringValue", "description": "Category value for a categorical evaluation score.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "booleanValue", "description": "Boolean value for a boolean evaluation score.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "textValue", "description": "Free-text value for a text evaluation score.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "comment", "description": "Explanatory note accompanying the evaluation score.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "configId", "description": "Score configuration selected from ListScoreConfigs. Required for this reviewer operation;\na missing configuration is rejected.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "profileId", "description": "Identifier of the agent profile associated with the operation or generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "messageId", "description": "Identifier of the conversation message to score. Supply this instead of target_id or a\nconversation_id and source_user_message_id pair.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "conversationId", "description": "Identifier of the conversation associated with the evaluation record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sourceUserMessageId", "description": "Identifier of the user message that originated the evaluated generation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "RecordScoreResponse", "title": "RecordScoreResponse", "slug": "/api/models/record-score-response", "description": "Result of recording a score attached to an evaluation object.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "RecordScoreResponse", "slug": "/api/models/record-score-response" }, "usedBy": [ "evals:recordScore" ], "usedByRoots": [], "fields": [ { "name": "scoreId", "description": "Identifier of the recorded evaluation score.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "targetId", "description": "Resolved evaluation-object identifier, returned so a caller that addressed a message can use\nthe object identity in later requests.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "targetType", "description": "Kind of evaluation object targeted by the score or annotation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "RegisterPushDeviceRequest", "title": "RegisterPushDeviceRequest", "slug": "/api/models/register-push-device-request", "description": "Caller user_id derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "RegisterPushDeviceRequest", "slug": "/api/models/register-push-device-request" }, "usedBy": [ "notifications:registerPushDevice" ], "usedByRoots": [], "fields": [ { "name": "fcmToken", "description": "Firebase Cloud Messaging token identifying the push delivery target.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "platform", "description": "Device platform associated with the registered push token.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "deviceId", "description": "Client-provided identifier of the device being registered.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "RegisterPushDeviceResponse", "title": "RegisterPushDeviceResponse", "slug": "/api/models/register-push-device-response", "description": "Result payload for registering an FCM token as a user’s push notification delivery target.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "RegisterPushDeviceResponse", "slug": "/api/models/register-push-device-response" }, "usedBy": [ "notifications:registerPushDevice" ], "usedByRoots": [], "fields": [ { "name": "success", "description": "Whether the operation reports a successful result.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "subscriberId", "description": "Identifier of the notification subscriber.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "RegisterUploadedFileRequest", "title": "RegisterUploadedFileRequest", "slug": "/api/models/register-uploaded-file-request", "description": "RegisterUploadedFileRequest completes the signed-URL upload flow (step 3 of 3):\nafter PUTting bytes to the URL from GenerateUploadUrl, register the object so it\nbecomes visible to ListFiles/GetFileMetadata/GenerateDownloadUrl.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "RegisterUploadedFileRequest", "slug": "/api/models/register-uploaded-file-request" }, "usedBy": [ "storage:registerUploadedFile" ], "usedByRoots": [], "fields": [ { "name": "fileId", "description": "file_id returned by GenerateUploadUrl (32 lowercase hex chars). The GCS key is\nrecomputed server-side from the caller-scoped folder_path + file_id, so a\ncaller can only ever register objects under its own prefix.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "folderPath", "description": "Must match the folder_path passed to GenerateUploadUrl.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "fileName", "description": "File name to use within the selected folder.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "metadata", "description": "Additional attributes associated with the resource.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "tags", "description": "Labels associated with the resource for organization or filtering.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "RegisterUploadedFileResponse", "title": "RegisterUploadedFileResponse", "slug": "/api/models/register-uploaded-file-response", "description": "Result payload for recording metadata for a file uploaded directly to storage.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "RegisterUploadedFileResponse", "slug": "/api/models/register-uploaded-file-response" }, "usedBy": [ "storage:registerUploadedFile" ], "usedByRoots": [], "fields": [ { "name": "file", "description": "Metadata for the file affected or retrieved by the operation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "registered", "description": "true when newly registered; false when the file_id was already registered\n(idempotent retry — the existing FileInfo is returned unchanged).", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "Relation", "title": "Memory relation", "slug": "/api/memory/models/relation", "description": "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.\n\nRelationships may be absent even when memory records are returned. They describe extracted associations, not verified facts, ownership permissions or lifecycle transitions.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "memory-knowledge", "role": "domain-model", "title": "Memory relation", "slug": "/api/memory/models/relation" }, "usedBy": [ "conversations:searchMemories" ], "usedByRoots": [], "fields": [ { "name": "source", "description": "Source entity name.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "relationship", "description": "Open string describing the relationship. Example labels do not restrict the allowed values.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "destination", "description": "Destination entity name.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "RelationReference", "title": "RelationReference", "slug": "/api/models/relation-reference", "description": "A graph relationship retrieved and included in generation context.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "memory-knowledge", "role": "domain-model", "title": "RelationReference", "slug": "/api/models/relation-reference" }, "usedBy": [ "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "source", "description": "Source entity of the memory graph relationship.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "relationship", "description": "Relationship label connecting the source and destination entities.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "destination", "description": "Destination entity of the memory graph relationship.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "RelationReferenceInput", "title": "RelationReference", "slug": "/api/models/relation-reference-input", "description": "A graph relationship retrieved and included in generation context.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "memory-knowledge", "role": "domain-model", "title": "RelationReference", "slug": "/api/models/relation-reference" }, "usedBy": [ "conversations:appendMessage", "conversations:sendMessage", "conversations:sendMessageSync" ], "usedByRoots": [], "fields": [ { "name": "source", "description": "Source entity of the memory graph relationship.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "relationship", "description": "Relationship label connecting the source and destination entities.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "destination", "description": "Destination entity of the memory graph relationship.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "RelationReferenceWebhook", "title": "RelationReference", "slug": "/api/models/relation-reference-webhook", "description": "A graph relationship retrieved and included in generation context.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "memory-knowledge", "role": "domain-model", "title": "RelationReference", "slug": "/api/models/relation-reference" }, "usedBy": [], "usedByRoots": [ "llm.message_published" ], "fields": [ { "name": "source", "description": "Source entity of the memory graph relationship.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "relationship", "description": "Relationship label connecting the source and destination entities.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "destination", "description": "Destination entity of the memory graph relationship.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "RemoveSubscribersFromTopicRequest", "title": "RemoveSubscribersFromTopicRequest", "slug": "/api/models/remove-subscribers-from-topic-request", "description": "Inputs for removing selected users from a notification topic’s recipient membership.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "RemoveSubscribersFromTopicRequest", "slug": "/api/models/remove-subscribers-from-topic-request" }, "usedBy": [ "notifications:removeSubscribersFromTopic" ], "usedByRoots": [], "fields": [ { "name": "topicKey", "description": "Caller-facing key identifying a notification topic.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "userIds", "description": "Identifiers of the users selected by the operation.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "RemoveSubscribersFromTopicResponse", "title": "RemoveSubscribersFromTopicResponse", "slug": "/api/models/remove-subscribers-from-topic-response", "description": "Result payload for removing selected users from a notification topic’s recipient membership.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "RemoveSubscribersFromTopicResponse", "slug": "/api/models/remove-subscribers-from-topic-response" }, "usedBy": [ "notifications:removeSubscribersFromTopic" ], "usedByRoots": [], "fields": [ { "name": "result", "description": "Accepted and failed subscriber counts with per-subscriber errors from the membership change.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "Resource", "title": "Resource", "slug": "/api/models/resource", "description": "A resource exposed by an MCP server", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "domain-model", "title": "Resource", "slug": "/api/models/resource" }, "usedBy": [ "conversations:mcpListResources", "conversations:mcpReadResource" ], "usedByRoots": [], "fields": [ { "name": "uri", "description": "Canonical URI for the resource.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "title", "description": "Display title of the MCP resource.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Description of the content available from the MCP resource.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "mimeType", "description": "Media type of the content exposed by the MCP resource.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "content", "description": "Optional embedded content.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "annotations", "description": "Optional annotations/metadata.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "lastModified", "description": "Time when this resource was last modified.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ResponseFormat", "title": "ResponseFormat", "slug": "/api/models/response-format", "description": "Structured response control\n\nWhen 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.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "ResponseFormat", "slug": "/api/models/response-format" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "jsonObject", "description": "Whether the model provider is requested to return a valid JSON object.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "jsonSchema", "description": "JSON Schema describing the requested structured model output.", "presence": "message", "required": false, "requestRequired": false }, { "name": "schemaName", "description": "Human-readable name of the structured-output schema, included in structured-message metadata\nand in the provider request’s json_schema.name.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "validate", "description": "Enable server-side validation of the response against json_schema.\nDefault: true when json_schema is set (applied in Go when not explicitly set).", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "maxValidationRetries", "description": "Maximum retries when server-side validation fails.\nDefault: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "responseHealing", "description": "Enable response healing for structured JSON output. Defaults to enabled for non-streaming\nrequests with json_schema unless explicitly disabled.", "presence": "explicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ResponseFormatInput", "title": "ResponseFormat", "slug": "/api/models/response-format-input", "description": "Structured response control\n\nWhen 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.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "ResponseFormat", "slug": "/api/models/response-format" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:appendMessage", "conversations:createThread", "conversations:sendMessage", "conversations:sendMessageSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [ "generation-config" ], "fields": [ { "name": "jsonObject", "description": "Whether the model provider is requested to return a valid JSON object.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "jsonSchema", "description": "JSON Schema describing the requested structured model output.", "presence": "message", "required": false, "requestRequired": false }, { "name": "schemaName", "description": "Human-readable name of the structured-output schema, included in structured-message metadata\nand in the provider request’s json_schema.name.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "validate", "description": "Enable server-side validation of the response against json_schema.\nDefault: true when json_schema is set (applied in Go when not explicitly set).", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "maxValidationRetries", "description": "Maximum retries when server-side validation fails.\nDefault: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "responseHealing", "description": "Enable response healing for structured JSON output. Defaults to enabled for non-streaming\nrequests with json_schema unless explicitly disabled.", "presence": "explicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ResponseFormatWebhook", "title": "ResponseFormat", "slug": "/api/models/response-format-webhook", "description": "Structured response control\n\nWhen 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.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "ResponseFormat", "slug": "/api/models/response-format" }, "usedBy": [], "usedByRoots": [ "llm.generation_started", "llm.message_published" ], "fields": [ { "name": "json_object", "description": "Whether the model provider is requested to return a valid JSON object.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "json_schema", "description": "JSON Schema describing the requested structured model output.", "presence": "message", "required": false, "requestRequired": false }, { "name": "schema_name", "description": "Human-readable name of the structured-output schema, included in structured-message metadata\nand in the provider request’s json_schema.name.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "validate", "description": "Enable server-side validation of the response against json_schema.\nDefault: true when json_schema is set (applied in Go when not explicitly set).", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "max_validation_retries", "description": "Maximum retries when server-side validation fails.\nDefault: 1 when not set. Set to 0 to disable retry (fail immediately on invalid output).", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "response_healing", "description": "Enable response healing for structured JSON output. Defaults to enabled for non-streaming\nrequests with json_schema unless explicitly disabled.", "presence": "explicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ResumeJobRequest", "title": "ResumeJobRequest", "slug": "/api/models/resume-job-request", "description": "Inputs for resuming a scheduled job and its trigger settings.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "scheduling", "role": "operation-envelope", "title": "ResumeJobRequest", "slug": "/api/models/resume-job-request" }, "usedBy": [ "scheduled-jobs:resumeJob" ], "usedByRoots": [], "fields": [ { "name": "scheduleId", "description": "Identifier of the scheduled job.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "externalId", "description": "Caller-assigned correlation identifier for the scheduled job.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "RetryConfig", "title": "RetryConfig", "slug": "/api/models/retry-config", "description": "Retry strategy, attempt limit, and interval for failed webhook deliveries.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "webhooks", "role": "domain-model", "title": "RetryConfig", "slug": "/api/models/retry-config" }, "usedBy": [ "webhooks:createWebhookEndpoint", "webhooks:createWebhookSubscription", "webhooks:listWebhookSubscriptions" ], "usedByRoots": [], "fields": [ { "name": "strategy", "description": "Webhook retry strategy selected in the provider configuration.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "retryCount", "description": "Maximum retry count configured for webhook delivery.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "intervalSeconds", "description": "Delay between webhook delivery retries, in seconds.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "RetryInfo", "title": "RetryInfo", "slug": "/api/models/retry-info", "description": "Retry guidance for transient errors.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "RetryInfo", "slug": "/api/models/retry-info" }, "usedBy": [ "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "retryDelayMs", "description": "Suggested minimum delay before retrying, in milliseconds.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "RetryInfoInput", "title": "RetryInfo", "slug": "/api/models/retry-info-input", "description": "Retry guidance for transient errors.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "RetryInfo", "slug": "/api/models/retry-info" }, "usedBy": [ "conversations:submitClientToolResults", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "retryDelayMs", "description": "Suggested minimum delay before retrying, in milliseconds.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "RetryInfoWebhook", "title": "RetryInfo", "slug": "/api/models/retry-info-webhook", "description": "Retry guidance for transient errors.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "RetryInfo", "slug": "/api/models/retry-info" }, "usedBy": [], "usedByRoots": [ "llm.generation_completed" ], "fields": [ { "name": "retry_delay_ms", "description": "Suggested minimum delay before retrying, in milliseconds.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "RetryPolicy", "title": "RetryPolicy", "slug": "/api/models/retry-policy", "description": "RetryPolicy controls how failed executions are retried.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "scheduling", "role": "domain-model", "title": "RetryPolicy", "slug": "/api/models/retry-policy" }, "usedBy": [ "scheduled-jobs:createJob", "scheduled-jobs:getJob", "scheduled-jobs:listJobs", "scheduled-jobs:pauseJob", "scheduled-jobs:resumeJob", "scheduled-jobs:updateJob" ], "usedByRoots": [], "fields": [ { "name": "maxAttempts", "description": "Maximum delivery attempts (including the initial attempt). Default 10.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "initialBackoffMs", "description": "Initial backoff before the first retry, in milliseconds. Default 5000.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxBackoffMs", "description": "Maximum backoff cap, in milliseconds. Default 1800000 (30 min).", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "RetryPolicyInput", "title": "RetryPolicy", "slug": "/api/models/retry-policy-input", "description": "RetryPolicy controls how failed executions are retried.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "scheduling", "role": "domain-model", "title": "RetryPolicy", "slug": "/api/models/retry-policy" }, "usedBy": [ "scheduled-jobs:createJob", "scheduled-jobs:updateJob" ], "usedByRoots": [], "fields": [ { "name": "maxAttempts", "description": "Maximum delivery attempts (including the initial attempt). Default 10.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "initialBackoffMs", "description": "Initial backoff before the first retry, in milliseconds. Default 5000.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxBackoffMs", "description": "Maximum backoff cap, in milliseconds. Default 1800000 (30 min).", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "RetryWebhookDeliveryRequest", "title": "RetryWebhookDeliveryRequest", "slug": "/api/models/retry-webhook-delivery-request", "description": "Inputs for requesting another attempt for a tenant webhook delivery.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "webhooks", "role": "operation-envelope", "title": "RetryWebhookDeliveryRequest", "slug": "/api/models/retry-webhook-delivery-request" }, "usedBy": [ "webhooks:retryWebhookDelivery" ], "usedByRoots": [], "fields": [ { "name": "deliveryId", "description": "Identifier of the webhook delivery to inspect or retry.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "RetryWebhookDeliveryResponse", "title": "RetryWebhookDeliveryResponse", "slug": "/api/models/retry-webhook-delivery-response", "description": "Result payload for requesting another attempt for a tenant webhook delivery.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "webhooks", "role": "operation-envelope", "title": "RetryWebhookDeliveryResponse", "slug": "/api/models/retry-webhook-delivery-response" }, "usedBy": [ "webhooks:retryWebhookDelivery" ], "usedByRoots": [], "fields": [ { "name": "delivery", "description": "Webhook delivery record returned by the operation.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "RevertInboxActionRequest", "title": "RevertInboxActionRequest", "slug": "/api/models/revert-inbox-action-request", "description": "Inputs for undoing completion of an inbox notification’s action.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "RevertInboxActionRequest", "slug": "/api/models/revert-inbox-action-request" }, "usedBy": [ "notifications:revertInboxAction" ], "usedByRoots": [], "fields": [ { "name": "notificationId", "description": "Identifier of the notification whose inbox entry is being modified.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "actionType", "description": "Action selector used when completing or reverting an inbox action.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "RevertInboxActionResponse", "title": "RevertInboxActionResponse", "slug": "/api/models/revert-inbox-action-response", "description": "Result payload for undoing completion of an inbox notification’s action.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "RevertInboxActionResponse", "slug": "/api/models/revert-inbox-action-response" }, "usedBy": [ "notifications:revertInboxAction" ], "usedByRoots": [], "fields": [ { "name": "status", "description": "Status reported by the notification provider.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "RpcError", "title": "RpcError", "slug": "/api/models/rpc-error", "description": "Standardized error payload following google.rpc.Status (AIP-193).\nUsed across all response messages and event payloads.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "RpcError", "slug": "/api/models/rpc-error" }, "usedBy": [ "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "code", "description": "Machine-readable error code. Clients switch on this field.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "message", "description": "Human-readable error description. Intended for developers, not end users.\nMust not be parsed programmatically — use code and details instead.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "isTerminal", "description": "Whether this error is terminal (non-retryable). When true, repeating the\nsame request will produce the same error. When false, transient condition\nmay resolve on retry.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "details", "description": "Structured error details. At most one of each detail type.\nFollows google.rpc.Status details pattern but uses concrete types\ninstead of google.protobuf.Any for type safety and codegen.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "RpcErrorInput", "title": "RpcError", "slug": "/api/models/rpc-error-input", "description": "Standardized error payload following google.rpc.Status (AIP-193).\nUsed across all response messages and event payloads.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "RpcError", "slug": "/api/models/rpc-error" }, "usedBy": [ "conversations:submitClientToolResults", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "code", "description": "Machine-readable error code. Clients switch on this field.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "message", "description": "Human-readable error description. Intended for developers, not end users.\nMust not be parsed programmatically — use code and details instead.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "isTerminal", "description": "Whether this error is terminal (non-retryable). When true, repeating the\nsame request will produce the same error. When false, transient condition\nmay resolve on retry.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "details", "description": "Structured error details. At most one of each detail type.\nFollows google.rpc.Status details pattern but uses concrete types\ninstead of google.protobuf.Any for type safety and codegen.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "RpcErrorWebhook", "title": "RpcError", "slug": "/api/models/rpc-error-webhook", "description": "Standardized error payload following google.rpc.Status (AIP-193).\nUsed across all response messages and event payloads.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "RpcError", "slug": "/api/models/rpc-error" }, "usedBy": [], "usedByRoots": [ "llm.generation_completed" ], "fields": [ { "name": "code", "description": "Machine-readable error code. Clients switch on this field.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "message", "description": "Human-readable error description. Intended for developers, not end users.\nMust not be parsed programmatically — use code and details instead.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "is_terminal", "description": "Whether this error is terminal (non-retryable). When true, repeating the\nsame request will produce the same error. When false, transient condition\nmay resolve on retry.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "details", "description": "Structured error details. At most one of each detail type.\nFollows google.rpc.Status details pattern but uses concrete types\ninstead of google.protobuf.Any for type safety and codegen.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "Schedule", "title": "Schedule", "slug": "/api/models/schedule", "description": "Schedule is the canonical representation of a scheduled job.\n\nCreating any schedule type returns the `Schedule` resource directly, with the same shape used by get, pause and resume operations.\n\n[`triggerCount`](/api/models/schedule#response-field-triggercount): Cumulative firings.\n\n[`failureCount`](/api/models/schedule#response-field-failurecount): Cumulative failed first attempts; a later successful retry does not erase the earlier failure.\n\n[`consecutiveFailureCount`](/api/models/schedule#response-field-consecutivefailurecount): Current sequence of failed firings; a successful attempt resets it. This counter drives auto-pause.\n\nZero-valued counters can be omitted. Nonzero 64-bit counters are decimal JSON strings; preserve their integer precision.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "scheduling", "role": "domain-model", "title": "Schedule", "slug": "/api/models/schedule" }, "usedBy": [ "scheduled-jobs:createJob", "scheduled-jobs:getJob", "scheduled-jobs:listJobs", "scheduled-jobs:pauseJob", "scheduled-jobs:resumeJob", "scheduled-jobs:updateJob" ], "usedByRoots": [], "fields": [ { "name": "scheduleId", "description": "Server-assigned identifier of the scheduled job, prefixed with \"sched_\".", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "tenantId", "description": "Identifier of the tenant that owns or scopes this record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "projectId", "description": "Identifier of the project within the tenant that scopes this record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "ownerSubject", "description": "Subject identifier of the owning user or service account.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Human-readable name assigned to the scheduled job.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Human-readable explanation of the scheduled job.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "scheduleType", "description": "Schedule type and expression.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "cronExpression", "description": "Cron expression. Populated when schedule_type is SCHEDULE_TYPE_CRON.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "timezone", "description": "IANA timezone for cron evaluation. Default \"UTC\".", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "scheduledAt", "description": "Exact fire time. Populated when schedule_type is SCHEDULE_TYPE_ONCE.", "presence": "message", "required": false, "requestRequired": false }, { "name": "intervalSeconds", "description": "Interval between firings in seconds. Populated when schedule_type is\nSCHEDULE_TYPE_RECURRING_INTERVAL.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "target", "description": "Destination and invocation settings for the scheduled job.", "presence": "message", "required": false, "requestRequired": false }, { "name": "state", "description": "Lifecycle status controlling whether the scheduled job can trigger.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "retryPolicy", "description": "Attempt limits and backoff settings for the scheduled target.", "presence": "message", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Application-defined JSON metadata attached to the scheduled job.", "presence": "message", "required": false, "requestRequired": false }, { "name": "autoPauseThreshold", "description": "If consecutive_failure_count reaches this threshold the job is\nauto-paused (state PAUSED, paused_by_subject \"system:auto-pause\").\n\nIt is compared against consecutive_failure_count, NOT failure_count.\nfailure_count is cumulative for the schedule's whole life, so a healthy\nschedule that collects scattered failures over months would eventually\nexceed any threshold and pause itself forever.\n\n0 disables auto-pause; otherwise must be in the range [3, 100]. Default 10.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "externalId", "description": "Client-supplied external id. Echoed back when set; empty otherwise.\nOptional, immutable, unique within (tenant_id, project_id) among live\nschedules. Never starts with the reserved system-id prefix \"sched_\".", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time at which the scheduled job was created.", "presence": "message", "required": false, "requestRequired": false }, { "name": "createdBySubject", "description": "Subject identifier recorded when the schedule was created.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "updatedAt", "description": "Time this record was most recently updated.", "presence": "message", "required": false, "requestRequired": false }, { "name": "updatedBySubject", "description": "Subject identifier recorded when the schedule was last updated.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pausedAt", "description": "Time at which the schedule was paused.", "presence": "message", "required": false, "requestRequired": false }, { "name": "pausedBySubject", "description": "Subject identifier recorded for the schedule pause.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "pausedReason", "description": "Explanation recorded for the schedule pause.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "resumedAt", "description": "Time at which the schedule was most recently resumed.", "presence": "message", "required": false, "requestRequired": false }, { "name": "resumedBySubject", "description": "Subject identifier recorded for the schedule resume.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "deletedAt", "description": "Time at which the schedule was deleted.", "presence": "message", "required": false, "requestRequired": false }, { "name": "deletedBySubject", "description": "Subject identifier recorded for the schedule deletion.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "lastTriggeredAt", "description": "Time when the schedule was last triggered.", "presence": "message", "required": false, "requestRequired": false }, { "name": "nextTriggerAt", "description": "Time calculated for the next scheduled trigger.", "presence": "message", "required": false, "requestRequired": false }, { "name": "triggerCount", "description": "Scheduled times that ran, cumulative for the schedule's whole life.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "failureCount", "description": "Scheduled times whose first attempt failed, cumulative for the\nschedule's whole life. A firing that fails on attempt 1 and succeeds on\nretry still counts here — a failure was observed.\n\nThis counter does NOT drive auto-pause. See consecutive_failure_count.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "consecutiveFailureCount", "description": "Current run of consecutive failed firings. This is the counter\nauto_pause_threshold is compared against.\n\nIncremented when a firing's first attempt fails; reset to 0 as soon as\nany attempt of any firing succeeds. So a firing that fails on attempt 1\nand succeeds on retry has net zero effect here while still advancing\nfailure_count — the target recovered, so the run is over.\n\nA non-success terminal outcome counts as a failure, including a firing\ncancelled on a terminal 4xx.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ScheduleTarget", "title": "ScheduleTarget", "slug": "/api/models/schedule-target", "description": "ScheduleTarget describes the HTTP endpoint that receives each job invocation.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "scheduling", "role": "domain-model", "title": "ScheduleTarget", "slug": "/api/models/schedule-target" }, "usedBy": [ "scheduled-jobs:createJob", "scheduled-jobs:getJob", "scheduled-jobs:listJobs", "scheduled-jobs:pauseJob", "scheduled-jobs:resumeJob", "scheduled-jobs:updateJob" ], "usedByRoots": [], "fields": [ { "name": "url", "description": "Destination URL. Must be a valid absolute URI.", "presence": "implicit", "required": false, "requestRequired": true }, { "name": "method", "description": "HTTP method to use. Defaults to \"POST\".", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "kind", "description": "Logical kind used for routing and observability (e.g., \"notification\",\n\"llm_conversation\", \"metering\"). Required.", "presence": "implicit", "required": false, "requestRequired": true }, { "name": "payload", "description": "Arbitrary JSON payload forwarded verbatim to the target.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ScheduleTargetInput", "title": "ScheduleTarget", "slug": "/api/models/schedule-target-input", "description": "ScheduleTarget describes the HTTP endpoint that receives each job invocation.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "scheduling", "role": "domain-model", "title": "ScheduleTarget", "slug": "/api/models/schedule-target" }, "usedBy": [ "scheduled-jobs:createJob", "scheduled-jobs:updateJob" ], "usedByRoots": [], "fields": [ { "name": "url", "description": "Destination URL. Must be a valid absolute URI.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "method", "description": "HTTP method to use. Defaults to \"POST\".", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "kind", "description": "Logical kind used for routing and observability (e.g., \"notification\",\n\"llm_conversation\", \"metering\"). Required.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "payload", "description": "Arbitrary JSON payload forwarded verbatim to the target.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "Score", "title": "Score", "slug": "/api/models/score", "description": "Evaluation score with its value, source, target identity, and generation attribution.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "Score", "slug": "/api/models/score" }, "usedBy": [ "evals:getOverview", "evals:getSession", "evals:getTrace", "evals:listObservations", "evals:listScores", "evals:listSessions", "evals:listTraces" ], "usedByRoots": [], "fields": [ { "name": "scoreId", "description": "Identifier of the evaluation score.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "targetType", "description": "Kind of evaluation object to which the score applies.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "targetId", "description": "Identifier of the evaluation object to which the score applies.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Metric name identifying the recorded evaluation score.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "dataType", "description": "Score value type used to interpret the numeric, categorical, or boolean value.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "numericValue", "description": "Numeric score value reported by the evaluator.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "stringValue", "description": "String operand or score value used by the selected evaluation type.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "booleanValue", "description": "Boolean operand or score value used by the selected evaluation type.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "source", "description": "Source classification reported for the evaluation score.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "comment", "description": "Explanatory text attached to the evaluation score.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time when this record was created.", "presence": "message", "required": false, "requestRequired": false }, { "name": "textValue", "description": "Text value of the evaluation score.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "authorUserId", "description": "Identifier recorded for the user who authored the score.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "configId", "description": "Identifier of the score configuration defining the score’s value domain.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "queueId", "description": "Identifier of the annotation queue.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "traceId", "description": "Identifier of the evaluation trace.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "observationId", "description": "Identifier of the evaluation observation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sessionId", "description": "Identifier of the evaluation session grouping related traces.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "datasetRunId", "description": "Identifier of the dataset run associated with the score.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "environment", "description": "Environment label attached to the evaluation record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadataJson", "description": "Additional attributes serialized as a JSON object.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "updatedAt", "description": "Time when this record was last updated.", "presence": "message", "required": false, "requestRequired": false }, { "name": "timestamp", "description": "Timestamp associated with the conversation message or event.", "presence": "message", "required": false, "requestRequired": false }, { "name": "traceName", "description": "Denormalised for the Scores table's Trace Name column, which would\notherwise need one trace read per row.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "userId", "description": "Identifier of the user associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sourceLabel", "description": "Original evaluation-provider source label, such as API, ANNOTATION or EVAL. Interpret it\nalongside source and authorship: API alone does not distinguish an end-user rating from a\nharness, and a source label does not independently prove verified human provenance.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "conversationId", "description": "Conversation identifier recorded in the score's own metadata. Scores authored directly in\nthe evaluation store can lack platform attribution; an empty link is not repaired by retrying.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "messageId", "description": "Identifier of the conversation message associated with the evaluation record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "messageSequence", "description": "Sequence number of the evaluated message within its conversation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "profileId", "description": "Identifier of the agent profile associated with the generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "configHash", "description": "Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation\nresults. Other settings are excluded; this is not an immutable profile revision.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ScoreAggregate", "title": "ScoreAggregate", "slug": "/api/models/score-aggregate", "description": "Count and average for scores grouped by name and source.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "ScoreAggregate", "slug": "/api/models/score-aggregate" }, "usedBy": [ "evals:getOverview" ], "usedByRoots": [], "fields": [ { "name": "name", "description": "Metric name shared by the aggregated scores.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "source", "description": "Source classification reported for the evaluation score.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "count", "description": "Number of evaluation records represented by this group.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "average", "description": "Average score value reported for the aggregate.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ScoreConfig", "title": "ScoreConfig", "slug": "/api/models/score-config", "description": "Score definition specifying its value type, bounds, and allowed categories.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "ScoreConfig", "slug": "/api/models/score-config" }, "usedBy": [ "evals:listScoreConfigs", "evals:updateScoreConfig" ], "usedByRoots": [], "fields": [ { "name": "configId", "description": "Identifier of the score configuration defining the score’s value domain.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Name identifying the score definition.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "dataType", "description": "Score value type used to interpret the numeric, categorical, or boolean value.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Human-readable description of the resource.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "minValue", "description": "Minimum numeric score value allowed by the score configuration.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxValue", "description": "Maximum numeric score value allowed by the score configuration.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "categories", "description": "Named score categories defined by the score configuration.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "isArchived", "description": "Whether the score configuration is archived. Archived configurations are retained so\nhistorical scores remain interpretable.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time when this record was created.", "presence": "message", "required": false, "requestRequired": false }, { "name": "updatedAt", "description": "Time when this record was last updated.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ScoreConfigCategory", "title": "ScoreConfigCategory", "slug": "/api/models/score-config-category", "description": "Named category and associated numeric value in a categorical score definition.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "ScoreConfigCategory", "slug": "/api/models/score-config-category" }, "usedBy": [ "evals:listScoreConfigs", "evals:updateScoreConfig" ], "usedByRoots": [], "fields": [ { "name": "label", "description": "Label identifying the prompt version or score category.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "value", "description": "Numeric score value associated with this named category.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "SearchFilesRequest", "title": "SearchFilesRequest", "slug": "/api/models/search-files-request", "description": "Inputs for finding stored files by query text and metadata constraints.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "SearchFilesRequest", "slug": "/api/models/search-files-request" }, "usedBy": [ "storage:searchFiles" ], "usedByRoots": [], "fields": [ { "name": "query", "description": "Search expression used to select matching entries.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "filter", "description": "Selection criteria applied to the listing.", "presence": "message", "required": false, "requestRequired": false }, { "name": "maxResults", "description": "Maximum number of file matches requested.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "SearchFilesResponse", "title": "SearchFilesResponse", "slug": "/api/models/search-files-response", "description": "Result payload for finding stored files by query text and metadata constraints.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "SearchFilesResponse", "slug": "/api/models/search-files-response" }, "usedBy": [ "storage:searchFiles" ], "usedByRoots": [], "fields": [ { "name": "files", "description": "File metadata records returned by the listing or search.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "totalMatches", "description": "Number of files reported to match the search criteria.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "SearchMemoriesRequest", "title": "Memory search request", "slug": "/api/memory/models/search-memories-request", "description": "Input for a semantic search of memories in the authenticated user’s tenant scope.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "memory-knowledge", "role": "operation-envelope", "title": "Memory search request", "slug": "/api/memory/models/search-memories-request" }, "usedBy": [ "conversations:searchMemories" ], "usedByRoots": [], "fields": [ { "name": "query", "description": "Non-empty natural-language search query.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "topK", "description": "Maximum results requested. Supply explicitly; omission is rejected before search.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "threshold", "description": "Minimum provider relevance score. Omission and zero do not request a positive cutoff.\nScores are provider-specific, not probabilities that the memory is true.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "rerank", "description": "Requests reranking when supported. Absence leaves the provider behavior unchanged; explicit\nfalse is forwarded as false. It does not guarantee relevance or correctness.", "presence": "explicit", "required": false, "requestRequired": false } ] }, { "schemaName": "SearchMemoriesResponse", "title": "Memory search response", "slug": "/api/memory/models/search-memories-response", "description": "Relevant memory records and any graph relationships returned by the search provider.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "memory-knowledge", "role": "operation-envelope", "title": "Memory search response", "slug": "/api/memory/models/search-memories-response" }, "usedBy": [ "conversations:searchMemories" ], "usedByRoots": [], "fields": [ { "name": "memories", "description": "Matched memories ordered by relevance. An empty result does not prove that no memories\nexist.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "relations", "description": "Returned graph relationships; this list may be absent when there are no relationships.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "SecretMetadata", "title": "SecretMetadata", "slug": "/api/models/secret-metadata", "description": "SecretMetadata is the only thing read APIs return. No message in this file\ncarries a secret value out of the service.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "secrets", "role": "domain-model", "title": "SecretMetadata", "slug": "/api/models/secret-metadata" }, "usedBy": [ "secrets:getSecretMetadata", "secrets:listSecrets", "secrets:putSecret" ], "usedByRoots": [], "fields": [ { "name": "name", "description": "Name identifying the secret within its project.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "projectId", "description": "Identifier of the project within the tenant that scopes this record. \"default\" until Projects\nships.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Human-readable explanation of the secret.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "labels", "description": "Free-form labels used to organize and identify secrets. Free-form, e.g. {\"kind\": \"mcp-auth\"}.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "version", "description": "Version number of the stored secret metadata. Increments on every PutSecret.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdBy", "description": "Subject identifier recorded for the creator of this record. Subject from the X-User-ID header,\nwhen present.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time this record was created.", "presence": "message", "required": false, "requestRequired": false }, { "name": "updatedAt", "description": "Time this record was most recently updated.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "SecretRef", "title": "SecretRef", "slug": "/api/models/secret-ref", "description": "Reference to a secret within the same tenant and project as the resource that uses it.\nCross-project and cross-tenant secret references are not supported.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "secrets", "role": "domain-model", "title": "SecretRef", "slug": "/api/models/secret-ref" }, "usedBy": [ "mcp-servers:createCustomMcpServer", "mcp-servers:getCustomMcpServer", "mcp-servers:listCustomMcpServers", "mcp-servers:updateCustomMcpServer" ], "usedByRoots": [], "fields": [ { "name": "name", "description": "Name identifying the secret within its project.", "presence": "implicit", "required": false, "requestRequired": true } ] }, { "schemaName": "SecretRefInput", "title": "SecretRef", "slug": "/api/models/secret-ref-input", "description": "Reference to a secret within the same tenant and project as the resource that uses it.\nCross-project and cross-tenant secret references are not supported.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "secrets", "role": "domain-model", "title": "SecretRef", "slug": "/api/models/secret-ref" }, "usedBy": [ "mcp-servers:createCustomMcpServer", "mcp-servers:updateCustomMcpServer" ], "usedByRoots": [], "fields": [ { "name": "name", "description": "Name identifying the secret within its project.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "SelectiveExclusionConfig", "title": "SelectiveExclusionConfig", "slug": "/api/models/selective-exclusion-config", "description": "Configuration for selective exclusion", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "SelectiveExclusionConfig", "slug": "/api/models/selective-exclusion-config" }, "usedBy": [ "conversations:getConversationState", "conversations:updateContextManagementSettings" ], "usedByRoots": [], "fields": [ { "name": "excludeToolResults", "description": "Whether tool-result content is excluded from model context.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "excludeImages", "description": "Whether image content is excluded from model context.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "excludeFiles", "description": "Whether file content is excluded from model context.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "excludeReasoning", "description": "When true, reasoning/thinking content parts are excluded from context", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "SelectiveExclusionConfigInput", "title": "SelectiveExclusionConfig", "slug": "/api/models/selective-exclusion-config-input", "description": "Configuration for selective exclusion", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "SelectiveExclusionConfig", "slug": "/api/models/selective-exclusion-config" }, "usedBy": [ "conversations:createThread", "conversations:updateContextManagementSettings" ], "usedByRoots": [], "fields": [ { "name": "excludeToolResults", "description": "Whether tool-result content is excluded from model context.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "excludeImages", "description": "Whether image content is excluded from model context.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "excludeFiles", "description": "Whether file content is excluded from model context.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "excludeReasoning", "description": "When true, reasoning/thinking content parts are excluded from context", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "SendBulkNotificationRequest", "title": "SendBulkNotificationRequest", "slug": "/api/models/send-bulk-notification-request", "description": "events contain recipient user_ids, not the caller.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "SendBulkNotificationRequest", "slug": "/api/models/send-bulk-notification-request" }, "usedBy": [ "notifications:sendBulkNotification" ], "usedByRoots": [], "fields": [ { "name": "events", "description": "Notification trigger events submitted together. Submit at most 100 events per batch.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "SendBulkNotificationResponse", "title": "SendBulkNotificationResponse", "slug": "/api/models/send-bulk-notification-response", "description": "Result payload for triggering multiple notification workflow events together.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "SendBulkNotificationResponse", "slug": "/api/models/send-bulk-notification-response" }, "usedBy": [ "notifications:sendBulkNotification" ], "usedByRoots": [], "fields": [ { "name": "results", "description": "Provider acknowledgements and errors for the submitted notification triggers.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "SendMessageRequest", "title": "SendMessageRequest", "slug": "/api/models/send-message-request", "description": "Input for starting an asynchronous generation from a user message.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "SendMessageRequest", "slug": "/api/models/send-message-request" }, "usedBy": [ "conversations:sendMessage" ], "usedByRoots": [], "fields": [ { "name": "conversationKey", "description": "Identifier of the conversation thread.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "userMessage", "description": "User message that starts the conversation turn. Required; its role is expected to be\nROLE_USER.", "presence": "message", "required": true, "requestRequired": true }, { "name": "overrideGenerationConfig", "description": "Per-call configuration overrides applied to the active profile’s configuration, or otherwise\nthe conversation default. Supplied scalar values, including zero, empty or false, replace the\nbase value; omitted values inherit. Empty repeated/map values inherit, so clear_tools is used\nto clear inherited tools.", "presence": "message", "required": false, "requestRequired": false }, { "name": "setActiveProfileId", "description": "Set the active agent profile for this and subsequent conversation turns.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "setActiveProfileVersion", "description": "Version of the active agent profile forwarded with this turn.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "overrideMcpServers", "description": "MCP servers for this turn only. A nonempty list replaces the active profile’s or\nconversation’s list for tool discovery and execution; an empty list inherits the resolved\nconfiguration.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "experiment", "description": "Dataset-run attribution for a scripted evaluation turn. Leave unset for ordinary conversation\ntraffic.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "SendMessageResponse", "title": "SendMessageResponse", "slug": "/api/models/send-message-response", "description": "Result of starting an asynchronous generation from a user message.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "SendMessageResponse", "slug": "/api/models/send-message-response" }, "usedBy": [ "conversations:sendMessage" ], "usedByRoots": [], "fields": [ { "name": "runId", "description": "Identifier of the generation run associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "interruptedPriorRun", "description": "Whether submitting this turn interrupted a preceding generation run.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "SendMessageSyncRequest", "title": "SendMessageSyncRequest", "slug": "/api/models/send-message-sync-request", "description": "Input for submitting a user message and waiting for generation output.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "SendMessageSyncRequest", "slug": "/api/models/send-message-sync-request" }, "usedBy": [ "conversations:sendMessageSync" ], "usedByRoots": [], "fields": [ { "name": "conversationKey", "description": "Identifier of the conversation thread.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "userMessage", "description": "Required — see the note on SendMessageRequest.user_message. The sync path\nis where the defect was actually observed: it holds the connection open,\nwaits out a real generation, and hands back messages and a COMPLETED\nstatus, so a dropped turn field looks exactly like a working call.", "presence": "message", "required": true, "requestRequired": true }, { "name": "overrideGenerationConfig", "description": "Per-call configuration overrides applied to the active profile’s configuration, or otherwise\nthe conversation default. Supplied scalar values, including zero, empty or false, replace the\nbase value; omitted values inherit. Empty repeated/map values inherit, so clear_tools is used\nto clear inherited tools.", "presence": "message", "required": false, "requestRequired": false }, { "name": "setActiveProfileId", "description": "Set the active agent profile for this and subsequent conversation turns.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "setActiveProfileVersion", "description": "Version of the active agent profile forwarded with this turn.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "overrideMcpServers", "description": "MCP servers for this turn only. A nonempty list replaces the active profile’s or\nconversation’s list for tool discovery and execution; an empty list inherits the resolved\nconfiguration.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "experiment", "description": "Dataset-run attribution for a scripted evaluation turn. Leave unset for ordinary conversation\ntraffic.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "SendMessageSyncResponse", "title": "SendMessageSyncResponse", "slug": "/api/models/send-message-sync-response", "description": "Result of submitting a user message and waiting for generation output.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "SendMessageSyncResponse", "slug": "/api/models/send-message-sync-response" }, "usedBy": [ "conversations:sendMessageSync" ], "usedByRoots": [], "fields": [ { "name": "runId", "description": "Identifier of the generation run associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "interruptedPriorRun", "description": "Whether submitting this turn interrupted a preceding generation run.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "messages", "description": "Conversation messages returned by the generation segment.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "status", "description": "Generation status reported when the synchronous wait returns.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "aggregateUsage", "description": "Aggregated model usage reported for the generation run.", "presence": "message", "required": false, "requestRequired": false }, { "name": "error", "description": "Structured error for partial success scenarios (some messages generated before failure).\nFull failures propagate as TerminalError → HTTP error status + RpcError JSON body.", "presence": "message", "required": false, "requestRequired": false }, { "name": "pendingClientTools", "description": "Tool calls dispatched for execution by the client.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "clientToolCursor", "description": "Latest client-tool dispatch sequence represented by this response.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "SendNotificationRequest", "title": "SendNotificationRequest", "slug": "/api/models/send-notification-request", "description": "user_id is the recipient, not the caller.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "SendNotificationRequest", "slug": "/api/models/send-notification-request" }, "usedBy": [ "notifications:sendNotification" ], "usedByRoots": [], "fields": [ { "name": "workflowId", "description": "Identifier of the notification workflow to execute or configure.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "userId", "description": "Identifier of the notification's intended recipient.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "payload", "description": "Template variables and event data passed to the notification workflow.", "presence": "message", "required": false, "requestRequired": false }, { "name": "overrides", "description": "Provider-specific overrides passed through to delivery, such as an FCM data payload.", "presence": "message", "required": false, "requestRequired": false }, { "name": "transactionId", "description": "Identifier correlating a notification trigger with later status or cancellation requests.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "SendNotificationResponse", "title": "SendNotificationResponse", "slug": "/api/models/send-notification-response", "description": "Result payload for triggering a notification workflow for a selected user.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "SendNotificationResponse", "slug": "/api/models/send-notification-response" }, "usedBy": [ "notifications:sendNotification" ], "usedByRoots": [], "fields": [ { "name": "acknowledged", "description": "Whether the notification provider acknowledged the trigger.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "status", "description": "Descriptive status reported by the notification provider, not a fixed set of states.\n\"processed\" means the workflow was accepted for processing; it does not confirm delivery.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "transactionId", "description": "Identifier correlating a notification trigger with later status or cancellation requests.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "errors", "description": "Errors reported while processing notification requests.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "SendToTopicRequest", "title": "SendToTopicRequest", "slug": "/api/models/send-to-topic-request", "description": "exclude_user_id is an exclusion target, not the caller.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "SendToTopicRequest", "slug": "/api/models/send-to-topic-request" }, "usedBy": [ "notifications:sendToTopic" ], "usedByRoots": [], "fields": [ { "name": "workflowId", "description": "Identifier of the notification workflow to execute or configure.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "topicKey", "description": "Caller-facing key identifying a notification topic.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "payload", "description": "Template variables and event data passed to the notification workflow.", "presence": "message", "required": false, "requestRequired": false }, { "name": "overrides", "description": "Provider-specific overrides applied to the notification trigger.", "presence": "message", "required": false, "requestRequired": false }, { "name": "transactionId", "description": "Identifier correlating a notification trigger with later status or cancellation requests.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "excludeUserId", "description": "User identifier to omit from the topic notification’s recipients.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "SendToTopicResponse", "title": "SendToTopicResponse", "slug": "/api/models/send-to-topic-response", "description": "Result payload for triggering a notification workflow for the subscribers of a topic.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "SendToTopicResponse", "slug": "/api/models/send-to-topic-response" }, "usedBy": [ "notifications:sendToTopic" ], "usedByRoots": [], "fields": [ { "name": "acknowledged", "description": "Whether the notification provider acknowledged the trigger.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "status", "description": "Status reported by the notification provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "transactionId", "description": "Identifier correlating a notification trigger with later status or cancellation requests.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "errors", "description": "Errors reported while processing notification requests.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "SendWithDigestRequest", "title": "SendWithDigestRequest", "slug": "/api/models/send-with-digest-request", "description": "user_id is the recipient, not the caller.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "SendWithDigestRequest", "slug": "/api/models/send-with-digest-request" }, "usedBy": [ "notifications:sendWithDigest" ], "usedByRoots": [], "fields": [ { "name": "workflowId", "description": "Identifier of the notification workflow to execute or configure.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "userId", "description": "Identifier of the user associated with the operation.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "payload", "description": "Template variables and event data passed to the notification workflow.", "presence": "message", "required": false, "requestRequired": false }, { "name": "overrides", "description": "Provider-specific overrides applied to the notification trigger.", "presence": "message", "required": false, "requestRequired": false }, { "name": "transactionId", "description": "Identifier correlating a notification trigger with later status or cancellation requests.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "SendWithDigestResponse", "title": "SendWithDigestResponse", "slug": "/api/models/send-with-digest-response", "description": "Result payload for submitting a notification event for digest processing.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "SendWithDigestResponse", "slug": "/api/models/send-with-digest-response" }, "usedBy": [ "notifications:sendWithDigest" ], "usedByRoots": [], "fields": [ { "name": "acknowledged", "description": "Whether the notification provider acknowledged the trigger.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "status", "description": "Status reported by the notification provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "transactionId", "description": "Identifier correlating a notification trigger with later status or cancellation requests.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "errors", "description": "Errors reported while processing notification requests.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "SessionDetail", "title": "SessionDetail", "slug": "/api/models/session-detail", "description": "Evaluation session summary together with the traces belonging to the session.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "SessionDetail", "slug": "/api/models/session-detail" }, "usedBy": [ "evals:getSession" ], "usedByRoots": [], "fields": [ { "name": "summary", "description": "Summary information for the evaluation trace or session.", "presence": "message", "required": false, "requestRequired": false }, { "name": "traces", "description": "Evaluation traces returned by the query.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "SessionSummary", "title": "SessionSummary", "slug": "/api/models/session-summary", "description": "Aggregated trace, usage, and score information for an evaluation session.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "SessionSummary", "slug": "/api/models/session-summary" }, "usedBy": [ "evals:getSession", "evals:listSessions" ], "usedByRoots": [], "fields": [ { "name": "sessionId", "description": "Identifier of the evaluation session grouping related traces.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time when this record was created.", "presence": "message", "required": false, "requestRequired": false }, { "name": "durationSeconds", "description": "Elapsed session duration, in seconds.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "environment", "description": "Environment label attached to the evaluation record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "userIds", "description": "Identifiers of the users selected by the operation.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "traceCount", "description": "Number of traces represented by this summary or group.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "totalCost", "description": "Total cost reported for the evaluated generation or aggregate.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "inputTokens", "description": "Input-token usage reported for the evaluated generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "outputTokens", "description": "Output-token usage reported for the evaluated generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "totalTokens", "description": "Total token usage reported for the evaluated generation or aggregate.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "traceTags", "description": "Labels collected from the session’s evaluation traces.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "scores", "description": "Evaluation scores returned for the selected objects or query.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "commentCount", "description": "Number of comments reported on the evaluation object.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadataJson", "description": "Additional attributes serialized as a JSON object.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "bookmarked", "description": "Whether the evaluation object is bookmarked.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "conversationIds", "description": "Conversation identifiers observed on the session’s traces; a session may span multiple\nconversations.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "SocayoAgentConfig", "title": "SocayoAgentConfig", "slug": "/api/models/socayo-agent-config", "description": "Socayo-specific agent configuration (bundled)", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "voice-media", "role": "domain-model", "title": "SocayoAgentConfig", "slug": "/api/models/socayo-agent-config" }, "usedBy": [ "conversations:createDailySession" ], "usedByRoots": [], "fields": [ { "name": "conversationKey", "description": "Conversation thread identifier associated with the voice session.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "userId", "description": "Identifier of the user associated with the operation.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "provider", "description": "Backend provider to use for session orchestration; defaults to PIPECAT_CLOUD", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "tts", "description": "Bundled sub-configs\nSpeech-synthesis configuration supplied to the Socayo agent.", "presence": "message", "required": false, "requestRequired": false }, { "name": "heygen", "description": "HeyGen avatar and voice configuration for the Socayo agent.", "presence": "message", "required": false, "requestRequired": false }, { "name": "transport", "description": "Audio transport settings used by the Socayo agent.", "presence": "message", "required": false, "requestRequired": false }, { "name": "extras", "description": "Optional extras for forward-compat", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "SourcePromptFragment", "title": "SourcePromptFragment", "slug": "/api/models/source-prompt-fragment", "description": "Shared template block supplied for import. Its path resolves source include directives;\nfragment_id supplies the stable output identity when shared fragments are emitted, or is derived\nfrom the path when omitted.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "domain-model", "title": "SourcePromptFragment", "slug": "/api/models/source-prompt-fragment" }, "usedBy": [ "agent-profiles:importAgentProfiles" ], "usedByRoots": [], "fields": [ { "name": "fragmentId", "description": "Identifier of the reusable prompt fragment.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Display name for the imported reusable prompt fragment.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sourceDsl", "description": "Raw source text (may itself contain @include / metadata comments).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "path", "description": "Include path, e.g. \"_shared/safety-module.txt\"", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "SourcePromptTemplate", "title": "SourcePromptTemplate", "slug": "/api/models/source-prompt-template", "description": "Source persona template to convert into an agent profile during import. Its source_dsl contains\nthe original template syntax from which the importer derives the profile template and variable\nspecifications.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "domain-model", "title": "SourcePromptTemplate", "slug": "/api/models/source-prompt-template" }, "usedBy": [ "agent-profiles:importAgentProfiles" ], "usedByRoots": [], "fields": [ { "name": "profileId", "description": "Identifier of the agent profile associated with the operation or generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Display name for the imported agent profile.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "whenToUse", "description": "Instructions describing when the imported agent profile should be selected.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "keywords", "description": "Keywords associated with selection of the imported agent profile.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "sourceDsl", "description": "Raw source-DSL system prompt.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "generationConfig", "description": "Generation settings other than the prompt, such as temperature. Must not set model or\nmodels: import refuses a template that does, and the model is set afterwards with\nUpdateAgentProfile.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "StartSessionUserData", "title": "StartSessionUserData", "slug": "/api/models/start-session-user-data", "description": "Arbitrary user data passed when starting a session, as simple key/value pairs", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "voice-media", "role": "domain-model", "title": "StartSessionUserData", "slug": "/api/models/start-session-user-data" }, "usedBy": [ "conversations:createDailySession" ], "usedByRoots": [], "fields": [ { "name": "fields", "description": "Structured user data passed to the session-start request.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "StartSessionUserDataInput", "title": "StartSessionUserData", "slug": "/api/models/start-session-user-data-input", "description": "Arbitrary user data passed when starting a session, as simple key/value pairs", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "voice-media", "role": "domain-model", "title": "StartSessionUserData", "slug": "/api/models/start-session-user-data" }, "usedBy": [ "conversations:createDailySession" ], "usedByRoots": [], "fields": [ { "name": "fields", "description": "Structured user data passed to the session-start request.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "StopOnFailureRule", "title": "StopOnFailureRule", "slug": "/api/models/stop-on-failure-rule", "description": "Requested tool-selection rule for handling an execution failure. The current\ngeneration workflow stores these rules but does not evaluate them or stop a loop\nor run because of them.\n\nThe conditions in [`stopOnFailureRules`](/api/models/tool-execution-policy#request-field-stoponfailurerules),\nincluding [`priority`](/api/models/stop-on-failure-rule#request-field-priority),\ntimeout inclusion and error matching, are not enforced. Do not rely on these\nfields as a stop control.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "StopOnFailureRule", "slug": "/api/models/stop-on-failure-rule" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "conversations:updatePromptVariables", "conversations:updateSettings", "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "toolNamePatterns", "description": "Requested tool-name selection; not evaluated by the current generation workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "serverIds", "description": "Requested MCP server selection; not evaluated by the current generation workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "onFailure", "description": "Requested failure action; not evaluated by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "includeTimeouts", "description": "Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "errorSubstrings", "description": "Requested error-text selection; not evaluated by the current generation workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "priority", "description": "Requested rule priority; not evaluated by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "StopOnFailureRuleInput", "title": "StopOnFailureRule", "slug": "/api/models/stop-on-failure-rule-input", "description": "Requested tool-selection rule for handling an execution failure. The current\ngeneration workflow stores these rules but does not evaluate them or stop a loop\nor run because of them.\n\nThe conditions in [`stopOnFailureRules`](/api/models/tool-execution-policy#request-field-stoponfailurerules),\nincluding [`priority`](/api/models/stop-on-failure-rule#request-field-priority),\ntimeout inclusion and error matching, are not enforced. Do not rely on these\nfields as a stop control.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "StopOnFailureRule", "slug": "/api/models/stop-on-failure-rule" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:appendMessage", "conversations:createThread", "conversations:sendMessage", "conversations:sendMessageSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "conversations:updateSettings", "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [ "generation-config" ], "fields": [ { "name": "toolNamePatterns", "description": "Requested tool-name selection; not evaluated by the current generation workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "serverIds", "description": "Requested MCP server selection; not evaluated by the current generation workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "onFailure", "description": "Requested failure action; not evaluated by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "includeTimeouts", "description": "Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "errorSubstrings", "description": "Requested error-text selection; not evaluated by the current generation workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "priority", "description": "Requested rule priority; not evaluated by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "StopOnFailureRuleWebhook", "title": "StopOnFailureRule", "slug": "/api/models/stop-on-failure-rule-webhook", "description": "Requested tool-selection rule for handling an execution failure. The current\ngeneration workflow stores these rules but does not evaluate them or stop a loop\nor run because of them.\n\nThe conditions in [`stopOnFailureRules`](/api/models/tool-execution-policy#request-field-stoponfailurerules),\nincluding [`priority`](/api/models/stop-on-failure-rule#request-field-priority),\ntimeout inclusion and error matching, are not enforced. Do not rely on these\nfields as a stop control.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "StopOnFailureRule", "slug": "/api/models/stop-on-failure-rule" }, "usedBy": [], "usedByRoots": [ "llm.generation_started", "llm.message_published" ], "fields": [ { "name": "tool_name_patterns", "description": "Requested tool-name selection; not evaluated by the current generation workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "server_ids", "description": "Requested MCP server selection; not evaluated by the current generation workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "on_failure", "description": "Requested failure action; not evaluated by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "include_timeouts", "description": "Requested inclusion of timeouts as failures; not evaluated by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "error_substrings", "description": "Requested error-text selection; not evaluated by the current generation workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "priority", "description": "Requested rule priority; not evaluated by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "StorageManagerState", "title": "StorageManagerState", "slug": "/api/models/storage-manager-state", "description": "Durable actor state for StorageManager", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "domain-model", "title": "StorageManagerState", "slug": "/api/models/storage-manager-state" }, "usedBy": [ "storage:getState" ], "usedByRoots": [], "fields": [ { "name": "userId", "description": "Identifier of the user associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "folders", "description": "Path -> FolderInfo.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "files", "description": "Path -> FileInfo.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "totalSizeBytes", "description": "Combined size of the represented files, in bytes.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "quotaBytes", "description": "Storage capacity allocated to the user, in bytes.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "totalFileCount", "description": "Number of files tracked in the storage state.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "totalFolderCount", "description": "Number of folders tracked in the storage state.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "When user's storage was initialized.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "lastModified", "description": "Last modification timestamp.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "StructuredMessage", "title": "StructuredMessage", "slug": "/api/models/structured-message", "description": "A structured message whose JSON payload has been validated against\na declared schema. Consumers can trust that json_payload conforms\nto the schema identified by schema_name.\n\nInspect 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.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "StructuredMessage", "slug": "/api/models/structured-message" }, "usedBy": [ "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:mcpListResources", "conversations:mcpReadResource", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "jsonPayload", "description": "The validated JSON payload as a Struct (preserves types)", "presence": "message", "required": false, "requestRequired": false }, { "name": "schemaName", "description": "Schema identifier (from ResponseFormat.schema_name)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "healed", "description": "Whether response healing is reported for this structured message. Currently returned as false.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "StructuredMessageInput", "title": "StructuredMessage", "slug": "/api/models/structured-message-input", "description": "A structured message whose JSON payload has been validated against\na declared schema. Consumers can trust that json_payload conforms\nto the schema identified by schema_name.\n\nInspect 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.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "StructuredMessage", "slug": "/api/models/structured-message" }, "usedBy": [ "conversations:appendMessage", "conversations:sendMessage", "conversations:sendMessageSync" ], "usedByRoots": [], "fields": [ { "name": "jsonPayload", "description": "The validated JSON payload as a Struct (preserves types)", "presence": "message", "required": false, "requestRequired": false }, { "name": "schemaName", "description": "Schema identifier (from ResponseFormat.schema_name)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "healed", "description": "Whether response healing is reported for this structured message. Currently returned as false.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "StructuredMessageWebhook", "title": "StructuredMessage", "slug": "/api/models/structured-message-webhook", "description": "A structured message whose JSON payload has been validated against\na declared schema. Consumers can trust that json_payload conforms\nto the schema identified by schema_name.\n\nInspect 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.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "StructuredMessage", "slug": "/api/models/structured-message" }, "usedBy": [], "usedByRoots": [ "llm.message_published" ], "fields": [ { "name": "json_payload", "description": "The validated JSON payload as a Struct (preserves types)", "presence": "message", "required": false, "requestRequired": false }, { "name": "schema_name", "description": "Schema identifier (from ResponseFormat.schema_name)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "healed", "description": "Whether response healing is reported for this structured message. Currently returned as false.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "SubmitClientToolResultsRequest", "title": "SubmitClientToolResultsRequest", "slug": "/api/models/submit-client-tool-results-request", "description": "Input for returning client-side tool execution results to the conversation.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "SubmitClientToolResultsRequest", "slug": "/api/models/submit-client-tool-results-request" }, "usedBy": [ "conversations:submitClientToolResults" ], "usedByRoots": [], "fields": [ { "name": "conversationKey", "description": "Identifier of the conversation thread.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "results", "description": "Execution results for tools that ran on the client.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "SubmitClientToolResultsResponse", "title": "SubmitClientToolResultsResponse", "slug": "/api/models/submit-client-tool-results-response", "description": "Result of returning client-side tool execution results to the conversation.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "SubmitClientToolResultsResponse", "slug": "/api/models/submit-client-tool-results-response" }, "usedBy": [ "conversations:submitClientToolResults" ], "usedByRoots": [], "fields": [ { "name": "runId", "description": "Identifier of the generation run, usable for retrieving its result or status after submitting\nclient-tool results.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "SubmitClientToolResultsSyncRequest", "title": "SubmitClientToolResultsSyncRequest", "slug": "/api/models/submit-client-tool-results-sync-request", "description": "Input for returning client-side tool results and waiting for the next generation segment.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "SubmitClientToolResultsSyncRequest", "slug": "/api/models/submit-client-tool-results-sync-request" }, "usedBy": [ "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "conversationKey", "description": "Identifier of the conversation thread.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "results", "description": "Execution results for tools that ran on the client.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "clientToolCursor", "description": "dispatch_seq this caller last observed — same semantics as\nAwaitGenerationRequest.client_tool_cursor. 0 on first call.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "SubmitClientToolResultsSyncResponse", "title": "SubmitClientToolResultsSyncResponse", "slug": "/api/models/submit-client-tool-results-sync-response", "description": "Result of returning client-side tool results and waiting for the next generation segment.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "SubmitClientToolResultsSyncResponse", "slug": "/api/models/submit-client-tool-results-sync-response" }, "usedBy": [ "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "runId", "description": "Identifier of the generation run associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "messages", "description": "Conversation messages returned by the generation segment.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "status", "description": "Generation status reported for the next segment after tool results are submitted.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "aggregateUsage", "description": "Aggregated model usage reported for the generation run.", "presence": "message", "required": false, "requestRequired": false }, { "name": "pendingClientTools", "description": "Tool calls dispatched for execution by the client.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "clientToolCursor", "description": "Latest client-tool dispatch sequence represented by this response.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "error", "description": "Structured error for partial success scenarios. Full failures propagate\nas TerminalError → HTTP error status + RpcError JSON body.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "SubmitToolApprovalsRequest", "title": "SubmitToolApprovalsRequest", "slug": "/api/models/submit-tool-approvals-request", "description": "Input for submitting decisions for tool calls awaiting approval.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "SubmitToolApprovalsRequest", "slug": "/api/models/submit-tool-approvals-request" }, "usedBy": [ "conversations:submitToolApprovals" ], "usedByRoots": [], "fields": [ { "name": "conversationKey", "description": "Identifier of the conversation thread.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "approvals", "description": "Approval decisions for the identified pending tool calls.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "SubmitToolApprovalsResponse", "title": "SubmitToolApprovalsResponse", "slug": "/api/models/submit-tool-approvals-response", "description": "Result of submitting decisions for tool calls awaiting approval. This message declares no response fields.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "SubmitToolApprovalsResponse", "slug": "/api/models/submit-tool-approvals-response" }, "usedBy": [ "conversations:submitToolApprovals" ], "usedByRoots": [], "fields": [] }, { "schemaName": "SubscriberData", "title": "SubscriberData", "slug": "/api/models/subscriber-data", "description": "Contact, locale, and custom attributes used by notification delivery.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "domain-model", "title": "SubscriberData", "slug": "/api/models/subscriber-data" }, "usedBy": [ "notifications:getSubscriber", "notifications:updateSubscriberData" ], "usedByRoots": [], "fields": [ { "name": "firstName", "description": "Subscriber’s given name.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "lastName", "description": "Subscriber’s family name.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "email", "description": "Email address used for subscriber contact and delivery.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "phone", "description": "Phone number used for subscriber contact and delivery.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "avatarUrl", "description": "URL of the subscriber’s avatar image.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "locale", "description": "Subscriber locale used when rendering notifications.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "timezone", "description": "Subscriber time zone used for notification presentation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "customData", "description": "Additional template variables.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "SubscriberDataInput", "title": "SubscriberData", "slug": "/api/models/subscriber-data-input", "description": "Contact, locale, and custom attributes used by notification delivery.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "domain-model", "title": "SubscriberData", "slug": "/api/models/subscriber-data" }, "usedBy": [ "notifications:updateSubscriberData" ], "usedByRoots": [], "fields": [ { "name": "firstName", "description": "Subscriber’s given name.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "lastName", "description": "Subscriber’s family name.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "email", "description": "Email address used for subscriber contact and delivery.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "phone", "description": "Phone number used for subscriber contact and delivery.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "avatarUrl", "description": "URL of the subscriber’s avatar image.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "locale", "description": "Subscriber locale used when rendering notifications.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "timezone", "description": "Subscriber time zone used for notification presentation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "customData", "description": "Additional template variables.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "SubscriberSummary", "title": "SubscriberSummary", "slug": "/api/models/subscriber-summary", "description": "Contact and presence information returned in a subscriber listing.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "domain-model", "title": "SubscriberSummary", "slug": "/api/models/subscriber-summary" }, "usedBy": [ "notifications:listSubscribers" ], "usedByRoots": [], "fields": [ { "name": "subscriberId", "description": "Identifier of the notification subscriber.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "email", "description": "Email address used for subscriber contact and delivery.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "firstName", "description": "Subscriber’s given name.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "lastName", "description": "Subscriber’s family name.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "isOnline", "description": "Whether the provider reports the subscriber currently online.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "lastOnlineAt", "description": "Time when the provider last observed the subscriber online.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "Subscription", "title": "Subscription", "slug": "/api/models/subscription", "description": "Webhook event selection and retry settings associated with an endpoint.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "webhooks", "role": "domain-model", "title": "Subscription", "slug": "/api/models/subscription" }, "usedBy": [ "webhooks:createWebhookEndpoint", "webhooks:createWebhookSubscription", "webhooks:listWebhookSubscriptions" ], "usedByRoots": [], "fields": [ { "name": "id", "description": "Identifier of the subscription record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Display name of the webhook event subscription.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "endpointId", "description": "Identifier of the webhook endpoint receiving deliveries.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "eventTypes", "description": "Event type names selected for the webhook subscription.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "filter", "description": "Selection criteria applied to the listing.", "presence": "message", "required": false, "requestRequired": false }, { "name": "retryConfig", "description": "Retry policy applied to the webhook subscription.", "presence": "message", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Time when this record was created.", "presence": "message", "required": false, "requestRequired": false }, { "name": "externalId", "description": "Client-supplied external subscription identifier. Empty when none was supplied.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "SubscriptionFilter", "title": "SubscriptionFilter", "slug": "/api/models/subscription-filter", "description": "Event-body and header conditions selecting webhook events for a subscription.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "webhooks", "role": "domain-model", "title": "SubscriptionFilter", "slug": "/api/models/subscription-filter" }, "usedBy": [ "webhooks:createWebhookEndpoint", "webhooks:createWebhookSubscription", "webhooks:listWebhookSubscriptions" ], "usedByRoots": [], "fields": [ { "name": "body", "description": "Event-body matching rules used by the webhook subscription filter.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "headers", "description": "Header-matching rules used to select events for the webhook subscription.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "TestCustomMCPServerConnectionRequest", "title": "TestCustomMCPServerConnectionRequest", "slug": "/api/models/test-custom-mcp-server-connection-request", "description": "Inputs for testing connectivity and tool discovery for a tenant-owned MCP server.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "TestCustomMCPServerConnectionRequest", "slug": "/api/models/test-custom-mcp-server-connection-request" }, "usedBy": [ "mcp-servers:testCustomMcpServerConnection" ], "usedByRoots": [], "fields": [ { "name": "projectId", "description": "Identifier of the project associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "serverId", "description": "Identifier of the MCP server associated with the operation or tool.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "TestCustomMCPServerConnectionResponse", "title": "TestCustomMCPServerConnectionResponse", "slug": "/api/models/test-custom-mcp-server-connection-response", "description": "Result payload for testing connectivity and tool discovery for a tenant-owned MCP server.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "TestCustomMCPServerConnectionResponse", "slug": "/api/models/test-custom-mcp-server-connection-response" }, "usedBy": [ "mcp-servers:testCustomMcpServerConnection" ], "usedByRoots": [], "fields": [ { "name": "success", "description": "Whether the operation reports a successful result.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "toolCount", "description": "Number of tools reported by the MCP server.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "latencyMs", "description": "Measured MCP connection-test latency, in milliseconds.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "error", "description": "Sanitized failure reason. Never contains the resolved credential, the auth\nheader, or internal path details.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ThreadSummary", "title": "ThreadSummary", "slug": "/api/models/thread-summary", "description": "Conversation summary returned by thread listing and detail operations.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "ThreadSummary", "slug": "/api/models/thread-summary" }, "usedBy": [ "conversations:listThreads" ], "usedByRoots": [], "fields": [ { "name": "threadId", "description": "Identifier of the conversation thread.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "userId", "description": "Identifier of the user associated with the conversation thread.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "title", "description": "Display title of the conversation thread.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "tags", "description": "Labels associated with the conversation thread.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "status", "description": "Lifecycle status recorded for the conversation thread.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "messageCount", "description": "Number of messages recorded in the thread summary.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "lastMessagePreview", "description": "Text preview of the most recently projected message.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "lastMessageAt", "description": "Timestamp of the most recently projected message.", "presence": "message", "required": false, "requestRequired": false }, { "name": "createdAt", "description": "Timestamp when the conversation thread was created.", "presence": "message", "required": false, "requestRequired": false }, { "name": "updatedAt", "description": "Timestamp when the conversation thread summary was last updated.", "presence": "message", "required": false, "requestRequired": false }, { "name": "externalId", "description": "Caller-supplied identifier associated with the conversation thread.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ThresholdConfig", "title": "ThresholdConfig", "slug": "/api/models/threshold-config", "description": "Threshold configuration for triggering compaction", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "ThresholdConfig", "slug": "/api/models/threshold-config" }, "usedBy": [ "conversations:getConversationState", "conversations:updateContextManagementSettings" ], "usedByRoots": [], "fields": [ { "name": "tokenCount", "description": "Absolute token limit.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "percentage", "description": "% of model's context window.", "presence": "explicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ThresholdConfigInput", "title": "ThresholdConfig", "slug": "/api/models/threshold-config-input", "description": "Threshold configuration for triggering compaction", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "ThresholdConfig", "slug": "/api/models/threshold-config" }, "usedBy": [ "conversations:createThread", "conversations:updateContextManagementSettings" ], "usedByRoots": [], "fields": [ { "name": "tokenCount", "description": "Absolute token limit.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "percentage", "description": "% of model's context window.", "presence": "explicit", "required": false, "requestRequired": false } ] }, { "schemaName": "TimeAwareConfig", "title": "TimeAwareConfig", "slug": "/api/models/time-aware-config", "description": "Configuration for time-aware LLM generation.\nControls injection of temporal context (current time, message timestamps,\nfile timestamps) into the LLM context during generation.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "TimeAwareConfig", "slug": "/api/models/time-aware-config" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "includeCurrentTime", "description": "Append the current date and time to the system prompt as temporal context. Default: true.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "includeMessageTimestamps", "description": "Include timestamps on messages in the model context. Requires the message timestamp to be\npopulated. Default: false.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "includeFileTimestamps", "description": "Include upload/modification timestamps when resolving FILE_ID content.\nWhen true, resolved file references include \"[Uploaded: ]\" annotations.\nDefault: false", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "timezone", "description": "Timezone for formatting (IANA format, e.g., \"America/Los_Angeles\").\nDefault: \"UTC\"", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "timestampFormat", "description": "Format pattern for timestamps.\n\"friendly\" (default): \"Jan 2, 2026 at 3:04 PM MST\"\n\"iso8601\": \"2026-01-02T15:04:00-08:00\"\n\"date_only\": \"2026-01-02\"", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "TimeAwareConfigInput", "title": "TimeAwareConfig", "slug": "/api/models/time-aware-config-input", "description": "Configuration for time-aware LLM generation.\nControls injection of temporal context (current time, message timestamps,\nfile timestamps) into the LLM context during generation.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "TimeAwareConfig", "slug": "/api/models/time-aware-config" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:appendMessage", "conversations:createThread", "conversations:sendMessage", "conversations:sendMessageSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [ "generation-config" ], "fields": [ { "name": "includeCurrentTime", "description": "Append the current date and time to the system prompt as temporal context. Default: true.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "includeMessageTimestamps", "description": "Include timestamps on messages in the model context. Requires the message timestamp to be\npopulated. Default: false.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "includeFileTimestamps", "description": "Include upload/modification timestamps when resolving FILE_ID content.\nWhen true, resolved file references include \"[Uploaded: ]\" annotations.\nDefault: false", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "timezone", "description": "Timezone for formatting (IANA format, e.g., \"America/Los_Angeles\").\nDefault: \"UTC\"", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "timestampFormat", "description": "Format pattern for timestamps.\n\"friendly\" (default): \"Jan 2, 2026 at 3:04 PM MST\"\n\"iso8601\": \"2026-01-02T15:04:00-08:00\"\n\"date_only\": \"2026-01-02\"", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "TimeAwareConfigWebhook", "title": "TimeAwareConfig", "slug": "/api/models/time-aware-config-webhook", "description": "Configuration for time-aware LLM generation.\nControls injection of temporal context (current time, message timestamps,\nfile timestamps) into the LLM context during generation.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "TimeAwareConfig", "slug": "/api/models/time-aware-config" }, "usedBy": [], "usedByRoots": [ "llm.generation_started", "llm.message_published" ], "fields": [ { "name": "include_current_time", "description": "Append the current date and time to the system prompt as temporal context. Default: true.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "include_message_timestamps", "description": "Include timestamps on messages in the model context. Requires the message timestamp to be\npopulated. Default: false.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "include_file_timestamps", "description": "Include upload/modification timestamps when resolving FILE_ID content.\nWhen true, resolved file references include \"[Uploaded: ]\" annotations.\nDefault: false", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "timezone", "description": "Timezone for formatting (IANA format, e.g., \"America/Los_Angeles\").\nDefault: \"UTC\"", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "timestamp_format", "description": "Format pattern for timestamps.\n\"friendly\" (default): \"Jan 2, 2026 at 3:04 PM MST\"\n\"iso8601\": \"2026-01-02T15:04:00-08:00\"\n\"date_only\": \"2026-01-02\"", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "TimeoutPolicy", "title": "TimeoutPolicy", "slug": "/api/models/timeout-policy", "description": "Bounds the run as a whole. This message has no per-tool or per-loop execution\ntimeout. Approval and client-result answer windows are configured separately on\nToolExecutionPolicy; those waits do not cancel an already dispatched remote action.\n\nSet a finite [`timeouts.overallMs`](/api/models/timeout-policy#request-field-overallms)\nwhen the task needs a duration limit. It is measured from run start; zero or\nomission leaves the run-level duration unbounded.\n\nWhen Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and\npending calls can be closed with `endReason: \"run_timed_out\"`. A call still awaiting\napproval has not been dispatched. The timeout does not guarantee a remote action\nstops at that instant, establish whether it took effect, or roll it back.\n\nUse [`endReason`](/api/models/tool-call#response-field-endreason) to distinguish a\nrun deadline from a call's own answer window: an unanswered approval reads\n`approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the\nactual tool status too; approval and client-tool expiry can produce `FAILED` or\n`TIMED_OUT`. Run and individual tool outcomes are different fields.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "TimeoutPolicy", "slug": "/api/models/timeout-policy" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "conversations:updatePromptVariables", "conversations:updateSettings", "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "overallMs", "description": "Overall run budget in milliseconds, measured from run start. Zero or omission\nleaves this run-level bound unset. The workflow checks the deadline and can end\nwith AGENT_STATUS_TIMED_OUT; it cannot cancel or undo a remote action already\ndispatched. Approval and client-result waits retain their separate finite limits.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "TimeoutPolicyInput", "title": "TimeoutPolicy", "slug": "/api/models/timeout-policy-input", "description": "Bounds the run as a whole. This message has no per-tool or per-loop execution\ntimeout. Approval and client-result answer windows are configured separately on\nToolExecutionPolicy; those waits do not cancel an already dispatched remote action.\n\nSet a finite [`timeouts.overallMs`](/api/models/timeout-policy#request-field-overallms)\nwhen the task needs a duration limit. It is measured from run start; zero or\nomission leaves the run-level duration unbounded.\n\nWhen Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and\npending calls can be closed with `endReason: \"run_timed_out\"`. A call still awaiting\napproval has not been dispatched. The timeout does not guarantee a remote action\nstops at that instant, establish whether it took effect, or roll it back.\n\nUse [`endReason`](/api/models/tool-call#response-field-endreason) to distinguish a\nrun deadline from a call's own answer window: an unanswered approval reads\n`approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the\nactual tool status too; approval and client-tool expiry can produce `FAILED` or\n`TIMED_OUT`. Run and individual tool outcomes are different fields.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "TimeoutPolicy", "slug": "/api/models/timeout-policy" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:appendMessage", "conversations:createThread", "conversations:sendMessage", "conversations:sendMessageSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "conversations:updateSettings", "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [ "generation-config" ], "fields": [ { "name": "overallMs", "description": "Overall run budget in milliseconds, measured from run start. Zero or omission\nleaves this run-level bound unset. The workflow checks the deadline and can end\nwith AGENT_STATUS_TIMED_OUT; it cannot cancel or undo a remote action already\ndispatched. Approval and client-result waits retain their separate finite limits.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "TimeoutPolicyWebhook", "title": "TimeoutPolicy", "slug": "/api/models/timeout-policy-webhook", "description": "Bounds the run as a whole. This message has no per-tool or per-loop execution\ntimeout. Approval and client-result answer windows are configured separately on\nToolExecutionPolicy; those waits do not cancel an already dispatched remote action.\n\nSet a finite [`timeouts.overallMs`](/api/models/timeout-policy#request-field-overallms)\nwhen the task needs a duration limit. It is measured from run start; zero or\nomission leaves the run-level duration unbounded.\n\nWhen Travila observes that the budget has elapsed, the run can end `TIMED_OUT` and\npending calls can be closed with `endReason: \"run_timed_out\"`. A call still awaiting\napproval has not been dispatched. The timeout does not guarantee a remote action\nstops at that instant, establish whether it took effect, or roll it back.\n\nUse [`endReason`](/api/models/tool-call#response-field-endreason) to distinguish a\nrun deadline from a call's own answer window: an unanswered approval reads\n`approval_timeout`, and an unanswered client tool reads `client_timeout`. Read the\nactual tool status too; approval and client-tool expiry can produce `FAILED` or\n`TIMED_OUT`. Run and individual tool outcomes are different fields.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "TimeoutPolicy", "slug": "/api/models/timeout-policy" }, "usedBy": [], "usedByRoots": [ "llm.generation_started", "llm.message_published" ], "fields": [ { "name": "overall_ms", "description": "Overall run budget in milliseconds, measured from run start. Zero or omission\nleaves this run-level bound unset. The workflow checks the deadline and can end\nwith AGENT_STATUS_TIMED_OUT; it cannot cancel or undo a remote action already\ndispatched. Approval and client-result waits retain their separate finite limits.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "TimeSeriesPoint", "title": "TimeSeriesPoint", "slug": "/api/models/time-series-point", "description": "Numeric evaluation measurement associated with a time bucket and series.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "TimeSeriesPoint", "slug": "/api/models/time-series-point" }, "usedBy": [ "evals:getOverview" ], "usedByRoots": [], "fields": [ { "name": "bucket", "description": "Time bucket identifying this point in the evaluation series.", "presence": "message", "required": false, "requestRequired": false }, { "name": "value", "description": "Numeric measurement recorded for this time bucket and series.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "series", "description": "Series key when the query is split — a score name, level, or profile id.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ToolApproval", "title": "ToolApproval", "slug": "/api/models/tool-approval", "description": "Approval decision for a specific tool call", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "ToolApproval", "slug": "/api/models/tool-approval" }, "usedBy": [ "conversations:submitToolApprovals" ], "usedByRoots": [], "fields": [ { "name": "toolCallId", "description": "Identifier of the tool call being approved, executed, or retrieved.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "toolName", "description": "Name of the tool associated with the call or result.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "approved", "description": "Whether the caller approves execution of the identified tool call.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "reason", "description": "Optional rejection reason.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ToolCall", "title": "ToolCall", "slug": "/api/models/tool-call", "description": "A single structured tool call emitted by the model\n\n[`clientToolDeadlineAt`](/api/models/tool-call#response-field-clienttooldeadlineat) is the client answer\nwindow. Expiry ends that wait and rejects late results; the timeout policy determines the outcome.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "ToolCall", "slug": "/api/models/tool-call" }, "usedBy": [ "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:getToolCall", "conversations:listPendingApprovals", "conversations:listPendingClientTools", "conversations:mcpCallTool", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "id", "description": "Provider-supplied call id.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Name of the tool or function being invoked.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "argumentsJson", "description": "JSON object payload.", "presence": "message", "required": false, "requestRequired": false }, { "name": "status", "description": "Execution status recorded for the tool call.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "resultJson", "description": "Tool execution result (object).", "presence": "message", "required": false, "requestRequired": false }, { "name": "executedAt", "description": "Time when the tool execution was recorded.", "presence": "message", "required": false, "requestRequired": false }, { "name": "serverId", "description": "Which server provides this tool (for MCP tools).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "isClientTool", "description": "True if this is a client-side tool handled by client.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Tool description captured when the call is emitted, preserving the definition used for\nhistorical calls even if the tool configuration later changes.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "parametersJsonSchema", "description": "JSON Schema describing the tool’s input arguments.", "presence": "message", "required": false, "requestRequired": false }, { "name": "requiresApprovalAt", "description": "Deadline for an approval decision, calculated from the effective approval timeout. This is not\nthe time the call began waiting. An approval received after the deadline is rejected.", "presence": "message", "required": false, "requestRequired": false }, { "name": "approvedAt", "description": "Timestamp when approval decision was recorded (if approved/rejected)", "presence": "message", "required": false, "requestRequired": false }, { "name": "approvedBy", "description": "Identifier of the approver (user id, email, or actor key)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "executionDuration", "description": "End-to-end execution duration once terminal (includes tool server latency or client-side time)", "presence": "message", "required": false, "requestRequired": false }, { "name": "endReason", "description": "Why this call ended, in one short phrase — \"approval rejected\",\n\"approval timeout\", the underlying error. Set only once `status` is\nterminal, and empty on a clean COMPLETED.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "clientToolDeadlineAt", "description": "Deadline by which the client must submit a result for this call, stamped\nwhen the call is dispatched to a caller. Mirrors requires_approval_at.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ToolCallCompletedEventWebhook", "title": "ToolCallCompletedEvent", "slug": "/api/models/tool-call-completed-event-webhook", "description": "Event emitted when a tool call reaches COMPLETED, FAILED, CANCELLED or TIMED_OUT, including\ncalls that required human approval.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "webhooks", "role": "domain-model", "title": "ToolCallCompletedEvent", "slug": "/api/models/tool-call-completed-event" }, "usedBy": [], "usedByRoots": [ "llm.tool_call_completed" ], "fields": [ { "name": "event_context", "description": "Event provenance and routing metadata associated with the emitted event.", "presence": "message", "required": false, "requestRequired": false }, { "name": "tool_call", "description": "Final tool call: status is terminal (SUCCESS|FAILED|CANCELLED|TIMED_OUT),\nresult_json populated.", "presence": "message", "required": false, "requestRequired": false }, { "name": "execution_time_ms", "description": "Wall-clock execution time in milliseconds (0 when unknown, e.g. dispatch error).", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ToolCallInput", "title": "ToolCall", "slug": "/api/models/tool-call-input", "description": "A single structured tool call emitted by the model\n\n[`clientToolDeadlineAt`](/api/models/tool-call#response-field-clienttooldeadlineat) is the client answer\nwindow. Expiry ends that wait and rejects late results; the timeout policy determines the outcome.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "ToolCall", "slug": "/api/models/tool-call" }, "usedBy": [ "conversations:appendMessage", "conversations:mcpCallTool", "conversations:sendMessage", "conversations:sendMessageSync" ], "usedByRoots": [], "fields": [ { "name": "id", "description": "Provider-supplied call id.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Name of the tool or function being invoked.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "argumentsJson", "description": "JSON object payload.", "presence": "message", "required": false, "requestRequired": false }, { "name": "status", "description": "Execution status recorded for the tool call.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "resultJson", "description": "Tool execution result (object).", "presence": "message", "required": false, "requestRequired": false }, { "name": "executedAt", "description": "Time when the tool execution was recorded.", "presence": "message", "required": false, "requestRequired": false }, { "name": "serverId", "description": "Which server provides this tool (for MCP tools).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "isClientTool", "description": "True if this is a client-side tool handled by client.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Tool description captured when the call is emitted, preserving the definition used for\nhistorical calls even if the tool configuration later changes.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "parametersJsonSchema", "description": "JSON Schema describing the tool’s input arguments.", "presence": "message", "required": false, "requestRequired": false }, { "name": "requiresApprovalAt", "description": "Deadline for an approval decision, calculated from the effective approval timeout. This is not\nthe time the call began waiting. An approval received after the deadline is rejected.", "presence": "message", "required": false, "requestRequired": false }, { "name": "approvedAt", "description": "Timestamp when approval decision was recorded (if approved/rejected)", "presence": "message", "required": false, "requestRequired": false }, { "name": "approvedBy", "description": "Identifier of the approver (user id, email, or actor key)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "executionDuration", "description": "End-to-end execution duration once terminal (includes tool server latency or client-side time)", "presence": "message", "required": false, "requestRequired": false }, { "name": "endReason", "description": "Why this call ended, in one short phrase — \"approval rejected\",\n\"approval timeout\", the underlying error. Set only once `status` is\nterminal, and empty on a clean COMPLETED.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "clientToolDeadlineAt", "description": "Deadline by which the client must submit a result for this call, stamped\nwhen the call is dispatched to a caller. Mirrors requires_approval_at.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ToolCallStartedEventWebhook", "title": "ToolCallStartedEvent", "slug": "/api/models/tool-call-started-event-webhook", "description": "Event for a tool call that has begun execution or is waiting for human approval. Check the event\nname and tool-call status to distinguish these cases; the event context identifies the\nconversation.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "webhooks", "role": "domain-model", "title": "ToolCallStartedEvent", "slug": "/api/models/tool-call-started-event" }, "usedBy": [], "usedByRoots": [ "llm.tool_call_approval_required", "llm.tool_call_started" ], "fields": [ { "name": "event_context", "description": "Event provenance and routing metadata associated with the emitted event.", "presence": "message", "required": false, "requestRequired": false }, { "name": "tool_call", "description": "Tool-call snapshot before a result is available, including its identity, name, server and\narguments. For llm.tool_call_started the status is EXECUTING; for\nllm.tool_call_approval_required it is REQUIRES_CONFIRMATION and requires_approval_at is the\ndecision deadline. result_json is unset.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ToolCallWebhook", "title": "ToolCall", "slug": "/api/models/tool-call-webhook", "description": "A single structured tool call emitted by the model\n\n[`clientToolDeadlineAt`](/api/models/tool-call#response-field-clienttooldeadlineat) is the client answer\nwindow. Expiry ends that wait and rejects late results; the timeout policy determines the outcome.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "ToolCall", "slug": "/api/models/tool-call" }, "usedBy": [], "usedByRoots": [ "llm.message_published", "llm.tool_call_approval_required", "llm.tool_call_completed", "llm.tool_call_started" ], "fields": [ { "name": "id", "description": "Provider-supplied call id.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Name of the tool or function being invoked.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "arguments_json", "description": "JSON object payload.", "presence": "message", "required": false, "requestRequired": false }, { "name": "status", "description": "Execution status recorded for the tool call.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "result_json", "description": "Tool execution result (object).", "presence": "message", "required": false, "requestRequired": false }, { "name": "executed_at", "description": "Time when the tool execution was recorded.", "presence": "message", "required": false, "requestRequired": false }, { "name": "server_id", "description": "Which server provides this tool (for MCP tools).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "is_client_tool", "description": "True if this is a client-side tool handled by client.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Tool description captured when the call is emitted, preserving the definition used for\nhistorical calls even if the tool configuration later changes.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "parameters_json_schema", "description": "JSON Schema describing the tool’s input arguments.", "presence": "message", "required": false, "requestRequired": false }, { "name": "requires_approval_at", "description": "Deadline for an approval decision, calculated from the effective approval timeout. This is not\nthe time the call began waiting. An approval received after the deadline is rejected.", "presence": "message", "required": false, "requestRequired": false }, { "name": "approved_at", "description": "Timestamp when approval decision was recorded (if approved/rejected)", "presence": "message", "required": false, "requestRequired": false }, { "name": "approved_by", "description": "Identifier of the approver (user id, email, or actor key)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "execution_duration", "description": "End-to-end execution duration once terminal (includes tool server latency or client-side time)", "presence": "message", "required": false, "requestRequired": false }, { "name": "end_reason", "description": "Why this call ended, in one short phrase — \"approval rejected\",\n\"approval timeout\", the underlying error. Set only once `status` is\nterminal, and empty on a clean COMPLETED.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "client_tool_deadline_at", "description": "Deadline by which the client must submit a result for this call, stamped\nwhen the call is dispatched to a caller. Mirrors requires_approval_at.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ToolChoice", "title": "ToolChoice", "slug": "/api/models/tool-choice", "description": "Policy selecting automatic tool choice, no tool use, or a named tool.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "ToolChoice", "slug": "/api/models/tool-choice" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "kind", "description": "Discriminator selecting the representation or policy used by this message.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "specificToolName", "description": "Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ToolChoiceInput", "title": "ToolChoice", "slug": "/api/models/tool-choice-input", "description": "Policy selecting automatic tool choice, no tool use, or a named tool.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "ToolChoice", "slug": "/api/models/tool-choice" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:appendMessage", "conversations:createThread", "conversations:sendMessage", "conversations:sendMessageSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [ "generation-config" ], "fields": [ { "name": "kind", "description": "Discriminator selecting the representation or policy used by this message.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "specificToolName", "description": "Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ToolChoiceWebhook", "title": "ToolChoice", "slug": "/api/models/tool-choice-webhook", "description": "Policy selecting automatic tool choice, no tool use, or a named tool.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "ToolChoice", "slug": "/api/models/tool-choice" }, "usedBy": [], "usedByRoots": [ "llm.generation_started", "llm.message_published" ], "fields": [ { "name": "kind", "description": "Discriminator selecting the representation or policy used by this message.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "specific_tool_name", "description": "Only used when kind = TOOL_CHOICE_KIND_SPECIFIC.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ToolDefinition", "title": "ToolDefinition", "slug": "/api/models/tool-definition", "description": "Canonical tool/function definition used across all services\n\n**[`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.\n\n**[`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.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "ToolDefinition", "slug": "/api/models/tool-definition" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:mcpGetServerInfo", "conversations:mcpListTools", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "name", "description": "Name used to select and invoke the tool.", "presence": "implicit", "required": false, "requestRequired": true }, { "name": "description", "description": "Explanation of the tool’s purpose supplied to the model and callers.", "presence": "implicit", "required": false, "requestRequired": true }, { "name": "parametersJsonSchema", "description": "JSON Schema object.", "presence": "message", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Additional tool metadata (version, category, etc.).", "presence": "collection", "required": false, "requestRequired": false }, { "name": "serverId", "description": "Which server provides this tool (for MCP tools).", "presence": "implicit", "required": false, "requestRequired": true }, { "name": "tags", "description": "Tool categorization tags.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "documentationUrl", "description": "Link to detailed documentation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "outputJsonSchema", "description": "Optional output schema (JSON Schema serialized as string) describing structured results", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ToolDefinitionInput", "title": "ToolDefinition", "slug": "/api/models/tool-definition-input", "description": "Canonical tool/function definition used across all services\n\n**[`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.\n\n**[`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.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "ToolDefinition", "slug": "/api/models/tool-definition" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:appendMessage", "conversations:createThread", "conversations:sendMessage", "conversations:sendMessageSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [ "generation-config" ], "fields": [ { "name": "name", "description": "Name used to select and invoke the tool.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "description", "description": "Explanation of the tool’s purpose supplied to the model and callers.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "parametersJsonSchema", "description": "JSON Schema object.", "presence": "message", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Additional tool metadata (version, category, etc.).", "presence": "collection", "required": false, "requestRequired": false }, { "name": "serverId", "description": "Which server provides this tool (for MCP tools).", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "tags", "description": "Tool categorization tags.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "documentationUrl", "description": "Link to detailed documentation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "outputJsonSchema", "description": "Optional output schema (JSON Schema serialized as string) describing structured results", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ToolDefinitionWebhook", "title": "ToolDefinition", "slug": "/api/models/tool-definition-webhook", "description": "Canonical tool/function definition used across all services\n\n**[`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.\n\n**[`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.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "ToolDefinition", "slug": "/api/models/tool-definition" }, "usedBy": [], "usedByRoots": [ "llm.generation_started", "llm.message_published" ], "fields": [ { "name": "name", "description": "Name used to select and invoke the tool.", "presence": "implicit", "required": false, "requestRequired": true }, { "name": "description", "description": "Explanation of the tool’s purpose supplied to the model and callers.", "presence": "implicit", "required": false, "requestRequired": true }, { "name": "parameters_json_schema", "description": "JSON Schema object.", "presence": "message", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Additional tool metadata (version, category, etc.).", "presence": "collection", "required": false, "requestRequired": false }, { "name": "server_id", "description": "Which server provides this tool (for MCP tools).", "presence": "implicit", "required": false, "requestRequired": true }, { "name": "tags", "description": "Tool categorization tags.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "documentation_url", "description": "Link to detailed documentation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "output_json_schema", "description": "Optional output schema (JSON Schema serialized as string) describing structured results", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "ToolExecutionOrderRule", "title": "ToolExecutionOrderRule", "slug": "/api/models/tool-execution-order-rule", "description": "Requested ordering rule for tool execution. The current generation workflow stores\nthese rules but does not apply their patterns, server filters or weights.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "ToolExecutionOrderRule", "slug": "/api/models/tool-execution-order-rule" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "conversations:updatePromptVariables", "conversations:updateSettings", "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "toolNamePatterns", "description": "Requested tool-name patterns; not evaluated by the current generation workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "serverIds", "description": "Requested MCP server filter; not evaluated by the current generation workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "weight", "description": "Requested ordering weight; not applied by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ToolExecutionOrderRuleInput", "title": "ToolExecutionOrderRule", "slug": "/api/models/tool-execution-order-rule-input", "description": "Requested ordering rule for tool execution. The current generation workflow stores\nthese rules but does not apply their patterns, server filters or weights.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "ToolExecutionOrderRule", "slug": "/api/models/tool-execution-order-rule" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:appendMessage", "conversations:createThread", "conversations:sendMessage", "conversations:sendMessageSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "conversations:updateSettings", "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [ "generation-config" ], "fields": [ { "name": "toolNamePatterns", "description": "Requested tool-name patterns; not evaluated by the current generation workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "serverIds", "description": "Requested MCP server filter; not evaluated by the current generation workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "weight", "description": "Requested ordering weight; not applied by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ToolExecutionOrderRuleWebhook", "title": "ToolExecutionOrderRule", "slug": "/api/models/tool-execution-order-rule-webhook", "description": "Requested ordering rule for tool execution. The current generation workflow stores\nthese rules but does not apply their patterns, server filters or weights.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "ToolExecutionOrderRule", "slug": "/api/models/tool-execution-order-rule" }, "usedBy": [], "usedByRoots": [ "llm.generation_started", "llm.message_published" ], "fields": [ { "name": "tool_name_patterns", "description": "Requested tool-name patterns; not evaluated by the current generation workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "server_ids", "description": "Requested MCP server filter; not evaluated by the current generation workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "weight", "description": "Requested ordering weight; not applied by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "ToolExecutionPolicy", "title": "ToolExecutionPolicy", "slug": "/api/models/tool-execution-policy", "description": "Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget\nand answer windows. Some stored controls are not enforced by the current workflow.\n\nIf an expected approval does not appear, inspect the tool/server require rules and\nauto-approve exceptions. Auto-approve takes precedence; server IDs are compared\ncase-insensitively after trimming whitespace. An exception does not establish that\nthe user reviewed the action.\n\nAn omitted or zero [`approvalTimeoutMs`](/api/models/tool-execution-policy#request-field-approvaltimeoutms)\nwaits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#request-field-failonapprovaltimeouttoolnamepatterns)\nyields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes\nevery expiry `FAILED`.\n\nThe retry controls [`retriableToolNamePatterns`](/api/models/tool-execution-policy#request-field-retriabletoolnamepatterns),\n[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),\n[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),\n[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and\n[`retryBackoff`](/api/models/tool-execution-policy#request-field-retrybackoff) are\nstored but do not schedule retries. Ordering rules, tie-breaking, the per-loop\ncall cap, client-tool scheduling mode, failure mode and stop-on-failure rules are\nalso not enforced; do not rely on them as execution or safety controls.\n\n[`maxTotalToolCalls`](/api/models/tool-execution-policy#request-field-maxtotaltoolcalls)\nlimits admitted calls across the run; zero or omission leaves the cap unset. A\nclient call consumes budget when armed. A routable MCP call consumes budget before\napproval, including when held for approval or later rejected. Unknown tools and\ncalls refused because the cap is already exhausted do not consume budget. Further\ncalls at the limit receive `FAILED` tool results naming the limit, which the model\ncan use when continuing the run.\n\n[`maxParallelToolCalls`](/api/models/tool-execution-policy#request-field-maxparalleltoolcalls)\nlimits concurrent MCP execution. Zero or one runs MCP calls sequentially; values\ngreater than one permit concurrency. Client calls are armed separately, and your\napplication controls their execution concurrency.\n\nChoose [`clientToolTimeoutMs`](/api/models/tool-execution-policy#request-field-clienttooltimeoutms)\nfor your application's validation and action. Zero or omission gives a five-minute\nanswer window; there is no unbounded setting. Each call returns its resolved\n[`clientToolDeadlineAt`](/api/models/tool-call#response-field-clienttooldeadlineat).\n\nSee [Tool execution policies](/api/tool-execution/policies) for policy selection and\ncaller reconciliation.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "ToolExecutionPolicy", "slug": "/api/models/tool-execution-policy" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "conversations:updatePromptVariables", "conversations:updateSettings", "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "requireApprovalToolNamePatterns", "description": "Approvals\nTool-name patterns selecting calls that require an approval decision.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "requireApprovalServerIds", "description": "MCP server identifiers whose calls require approval. IDs are compared case-insensitively\nafter trimming whitespace.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "autoApproveToolNamePatterns", "description": "Tool-name patterns whose matching calls may be approved automatically.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "autoApproveServerIds", "description": "MCP server identifiers exempted from approval require rules. IDs are compared\ncase-insensitively after trimming whitespace.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "approvalMode", "description": "How to schedule execution when approvals are required for some tools", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "clientToolMode", "description": "Stored requested client-tool scheduling mode; not enforced by the current workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "approvalTimeoutMs", "description": "Time allowed for an approval decision, in milliseconds. Zero or omission selects the\nfive-minute default; a positive value overrides it. There is no unbounded wait setting.\nAt expiry, matching fail_on_approval_timeout_tool_name_patterns produces FAILED;\nother calls become TIMED_OUT. An empty pattern list makes every expiry FAILED.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "failOnApprovalTimeoutToolNamePatterns", "description": "Selects approval timeouts reported as FAILED; nonmatching calls become TIMED_OUT.\nAn empty list makes every approval expiry FAILED. Global failure_mode is not enforced.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "orderRules", "description": "Stored requested ordering rules; not applied by the current generation workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "stableSortByCallIndexOnTie", "description": "Stored requested ordering tie-breaker; not applied by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxParallelToolCalls", "description": "Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls\nsequentially; larger values permit concurrency. Client calls are armed separately,\nand their execution concurrency is controlled by the caller application.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxToolCallsPerLoop", "description": "Stored requested per-loop tool-call cap; not enforced by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxTotalToolCalls", "description": "Maximum admitted tool calls across the run; zero or omission leaves the cap unset.\nClient calls count when armed. Routable MCP calls count before approval, including\ncalls later rejected. Unknown tools and calls refused by an exhausted cap do not count.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "retriableToolNamePatterns", "description": "Stored requested retry selection; does not enable retries in the current workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "maxRetries", "description": "Stored requested retry count; does not enable retries in the current workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "retryBackoff", "description": "Stored requested retry delays; not applied by the current generation workflow.", "presence": "message", "required": false, "requestRequired": false }, { "name": "retryableErrorSubstrings", "description": "Stored requested retryable-error selection; not evaluated by the current workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "nonRetryableErrorSubstrings", "description": "Stored requested retry exclusions; not evaluated by the current generation workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "timeouts", "description": "Timeouts\nOverall execution time budget for the generation run.", "presence": "message", "required": false, "requestRequired": false }, { "name": "clientToolTimeoutMs", "description": "Time allowed for a client-side tool result, in milliseconds. Zero or omission selects\nthe five-minute default; a positive value overrides it. There is no unbounded wait.\nThe resolved answer deadline is returned as clientToolDeadlineAt on each call.\nA result arriving after the deadline is rejected. At expiry, an empty or matching\nfail_on_approval_timeout_tool_name_patterns list yields FAILED; other calls become TIMED_OUT.\nExpiry closes the answer window and does not cancel a client action already in progress.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "failureMode", "description": "Stored requested failure action; not enforced by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "stopOnFailureRules", "description": "Stored requested stop rules; not evaluated by the current generation workflow.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "ToolExecutionPolicyInput", "title": "ToolExecutionPolicy", "slug": "/api/models/tool-execution-policy-input", "description": "Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget\nand answer windows. Some stored controls are not enforced by the current workflow.\n\nIf an expected approval does not appear, inspect the tool/server require rules and\nauto-approve exceptions. Auto-approve takes precedence; server IDs are compared\ncase-insensitively after trimming whitespace. An exception does not establish that\nthe user reviewed the action.\n\nAn omitted or zero [`approvalTimeoutMs`](/api/models/tool-execution-policy#request-field-approvaltimeoutms)\nwaits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#request-field-failonapprovaltimeouttoolnamepatterns)\nyields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes\nevery expiry `FAILED`.\n\nThe retry controls [`retriableToolNamePatterns`](/api/models/tool-execution-policy#request-field-retriabletoolnamepatterns),\n[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),\n[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),\n[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and\n[`retryBackoff`](/api/models/tool-execution-policy#request-field-retrybackoff) are\nstored but do not schedule retries. Ordering rules, tie-breaking, the per-loop\ncall cap, client-tool scheduling mode, failure mode and stop-on-failure rules are\nalso not enforced; do not rely on them as execution or safety controls.\n\n[`maxTotalToolCalls`](/api/models/tool-execution-policy#request-field-maxtotaltoolcalls)\nlimits admitted calls across the run; zero or omission leaves the cap unset. A\nclient call consumes budget when armed. A routable MCP call consumes budget before\napproval, including when held for approval or later rejected. Unknown tools and\ncalls refused because the cap is already exhausted do not consume budget. Further\ncalls at the limit receive `FAILED` tool results naming the limit, which the model\ncan use when continuing the run.\n\n[`maxParallelToolCalls`](/api/models/tool-execution-policy#request-field-maxparalleltoolcalls)\nlimits concurrent MCP execution. Zero or one runs MCP calls sequentially; values\ngreater than one permit concurrency. Client calls are armed separately, and your\napplication controls their execution concurrency.\n\nChoose [`clientToolTimeoutMs`](/api/models/tool-execution-policy#request-field-clienttooltimeoutms)\nfor your application's validation and action. Zero or omission gives a five-minute\nanswer window; there is no unbounded setting. Each call returns its resolved\n[`clientToolDeadlineAt`](/api/models/tool-call#response-field-clienttooldeadlineat).\n\nSee [Tool execution policies](/api/tool-execution/policies) for policy selection and\ncaller reconciliation.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "ToolExecutionPolicy", "slug": "/api/models/tool-execution-policy" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:appendMessage", "conversations:createThread", "conversations:sendMessage", "conversations:sendMessageSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "conversations:updateSettings", "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [ "generation-config" ], "fields": [ { "name": "requireApprovalToolNamePatterns", "description": "Approvals\nTool-name patterns selecting calls that require an approval decision.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "requireApprovalServerIds", "description": "MCP server identifiers whose calls require approval. IDs are compared case-insensitively\nafter trimming whitespace.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "autoApproveToolNamePatterns", "description": "Tool-name patterns whose matching calls may be approved automatically.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "autoApproveServerIds", "description": "MCP server identifiers exempted from approval require rules. IDs are compared\ncase-insensitively after trimming whitespace.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "approvalMode", "description": "How to schedule execution when approvals are required for some tools", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "clientToolMode", "description": "Stored requested client-tool scheduling mode; not enforced by the current workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "approvalTimeoutMs", "description": "Time allowed for an approval decision, in milliseconds. Zero or omission selects the\nfive-minute default; a positive value overrides it. There is no unbounded wait setting.\nAt expiry, matching fail_on_approval_timeout_tool_name_patterns produces FAILED;\nother calls become TIMED_OUT. An empty pattern list makes every expiry FAILED.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "failOnApprovalTimeoutToolNamePatterns", "description": "Selects approval timeouts reported as FAILED; nonmatching calls become TIMED_OUT.\nAn empty list makes every approval expiry FAILED. Global failure_mode is not enforced.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "orderRules", "description": "Stored requested ordering rules; not applied by the current generation workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "stableSortByCallIndexOnTie", "description": "Stored requested ordering tie-breaker; not applied by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxParallelToolCalls", "description": "Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls\nsequentially; larger values permit concurrency. Client calls are armed separately,\nand their execution concurrency is controlled by the caller application.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxToolCallsPerLoop", "description": "Stored requested per-loop tool-call cap; not enforced by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxTotalToolCalls", "description": "Maximum admitted tool calls across the run; zero or omission leaves the cap unset.\nClient calls count when armed. Routable MCP calls count before approval, including\ncalls later rejected. Unknown tools and calls refused by an exhausted cap do not count.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "retriableToolNamePatterns", "description": "Stored requested retry selection; does not enable retries in the current workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "maxRetries", "description": "Stored requested retry count; does not enable retries in the current workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "retryBackoff", "description": "Stored requested retry delays; not applied by the current generation workflow.", "presence": "message", "required": false, "requestRequired": false }, { "name": "retryableErrorSubstrings", "description": "Stored requested retryable-error selection; not evaluated by the current workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "nonRetryableErrorSubstrings", "description": "Stored requested retry exclusions; not evaluated by the current generation workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "timeouts", "description": "Timeouts\nOverall execution time budget for the generation run.", "presence": "message", "required": false, "requestRequired": false }, { "name": "clientToolTimeoutMs", "description": "Time allowed for a client-side tool result, in milliseconds. Zero or omission selects\nthe five-minute default; a positive value overrides it. There is no unbounded wait.\nThe resolved answer deadline is returned as clientToolDeadlineAt on each call.\nA result arriving after the deadline is rejected. At expiry, an empty or matching\nfail_on_approval_timeout_tool_name_patterns list yields FAILED; other calls become TIMED_OUT.\nExpiry closes the answer window and does not cancel a client action already in progress.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "failureMode", "description": "Stored requested failure action; not enforced by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "stopOnFailureRules", "description": "Stored requested stop rules; not evaluated by the current generation workflow.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "ToolExecutionPolicyWebhook", "title": "ToolExecutionPolicy", "slug": "/api/models/tool-execution-policy-webhook", "description": "Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget\nand answer windows. Some stored controls are not enforced by the current workflow.\n\nIf an expected approval does not appear, inspect the tool/server require rules and\nauto-approve exceptions. Auto-approve takes precedence; server IDs are compared\ncase-insensitively after trimming whitespace. An exception does not establish that\nthe user reviewed the action.\n\nAn omitted or zero [`approvalTimeoutMs`](/api/models/tool-execution-policy#request-field-approvaltimeoutms)\nwaits five minutes. At expiry, [`failOnApprovalTimeoutToolNamePatterns`](/api/models/tool-execution-policy#request-field-failonapprovaltimeouttoolnamepatterns)\nyields `FAILED` for matching calls and `TIMED_OUT` for others; an unset list makes\nevery expiry `FAILED`.\n\nThe retry controls [`retriableToolNamePatterns`](/api/models/tool-execution-policy#request-field-retriabletoolnamepatterns),\n[`retryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-retryableerrorsubstrings),\n[`nonRetryableErrorSubstrings`](/api/models/tool-execution-policy#request-field-nonretryableerrorsubstrings),\n[`maxRetries`](/api/models/tool-execution-policy#request-field-maxretries) and\n[`retryBackoff`](/api/models/tool-execution-policy#request-field-retrybackoff) are\nstored but do not schedule retries. Ordering rules, tie-breaking, the per-loop\ncall cap, client-tool scheduling mode, failure mode and stop-on-failure rules are\nalso not enforced; do not rely on them as execution or safety controls.\n\n[`maxTotalToolCalls`](/api/models/tool-execution-policy#request-field-maxtotaltoolcalls)\nlimits admitted calls across the run; zero or omission leaves the cap unset. A\nclient call consumes budget when armed. A routable MCP call consumes budget before\napproval, including when held for approval or later rejected. Unknown tools and\ncalls refused because the cap is already exhausted do not consume budget. Further\ncalls at the limit receive `FAILED` tool results naming the limit, which the model\ncan use when continuing the run.\n\n[`maxParallelToolCalls`](/api/models/tool-execution-policy#request-field-maxparalleltoolcalls)\nlimits concurrent MCP execution. Zero or one runs MCP calls sequentially; values\ngreater than one permit concurrency. Client calls are armed separately, and your\napplication controls their execution concurrency.\n\nChoose [`clientToolTimeoutMs`](/api/models/tool-execution-policy#request-field-clienttooltimeoutms)\nfor your application's validation and action. Zero or omission gives a five-minute\nanswer window; there is no unbounded setting. Each call returns its resolved\n[`clientToolDeadlineAt`](/api/models/tool-call#response-field-clienttooldeadlineat).\n\nSee [Tool execution policies](/api/tool-execution/policies) for policy selection and\ncaller reconciliation.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "delegation-approvals", "role": "domain-model", "title": "ToolExecutionPolicy", "slug": "/api/models/tool-execution-policy" }, "usedBy": [], "usedByRoots": [ "llm.generation_started", "llm.message_published" ], "fields": [ { "name": "require_approval_tool_name_patterns", "description": "Approvals\nTool-name patterns selecting calls that require an approval decision.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "require_approval_server_ids", "description": "MCP server identifiers whose calls require approval. IDs are compared case-insensitively\nafter trimming whitespace.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "auto_approve_tool_name_patterns", "description": "Tool-name patterns whose matching calls may be approved automatically.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "auto_approve_server_ids", "description": "MCP server identifiers exempted from approval require rules. IDs are compared\ncase-insensitively after trimming whitespace.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "approval_mode", "description": "How to schedule execution when approvals are required for some tools", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "client_tool_mode", "description": "Stored requested client-tool scheduling mode; not enforced by the current workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "approval_timeout_ms", "description": "Time allowed for an approval decision, in milliseconds. Zero or omission selects the\nfive-minute default; a positive value overrides it. There is no unbounded wait setting.\nAt expiry, matching fail_on_approval_timeout_tool_name_patterns produces FAILED;\nother calls become TIMED_OUT. An empty pattern list makes every expiry FAILED.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "fail_on_approval_timeout_tool_name_patterns", "description": "Selects approval timeouts reported as FAILED; nonmatching calls become TIMED_OUT.\nAn empty list makes every approval expiry FAILED. Global failure_mode is not enforced.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "order_rules", "description": "Stored requested ordering rules; not applied by the current generation workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "stable_sort_by_call_index_on_tie", "description": "Stored requested ordering tie-breaker; not applied by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "max_parallel_tool_calls", "description": "Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls\nsequentially; larger values permit concurrency. Client calls are armed separately,\nand their execution concurrency is controlled by the caller application.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "max_tool_calls_per_loop", "description": "Stored requested per-loop tool-call cap; not enforced by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "max_total_tool_calls", "description": "Maximum admitted tool calls across the run; zero or omission leaves the cap unset.\nClient calls count when armed. Routable MCP calls count before approval, including\ncalls later rejected. Unknown tools and calls refused by an exhausted cap do not count.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "retriable_tool_name_patterns", "description": "Stored requested retry selection; does not enable retries in the current workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "max_retries", "description": "Stored requested retry count; does not enable retries in the current workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "retry_backoff", "description": "Stored requested retry delays; not applied by the current generation workflow.", "presence": "message", "required": false, "requestRequired": false }, { "name": "retryable_error_substrings", "description": "Stored requested retryable-error selection; not evaluated by the current workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "non_retryable_error_substrings", "description": "Stored requested retry exclusions; not evaluated by the current generation workflow.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "timeouts", "description": "Timeouts\nOverall execution time budget for the generation run.", "presence": "message", "required": false, "requestRequired": false }, { "name": "client_tool_timeout_ms", "description": "Time allowed for a client-side tool result, in milliseconds. Zero or omission selects\nthe five-minute default; a positive value overrides it. There is no unbounded wait.\nThe resolved answer deadline is returned as clientToolDeadlineAt on each call.\nA result arriving after the deadline is rejected. At expiry, an empty or matching\nfail_on_approval_timeout_tool_name_patterns list yields FAILED; other calls become TIMED_OUT.\nExpiry closes the answer window and does not cancel a client action already in progress.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "failure_mode", "description": "Stored requested failure action; not enforced by the current generation workflow.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "stop_on_failure_rules", "description": "Stored requested stop rules; not evaluated by the current generation workflow.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "TopicSubscriptionError", "title": "TopicSubscriptionError", "slug": "/api/models/topic-subscription-error", "description": "Subscriber-specific failure reported while changing notification-topic membership.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "domain-model", "title": "TopicSubscriptionError", "slug": "/api/models/topic-subscription-error" }, "usedBy": [ "notifications:addSubscribersToTopic", "notifications:removeSubscribersFromTopic" ], "usedByRoots": [], "fields": [ { "name": "subscriberId", "description": "Identifier of the notification subscriber.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "code", "description": "Provider error code for the topic subscription failure.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "message", "description": "Diagnostic or descriptive text returned by the operation.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "TopicSubscriptionResult", "title": "TopicSubscriptionResult", "slug": "/api/models/topic-subscription-result", "description": "Result of a topic subscription operation (add/remove subscribers).\nNovu returns partial success — some subscribers may fail while others succeed.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "domain-model", "title": "TopicSubscriptionResult", "slug": "/api/models/topic-subscription-result" }, "usedBy": [ "notifications:addSubscribersToTopic", "notifications:removeSubscribersFromTopic" ], "usedByRoots": [], "fields": [ { "name": "totalCount", "description": "Total number of matching entries reported by the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "successful", "description": "Number of subscribers accepted by the topic subscription operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "failed", "description": "Number of subscribers rejected by the topic subscription operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "errors", "description": "Errors reported while processing notification requests.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "TraceDetail", "title": "TraceDetail", "slug": "/api/models/trace-detail", "description": "Evaluation trace summary together with its observations and attached scores.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "TraceDetail", "slug": "/api/models/trace-detail" }, "usedBy": [ "evals:getTrace" ], "usedByRoots": [], "fields": [ { "name": "summary", "description": "Summary information for the evaluation trace or session.", "presence": "message", "required": false, "requestRequired": false }, { "name": "observations", "description": "Observations associated with the trace or returned by the query.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "scores", "description": "Evaluation scores returned for the selected objects or query.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "TraceSummary", "title": "TraceSummary", "slug": "/api/models/trace-summary", "description": "Evaluation summary for a conversation turn, including its recorded conversation, message and\nprofile attribution.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "domain-model", "title": "TraceSummary", "slug": "/api/models/trace-summary" }, "usedBy": [ "evals:getSession", "evals:getTrace", "evals:listTraces" ], "usedByRoots": [], "fields": [ { "name": "traceId", "description": "Identifier of the evaluation trace.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Name recorded for the evaluation trace.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "timestamp", "description": "Timestamp associated with the conversation message or event.", "presence": "message", "required": false, "requestRequired": false }, { "name": "inputJson", "description": "Evaluation input serialized as JSON.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "outputJson", "description": "Evaluation output serialized as JSON.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "latencySeconds", "description": "Elapsed observation latency, in seconds.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "totalCost", "description": "Total cost reported for the evaluated generation or aggregate.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "environment", "description": "Environment label attached to the evaluation record.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "tags", "description": "Labels associated with the resource for organization or filtering.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "metadataJson", "description": "Additional attributes serialized as a JSON object.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "bookmarked", "description": "Whether the evaluation object is bookmarked.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "version", "description": "Version of the resource represented by this message.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "release", "description": "Application release identifier attached to the trace.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "userId", "description": "Identifier of the user associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sessionId", "description": "Identifier of the evaluation session grouping related traces.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "observationCount", "description": "Number of observations reported for the evaluation object.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "conversationId", "description": "Identifier of the conversation associated with the trace.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sourceUserMessageId", "description": "Identifier of the user message that opened the evaluated generation turn.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "profileId", "description": "Identifier of the agent profile associated with the generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "configHash", "description": "Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation\nresults. Other settings are excluded; this is not an immutable profile revision.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "inputTokens", "description": "Input-token usage reported for the evaluated generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "outputTokens", "description": "Output-token usage reported for the evaluated generation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "totalTokens", "description": "Total token usage reported for the evaluated generation or aggregate.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "errorCount", "description": "Number of observations reported at error level.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "warningCount", "description": "Number of observations reported at warning level.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "defaultCount", "description": "Number of observations reported at the default level.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "debugCount", "description": "Number of observations reported at debug level.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "scores", "description": "Evaluation scores returned for the selected objects or query.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "commentCount", "description": "Number of comments reported on the evaluation object.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "TranscriptionBucketConfig", "title": "TranscriptionBucketConfig", "slug": "/api/models/transcription-bucket-config", "description": "Object-storage destination and access settings for Daily transcriptions.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "voice-media", "role": "domain-model", "title": "TranscriptionBucketConfig", "slug": "/api/models/transcription-bucket-config" }, "usedBy": [ "conversations:createDailySession" ], "usedByRoots": [], "fields": [ { "name": "bucketName", "description": "Object-storage bucket used for Daily recordings or transcriptions.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "bucketRegion", "description": "Region containing the Daily recording or transcription bucket.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "assumeRoleArn", "description": "Role ARN Daily uses when accessing the storage bucket.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "allowApiAccess", "description": "Whether Daily API access to bucket content is enabled.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "TranscriptionBucketConfigInput", "title": "TranscriptionBucketConfig", "slug": "/api/models/transcription-bucket-config-input", "description": "Object-storage destination and access settings for Daily transcriptions.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "voice-media", "role": "domain-model", "title": "TranscriptionBucketConfig", "slug": "/api/models/transcription-bucket-config" }, "usedBy": [ "conversations:createDailySession" ], "usedByRoots": [], "fields": [ { "name": "bucketName", "description": "Object-storage bucket used for Daily recordings or transcriptions.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "bucketRegion", "description": "Region containing the Daily recording or transcription bucket.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "assumeRoleArn", "description": "Role ARN Daily uses when accessing the storage bucket.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "allowApiAccess", "description": "Whether Daily API access to bucket content is enabled.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "TransportConfig", "title": "TransportConfig", "slug": "/api/models/transport-config", "description": "Transport audio configuration", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "voice-media", "role": "domain-model", "title": "TransportConfig", "slug": "/api/models/transport-config" }, "usedBy": [ "conversations:createDailySession" ], "usedByRoots": [], "fields": [ { "name": "audioInSampleRate", "description": "Sample rate of incoming audio, in hertz.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "audioOutSampleRate", "description": "Sample rate of outgoing audio, in hertz.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "TTSConfig", "title": "TTSConfig", "slug": "/api/models/tts-config", "description": "Cartesia Sonic-3 TTS configuration", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "voice-media", "role": "domain-model", "title": "TTSConfig", "slug": "/api/models/tts-config" }, "usedBy": [ "conversations:createDailySession" ], "usedByRoots": [], "fields": [ { "name": "voiceId", "description": "Provider-specific voice identifier (Cartesia voice_id)", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "model", "description": "Optional Cartesia model identifier (e.g., \"sonic-english\")", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "sampleRate", "description": "Optional sample rate override (Hz)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "volume", "description": "Volume multiplier (0.5..2.0)", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "speed", "description": "Speed multiplier (0.6..1.5)", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "emotion", "description": "Single emotion string (e.g., \"neutral\", \"excited\")", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "language", "description": "Cartesia language code (e.g., \"EN\")", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "TurnContextConfig", "title": "TurnContextConfig", "slug": "/api/models/turn-context-config", "description": "Configuration for turn-aware LLM generation\n\nTurn 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.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "TurnContextConfig", "slug": "/api/models/turn-context-config" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "enabled", "description": "Enable turn context injection into system prompt\nDefault: true", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "includeToolGuidance", "description": "Include tool usage guidance based on remaining turns\nDefault: false (can enable for agentic workflows)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "format", "description": "Format for turn context\n\"minimal\": \"[Turn 2/5]\"\n\"standard\": \"[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]\"\n\"verbose\": Includes detailed behavioral guidance\nDefault: \"standard\"", "presence": "implicit", "required": false, "requestRequired": true } ] }, { "schemaName": "TurnContextConfigInput", "title": "TurnContextConfig", "slug": "/api/models/turn-context-config-input", "description": "Configuration for turn-aware LLM generation\n\nTurn 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.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "TurnContextConfig", "slug": "/api/models/turn-context-config" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:appendMessage", "conversations:createThread", "conversations:sendMessage", "conversations:sendMessageSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [ "generation-config" ], "fields": [ { "name": "enabled", "description": "Enable turn context injection into system prompt\nDefault: true", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "includeToolGuidance", "description": "Include tool usage guidance based on remaining turns\nDefault: false (can enable for agentic workflows)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "format", "description": "Format for turn context\n\"minimal\": \"[Turn 2/5]\"\n\"standard\": \"[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]\"\n\"verbose\": Includes detailed behavioral guidance\nDefault: \"standard\"", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "TurnContextConfigWebhook", "title": "TurnContextConfig", "slug": "/api/models/turn-context-config-webhook", "description": "Configuration for turn-aware LLM generation\n\nTurn 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.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "TurnContextConfig", "slug": "/api/models/turn-context-config" }, "usedBy": [], "usedByRoots": [ "llm.generation_started", "llm.message_published" ], "fields": [ { "name": "enabled", "description": "Enable turn context injection into system prompt\nDefault: true", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "include_tool_guidance", "description": "Include tool usage guidance based on remaining turns\nDefault: false (can enable for agentic workflows)", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "format", "description": "Format for turn context\n\"minimal\": \"[Turn 2/5]\"\n\"standard\": \"[Turn 2 of 5 - 3 turns remaining. Plan your response accordingly.]\"\n\"verbose\": Includes detailed behavioral guidance\nDefault: \"standard\"", "presence": "implicit", "required": false, "requestRequired": true } ] }, { "schemaName": "TurnInfo", "title": "TurnInfo", "slug": "/api/models/turn-info", "description": "Turn position within an agentic generation run", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "TurnInfo", "slug": "/api/models/turn-info" }, "usedBy": [ "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "currentTurn", "description": "Current turn position within the generation run.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxTurns", "description": "Maximum turns configured for the generation run.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "TurnInfoInput", "title": "TurnInfo", "slug": "/api/models/turn-info-input", "description": "Turn position within an agentic generation run", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "TurnInfo", "slug": "/api/models/turn-info" }, "usedBy": [ "conversations:appendMessage", "conversations:sendMessage", "conversations:sendMessageSync" ], "usedByRoots": [], "fields": [ { "name": "currentTurn", "description": "Current turn position within the generation run.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "maxTurns", "description": "Maximum turns configured for the generation run.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "TurnInfoWebhook", "title": "TurnInfo", "slug": "/api/models/turn-info-webhook", "description": "Turn position within an agentic generation run", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "TurnInfo", "slug": "/api/models/turn-info" }, "usedBy": [], "usedByRoots": [ "llm.message_published" ], "fields": [ { "name": "current_turn", "description": "Current turn position within the generation run.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "max_turns", "description": "Maximum turns configured for the generation run.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "UnarchiveInboxMessageRequest", "title": "UnarchiveInboxMessageRequest", "slug": "/api/models/unarchive-inbox-message-request", "description": "Inputs for restoring an archived notification to the subscriber’s inbox feed.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "UnarchiveInboxMessageRequest", "slug": "/api/models/unarchive-inbox-message-request" }, "usedBy": [ "notifications:unarchiveInboxMessage" ], "usedByRoots": [], "fields": [ { "name": "notificationId", "description": "Identifier of the notification whose inbox entry is being modified.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "UnarchiveInboxMessageResponse", "title": "UnarchiveInboxMessageResponse", "slug": "/api/models/unarchive-inbox-message-response", "description": "Result payload for restoring an archived notification to the subscriber’s inbox feed.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "UnarchiveInboxMessageResponse", "slug": "/api/models/unarchive-inbox-message-response" }, "usedBy": [ "notifications:unarchiveInboxMessage" ], "usedByRoots": [], "fields": [ { "name": "status", "description": "Status reported by the notification provider.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "UnregisterPushDeviceRequest", "title": "UnregisterPushDeviceRequest", "slug": "/api/models/unregister-push-device-request", "description": "Caller user_id derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "UnregisterPushDeviceRequest", "slug": "/api/models/unregister-push-device-request" }, "usedBy": [ "notifications:unregisterPushDevice" ], "usedByRoots": [], "fields": [ { "name": "fcmToken", "description": "Firebase Cloud Messaging token identifying the push delivery target.", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "UnregisterPushDeviceResponse", "title": "UnregisterPushDeviceResponse", "slug": "/api/models/unregister-push-device-response", "description": "Result payload for removing an FCM token from the user’s registered push delivery targets.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "UnregisterPushDeviceResponse", "slug": "/api/models/unregister-push-device-response" }, "usedBy": [ "notifications:unregisterPushDevice" ], "usedByRoots": [], "fields": [ { "name": "subscriberId", "description": "Identifier of the notification subscriber.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "remainingCredentialCount", "description": "Number of push credentials remaining after unregistering the device.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateAgentProfileRequest", "title": "UpdateAgentProfileRequest", "slug": "/api/models/update-agent-profile-request", "description": "=== Update ===\nInputs for changing selected agent-profile fields and producing an updated revision.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "UpdateAgentProfileRequest", "slug": "/api/models/update-agent-profile-request" }, "usedBy": [ "agent-profiles:updateAgentProfile" ], "usedByRoots": [], "fields": [ { "name": "projectId", "description": "Identifier of the project associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "profileId", "description": "Identifier of the agent profile associated with the operation or generation.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "profile", "description": "Carries the new field values.", "presence": "message", "required": false, "requestRequired": false }, { "name": "updateMask", "description": "Field paths selecting which values to modify. Omitted or empty: only the fields the\nprofile sets change, at every depth.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateAgentProfileResponse", "title": "UpdateAgentProfileResponse", "slug": "/api/models/update-agent-profile-response", "description": "Result payload for changing selected agent-profile fields and producing an updated revision.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "UpdateAgentProfileResponse", "slug": "/api/models/update-agent-profile-response" }, "usedBy": [ "agent-profiles:updateAgentProfile" ], "usedByRoots": [], "fields": [ { "name": "profile", "description": "Agent profile returned by the operation.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateContextManagementSettingsRequest", "title": "UpdateContextManagementSettingsRequest", "slug": "/api/models/update-context-management-settings-request", "description": "Input for updating the conversation’s context compaction configuration.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "UpdateContextManagementSettingsRequest", "slug": "/api/models/update-context-management-settings-request" }, "usedBy": [ "conversations:updateContextManagementSettings" ], "usedByRoots": [], "fields": [ { "name": "conversationKey", "description": "Identifier of the conversation thread.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "contextManagementSettings", "description": "Configuration governing the conversation’s context management and compaction.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateContextManagementSettingsResponse", "title": "UpdateContextManagementSettingsResponse", "slug": "/api/models/update-context-management-settings-response", "description": "Result of updating the conversation’s context compaction configuration.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "UpdateContextManagementSettingsResponse", "slug": "/api/models/update-context-management-settings-response" }, "usedBy": [ "conversations:updateContextManagementSettings" ], "usedByRoots": [], "fields": [ { "name": "contextManagementSettings", "description": "Configuration governing the conversation’s context management and compaction.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateCustomMCPServerRequest", "title": "UpdateCustomMCPServerRequest", "slug": "/api/models/update-custom-mcp-server-request", "description": "Inputs for changing a tenant-owned MCP server’s connection configuration.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "UpdateCustomMCPServerRequest", "slug": "/api/models/update-custom-mcp-server-request" }, "usedBy": [ "mcp-servers:updateCustomMcpServer" ], "usedByRoots": [], "fields": [ { "name": "projectId", "description": "Identifier of the project associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "serverId", "description": "Identifier of the MCP server associated with the operation or tool.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "server", "description": "MCP server record supplied to or returned by the operation.", "presence": "message", "required": true, "requestRequired": true } ] }, { "schemaName": "UpdateCustomMCPServerResponse", "title": "UpdateCustomMCPServerResponse", "slug": "/api/models/update-custom-mcp-server-response", "description": "Result payload for changing a tenant-owned MCP server’s connection configuration.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "tools-connections", "role": "operation-envelope", "title": "UpdateCustomMCPServerResponse", "slug": "/api/models/update-custom-mcp-server-response" }, "usedBy": [ "mcp-servers:updateCustomMcpServer" ], "usedByRoots": [], "fields": [ { "name": "server", "description": "MCP server record supplied to or returned by the operation.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateDatasetItemRequest", "title": "UpdateDatasetItemRequest", "slug": "/api/models/update-dataset-item-request", "description": "Inputs for updating an input and expected-output pair in an evaluation dataset.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "UpdateDatasetItemRequest", "slug": "/api/models/update-dataset-item-request" }, "usedBy": [ "evals:updateDatasetItem" ], "usedByRoots": [], "fields": [ { "name": "itemId", "description": "Identifier of the dataset item or annotation queue item being addressed.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "datasetId", "description": "Identifier of the evaluation dataset.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "inputJson", "description": "Dataset item input serialized as JSON text.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "expectedOutputJson", "description": "Expected dataset item output serialized as JSON text.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadataJson", "description": "Additional evaluation metadata serialized as JSON text.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "status", "description": "Whether the evaluation dataset item is active or archived.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateDatasetItemResponse", "title": "UpdateDatasetItemResponse", "slug": "/api/models/update-dataset-item-response", "description": "Result of updating an input and expected-output pair in an evaluation dataset.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "UpdateDatasetItemResponse", "slug": "/api/models/update-dataset-item-response" }, "usedBy": [ "evals:updateDatasetItem" ], "usedByRoots": [], "fields": [ { "name": "itemId", "description": "Identifier of the dataset item or annotation queue item being addressed.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateFileMetadataRequest", "title": "UpdateFileMetadataRequest", "slug": "/api/models/update-file-metadata-request", "description": "Inputs for changing labels, description, or custom attributes of a stored file.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "UpdateFileMetadataRequest", "slug": "/api/models/update-file-metadata-request" }, "usedBy": [ "storage:updateFileMetadata" ], "usedByRoots": [], "fields": [ { "name": "fileId", "description": "Stable identifier of the stored file.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Additional attributes associated with the resource.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "tags", "description": "Labels associated with the resource for organization or filtering.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "description", "description": "Human-readable description of the resource.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateFileMetadataResponse", "title": "UpdateFileMetadataResponse", "slug": "/api/models/update-file-metadata-response", "description": "Result payload for changing labels, description, or custom attributes of a stored file.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "UpdateFileMetadataResponse", "slug": "/api/models/update-file-metadata-response" }, "usedBy": [ "storage:updateFileMetadata" ], "usedByRoots": [], "fields": [ { "name": "file", "description": "Metadata for the file affected or retrieved by the operation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "updated", "description": "Whether the file metadata update reports a change.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateGlobalPreferenceRequest", "title": "UpdateGlobalPreferenceRequest", "slug": "/api/models/update-global-preference-request", "description": "Inputs for changing the subscriber’s channel preferences across notification workflows.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "UpdateGlobalPreferenceRequest", "slug": "/api/models/update-global-preference-request" }, "usedBy": [ "notifications:updateGlobalPreference" ], "usedByRoots": [], "fields": [ { "name": "channels", "description": "Channel switches to update for the subscriber.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateJobRequest", "title": "UpdateJobRequest", "slug": "/api/models/update-job-request", "description": "Inputs for updating a scheduled job and its trigger settings.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "scheduling", "role": "operation-envelope", "title": "UpdateJobRequest", "slug": "/api/models/update-job-request" }, "usedBy": [ "scheduled-jobs:updateJob" ], "usedByRoots": [], "fields": [ { "name": "scheduleId", "description": "Identifier of the scheduled job.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "name", "description": "Human-readable name assigned to the scheduled job.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Human-readable explanation of the scheduled job.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "cronExpression", "description": "Cron expression defining when the scheduled job runs.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "timezone", "description": "IANA time zone associated with the record or schedule.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "scheduledAt", "description": "Instant at which a one-time scheduled job should run.", "presence": "message", "required": false, "requestRequired": false }, { "name": "intervalSeconds", "description": "Interval between scheduled triggers, in seconds.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "target", "description": "Destination and invocation settings for the scheduled job.", "presence": "message", "required": false, "requestRequired": false }, { "name": "retryPolicy", "description": "Attempt limits and backoff settings for the scheduled target.", "presence": "message", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Application-defined JSON metadata attached to the scheduled job.", "presence": "message", "required": false, "requestRequired": false }, { "name": "autoPauseThreshold", "description": "Consecutive failure threshold used to pause the scheduled job.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "externalId", "description": "Lookup reference only. Exactly one of schedule_id / external_id must be set.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateJobResponse", "title": "UpdateJobResponse", "slug": "/api/models/update-job-response", "description": "UpdateJob keeps a dedicated response wrapper (rather than the bare Schedule\nthe other mutations return) because it carries response-only metadata that\nis not part of the persisted resource.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "scheduling", "role": "operation-envelope", "title": "UpdateJobResponse", "slug": "/api/models/update-job-response" }, "usedBy": [ "scheduled-jobs:updateJob" ], "usedByRoots": [], "fields": [ { "name": "schedule", "description": "Scheduled job returned by the operation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "effectiveAt", "description": "When the update takes effect. Current updates return immediate; next_resync and\nnext_worker_deployment are legacy values that are no longer emitted. The returned schedule’s\nnext_trigger_at identifies its next firing.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateLocaleRequest", "title": "UpdateLocaleRequest", "slug": "/api/models/update-locale-request", "description": "Inputs for updating the end user's locale preference.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "identity-access", "role": "operation-envelope", "title": "UpdateLocaleRequest", "slug": "/api/models/update-locale-request" }, "usedBy": [ "end-users:updateLocale" ], "usedByRoots": [], "fields": [ { "name": "locale", "description": "BCP-47 locale override, such as \"es-MX\". Empty string clears the override.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateLocaleResponse", "title": "UpdateLocaleResponse", "slug": "/api/models/update-locale-response", "description": "Result of updating the end user's locale preference. This schema declares no result fields.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "identity-access", "role": "operation-envelope", "title": "UpdateLocaleResponse", "slug": "/api/models/update-locale-response" }, "usedBy": [ "end-users:updateLocale" ], "usedByRoots": [], "fields": [] }, { "schemaName": "UpdateLocationRequest", "title": "UpdateLocationRequest", "slug": "/api/models/update-location-request", "description": "Inputs for updating the end user's geographic coordinates.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "identity-access", "role": "operation-envelope", "title": "UpdateLocationRequest", "slug": "/api/models/update-location-request" }, "usedBy": [ "end-users:updateLocation" ], "usedByRoots": [], "fields": [ { "name": "latitude", "description": "Latitude of the location in decimal degrees.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "longitude", "description": "Longitude of the location in decimal degrees.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateLocationResponse", "title": "UpdateLocationResponse", "slug": "/api/models/update-location-response", "description": "Result of updating the end user's geographic coordinates.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "identity-access", "role": "operation-envelope", "title": "UpdateLocationResponse", "slug": "/api/models/update-location-response" }, "usedBy": [ "end-users:updateLocation" ], "usedByRoots": [], "fields": [ { "name": "location", "description": "Coordinates and derived location metadata stored for the end user. Includes derived IANA\ntimezone.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateMemoryRequest", "title": "UpdateMemoryRequest", "slug": "/api/models/update-memory-request", "description": "Input for replacing the text of a memory record.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "memory-knowledge", "role": "operation-envelope", "title": "UpdateMemoryRequest", "slug": "/api/models/update-memory-request" }, "usedBy": [ "conversations:updateMemory" ], "usedByRoots": [], "fields": [ { "name": "memoryId", "description": "Memory ID to update", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "text", "description": "New memory text content", "presence": "implicit", "required": true, "requestRequired": true } ] }, { "schemaName": "UpdateMemoryResponse", "title": "UpdateMemoryResponse", "slug": "/api/models/update-memory-response", "description": "Result of replacing the text of a memory record. This message declares no response fields.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "memory-knowledge", "role": "operation-envelope", "title": "UpdateMemoryResponse", "slug": "/api/models/update-memory-response" }, "usedBy": [ "conversations:updateMemory" ], "usedByRoots": [], "fields": [] }, { "schemaName": "UpdateMetadataRequest", "title": "UpdateMetadataRequest", "slug": "/api/models/update-metadata-request", "description": "Inputs for updating the end user's profile metadata.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "identity-access", "role": "operation-envelope", "title": "UpdateMetadataRequest", "slug": "/api/models/update-metadata-request" }, "usedBy": [ "end-users:updateMetadata" ], "usedByRoots": [], "fields": [ { "name": "metadata", "description": "Application-defined key-value metadata associated with the end user.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateMetadataResponse", "title": "UpdateMetadataResponse", "slug": "/api/models/update-metadata-response", "description": "Result of updating the end user's profile metadata. This schema declares no result fields.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "identity-access", "role": "operation-envelope", "title": "UpdateMetadataResponse", "slug": "/api/models/update-metadata-response" }, "usedBy": [ "end-users:updateMetadata" ], "usedByRoots": [], "fields": [] }, { "schemaName": "UpdatePromptFragmentRequest", "title": "UpdatePromptFragmentRequest", "slug": "/api/models/update-prompt-fragment-request", "description": "=== Update fragment ===\nInputs for changing selected fields of a reusable prompt fragment.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "UpdatePromptFragmentRequest", "slug": "/api/models/update-prompt-fragment-request" }, "usedBy": [ "agent-profiles:updatePromptFragment" ], "usedByRoots": [], "fields": [ { "name": "projectId", "description": "Identifier of the project associated with the operation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "fragmentId", "description": "Identifier of the reusable prompt fragment.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "fragment", "description": "Carries the new field values.", "presence": "message", "required": false, "requestRequired": false }, { "name": "updateMask", "description": "Field paths selecting which values to modify.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdatePromptFragmentResponse", "title": "UpdatePromptFragmentResponse", "slug": "/api/models/update-prompt-fragment-response", "description": "Result payload for changing selected fields of a reusable prompt fragment.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "profiles-prompts", "role": "operation-envelope", "title": "UpdatePromptFragmentResponse", "slug": "/api/models/update-prompt-fragment-response" }, "usedBy": [ "agent-profiles:updatePromptFragment" ], "usedByRoots": [], "fields": [ { "name": "fragment", "description": "Reusable prompt fragment returned by the operation.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdatePromptVariablesRequest", "title": "UpdatePromptVariablesRequest", "slug": "/api/models/update-prompt-variables-request", "description": "Inputs for merging updated prompt variables into a conversation. The profile template is\nrendered with the updated variables on the next turn.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "UpdatePromptVariablesRequest", "slug": "/api/models/update-prompt-variables-request" }, "usedBy": [ "conversations:updatePromptVariables" ], "usedByRoots": [], "fields": [ { "name": "conversationKey", "description": "Identifier of the conversation thread.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "variables", "description": "Prompt-variable values to merge into the conversation’s settings.", "presence": "message", "required": false, "requestRequired": false }, { "name": "updateMask", "description": "Field paths selecting which prompt variables to update.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdatePromptVariablesResponse", "title": "UpdatePromptVariablesResponse", "slug": "/api/models/update-prompt-variables-response", "description": "Result of merging prompt variables into conversation settings.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "UpdatePromptVariablesResponse", "slug": "/api/models/update-prompt-variables-response" }, "usedBy": [ "conversations:updatePromptVariables" ], "usedByRoots": [], "fields": [ { "name": "settings", "description": "The merged conversation settings (mirrors UpdateSettingsResponse).", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateScoreConfigRequest", "title": "UpdateScoreConfigRequest", "slug": "/api/models/update-score-config-request", "description": "Partial update of a score configuration. Unset fields retain their values; is_archived changes\narchival state. The score data type and categories cannot be changed through this request.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "UpdateScoreConfigRequest", "slug": "/api/models/update-score-config-request" }, "usedBy": [ "evals:updateScoreConfig" ], "usedByRoots": [], "fields": [ { "name": "configId", "description": "Identifier of the evaluation score configuration.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "name", "description": "Name assigned to, or used to filter, the evaluation record.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Human-readable explanation of the evaluation record.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "minValue", "description": "Lower numeric bound for the score range.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "maxValue", "description": "Upper numeric bound for the score range.", "presence": "explicit", "required": false, "requestRequired": false }, { "name": "isArchived", "description": "Whether the score configuration is marked as archived.", "presence": "explicit", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateScoreConfigResponse", "title": "UpdateScoreConfigResponse", "slug": "/api/models/update-score-config-response", "description": "Result of updating the definition and allowed values of an evaluation score.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "evaluation", "role": "operation-envelope", "title": "UpdateScoreConfigResponse", "slug": "/api/models/update-score-config-response" }, "usedBy": [ "evals:updateScoreConfig" ], "usedByRoots": [], "fields": [ { "name": "config", "description": "Score configuration returned after the update.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateSettingsRequest", "title": "UpdateSettingsRequest", "slug": "/api/models/update-settings-request", "description": "Input for updating the conversation’s settings.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "UpdateSettingsRequest", "slug": "/api/models/update-settings-request" }, "usedBy": [ "conversations:updateSettings" ], "usedByRoots": [], "fields": [ { "name": "conversationKey", "description": "Identifier of the conversation thread.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "settings", "description": "Conversation settings returned or supplied for this operation.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateSettingsResponse", "title": "UpdateSettingsResponse", "slug": "/api/models/update-settings-response", "description": "Result of updating the conversation’s settings.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "operation-envelope", "title": "UpdateSettingsResponse", "slug": "/api/models/update-settings-response" }, "usedBy": [ "conversations:updateSettings" ], "usedByRoots": [], "fields": [ { "name": "settings", "description": "Conversation settings returned or supplied for this operation.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateSubscriberDataRequest", "title": "UpdateSubscriberDataRequest", "slug": "/api/models/update-subscriber-data-request", "description": "Caller user_id derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "UpdateSubscriberDataRequest", "slug": "/api/models/update-subscriber-data-request" }, "usedBy": [ "notifications:updateSubscriberData" ], "usedByRoots": [], "fields": [ { "name": "data", "description": "Contact, locale, and custom subscriber attributes to update.", "presence": "message", "required": true, "requestRequired": true } ] }, { "schemaName": "UpdateSubscriberDataResponse", "title": "UpdateSubscriberDataResponse", "slug": "/api/models/update-subscriber-data-response", "description": "Result payload for changing contact, locale, or custom attributes used for notification delivery.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "UpdateSubscriberDataResponse", "slug": "/api/models/update-subscriber-data-response" }, "usedBy": [ "notifications:updateSubscriberData" ], "usedByRoots": [], "fields": [ { "name": "data", "description": "Contact, locale, and custom attributes returned for the subscriber.", "presence": "message", "required": false, "requestRequired": false }, { "name": "updatedAt", "description": "Time when this record was last updated.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateWebhookEndpointRequest", "title": "UpdateWebhookEndpointRequest", "slug": "/api/models/update-webhook-endpoint-request", "description": "Inputs for changing the address or descriptive metadata of a tenant webhook destination.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "webhooks", "role": "operation-envelope", "title": "UpdateWebhookEndpointRequest", "slug": "/api/models/update-webhook-endpoint-request" }, "usedBy": [ "webhooks:updateWebhookEndpoint" ], "usedByRoots": [], "fields": [ { "name": "endpointId", "description": "Identifier of the webhook endpoint receiving deliveries.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "name", "description": "Display name of the tenant’s webhook delivery destination.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "url", "description": "URL associated with the resource or outbound request.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "description", "description": "Human-readable description of the resource.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateWebhookEndpointResponse", "title": "UpdateWebhookEndpointResponse", "slug": "/api/models/update-webhook-endpoint-response", "description": "Result payload for changing the address or descriptive metadata of a tenant webhook destination.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "webhooks", "role": "operation-envelope", "title": "UpdateWebhookEndpointResponse", "slug": "/api/models/update-webhook-endpoint-response" }, "usedBy": [ "webhooks:updateWebhookEndpoint" ], "usedByRoots": [], "fields": [ { "name": "endpoint", "description": "Webhook endpoint returned by the provider operation.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateWorkflowPreferenceRequest", "title": "UpdateWorkflowPreferenceRequest", "slug": "/api/models/update-workflow-preference-request", "description": "Inputs for changing the subscriber’s channel preferences for one notification workflow.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "domain-model", "title": "UpdateWorkflowPreferenceRequest", "slug": "/api/models/update-workflow-preference-request" }, "usedBy": [ "notifications:bulkUpdatePreferences", "notifications:updateWorkflowPreference" ], "usedByRoots": [], "fields": [ { "name": "workflowId", "description": "Identifier of the notification workflow to execute or configure.", "presence": "implicit", "required": true, "requestRequired": true }, { "name": "channels", "description": "Channel switches to update for the subscriber.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateWorkflowRequest", "title": "UpdateWorkflowRequest", "slug": "/api/models/update-workflow-request", "description": "tenant_id and environment derived from auth headers by gateway.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "UpdateWorkflowRequest", "slug": "/api/models/update-workflow-request" }, "usedBy": [ "notifications:updateWorkflow" ], "usedByRoots": [], "fields": [ { "name": "workflowId", "description": "Identifier of the notification workflow to execute or configure.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "workflow", "description": "Notification workflow definition supplied to or returned by the provider.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "UpdateWorkflowResponse", "title": "UpdateWorkflowResponse", "slug": "/api/models/update-workflow-response", "description": "Result payload for changing a registered notification workflow definition.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "operation-envelope", "title": "UpdateWorkflowResponse", "slug": "/api/models/update-workflow-response" }, "usedBy": [ "notifications:updateWorkflow" ], "usedByRoots": [], "fields": [ { "name": "workflow", "description": "Notification workflow definition supplied to or returned by the provider.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "UploadFileRequest", "title": "UploadFileRequest", "slug": "/api/models/upload-file-request", "description": "Inputs for uploading file content and recording its metadata in the selected folder.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "UploadFileRequest", "slug": "/api/models/upload-file-request" }, "usedBy": [ "storage:uploadFile" ], "usedByRoots": [], "fields": [ { "name": "folderPath", "description": "Path of the folder within the user’s storage namespace.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "fileName", "description": "File name to use within the selected folder.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "content", "description": "Raw bytes of the object being uploaded or downloaded.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "contentType", "description": "Media type describing the file or response body.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "metadata", "description": "Additional attributes associated with the resource.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "tags", "description": "Labels associated with the resource for organization or filtering.", "presence": "collection", "required": false, "requestRequired": false } ] }, { "schemaName": "UploadFileResponse", "title": "UploadFileResponse", "slug": "/api/models/upload-file-response", "description": "Result payload for uploading file content and recording its metadata in the selected folder.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "files-data", "role": "operation-envelope", "title": "UploadFileResponse", "slug": "/api/models/upload-file-response" }, "usedBy": [ "storage:uploadFile" ], "usedByRoots": [], "fields": [ { "name": "file", "description": "Metadata for the file affected or retrieved by the operation.", "presence": "message", "required": false, "requestRequired": false }, { "name": "uploaded", "description": "Whether the file upload operation reports completion.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "UpstreamError", "title": "UpstreamError", "slug": "/api/models/upstream-error", "description": "Context from an upstream provider error.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "UpstreamError", "slug": "/api/models/upstream-error" }, "usedBy": [ "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "provider", "description": "Name of the upstream provider that reported the error.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "statusCode", "description": "HTTP status code returned by the provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "rawBody", "description": "Raw error body from the provider. Truncated to 512 bytes (enforced at Go level).", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "UpstreamErrorInput", "title": "UpstreamError", "slug": "/api/models/upstream-error-input", "description": "Context from an upstream provider error.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "UpstreamError", "slug": "/api/models/upstream-error" }, "usedBy": [ "conversations:submitClientToolResults", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "provider", "description": "Name of the upstream provider that reported the error.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "statusCode", "description": "HTTP status code returned by the provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "rawBody", "description": "Raw error body from the provider. Truncated to 512 bytes (enforced at Go level).", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "UpstreamErrorWebhook", "title": "UpstreamError", "slug": "/api/models/upstream-error-webhook", "description": "Context from an upstream provider error.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "shared", "role": "domain-model", "title": "UpstreamError", "slug": "/api/models/upstream-error" }, "usedBy": [], "usedByRoots": [ "llm.generation_completed" ], "fields": [ { "name": "provider", "description": "Name of the upstream provider that reported the error.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "status_code", "description": "HTTP status code returned by the provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "raw_body", "description": "Raw error body from the provider. Truncated to 512 bytes (enforced at Go level).", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "UrlCitation", "title": "UrlCitation", "slug": "/api/models/url-citation", "description": "=== Annotations ===\nWeb source and character range cited in generated message content.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "UrlCitation", "slug": "/api/models/url-citation" }, "usedBy": [ "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "url", "description": "URL associated with the resource or outbound request.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "title", "description": "Title of the web page cited by this annotation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "content", "description": "Excerpt or snippet of the cited web page.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "startIndex", "description": "Character index in message content.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "endIndex", "description": "Character index in message content.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "UrlCitationInput", "title": "UrlCitation", "slug": "/api/models/url-citation-input", "description": "=== Annotations ===\nWeb source and character range cited in generated message content.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "UrlCitation", "slug": "/api/models/url-citation" }, "usedBy": [ "conversations:appendMessage", "conversations:sendMessage", "conversations:sendMessageSync" ], "usedByRoots": [], "fields": [ { "name": "url", "description": "URL associated with the resource or outbound request.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "title", "description": "Title of the web page cited by this annotation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "content", "description": "Excerpt or snippet of the cited web page.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "startIndex", "description": "Character index in message content.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "endIndex", "description": "Character index in message content.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "UrlCitationWebhook", "title": "UrlCitation", "slug": "/api/models/url-citation-webhook", "description": "=== Annotations ===\nWeb source and character range cited in generated message content.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "UrlCitation", "slug": "/api/models/url-citation" }, "usedBy": [], "usedByRoots": [ "llm.message_published" ], "fields": [ { "name": "url", "description": "URL associated with the resource or outbound request.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "title", "description": "Title of the web page cited by this annotation.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "content", "description": "Excerpt or snippet of the cited web page.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "start_index", "description": "Character index in message content.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "end_index", "description": "Character index in message content.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "Usage", "title": "Usage", "slug": "/api/models/usage", "description": "Usage accounting", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "Usage", "slug": "/api/models/usage" }, "usedBy": [ "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync" ], "usedByRoots": [], "fields": [ { "name": "promptTokens", "description": "Prompt-token usage reported by the model provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "completionTokens", "description": "Completion-token usage reported by the model provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "totalTokens", "description": "Total token usage reported by the model provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "costEstimate", "description": "Estimated cost in USD.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "completionTokensDetails", "description": "Breakdown of completion tokens.", "presence": "message", "required": false, "requestRequired": false }, { "name": "promptTokensDetails", "description": "Breakdown of prompt tokens (cache).", "presence": "message", "required": false, "requestRequired": false }, { "name": "costDetails", "description": "Breakdown of upstream provider cost (BYOK routes).", "presence": "message", "required": false, "requestRequired": false }, { "name": "isByok", "description": "Whether this generation used the customer's own model-provider key.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "UsageByModelWebhook", "title": "UsageByModel", "slug": "/api/models/usage-by-model-webhook", "description": "Usage attributed to a single model within one generation run.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "UsageByModel", "slug": "/api/models/usage-by-model" }, "usedBy": [], "usedByRoots": [ "llm.generation_completed" ], "fields": [ { "name": "model", "description": "Model identifier as recorded on the assistant message that produced it.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "calls", "description": "Provider completions attributed to this model within the run.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "usage", "description": "Same shape as the run aggregate, scoped to this model.", "presence": "message", "required": false, "requestRequired": false } ] }, { "schemaName": "UsageInput", "title": "Usage", "slug": "/api/models/usage-input", "description": "Usage accounting", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "Usage", "slug": "/api/models/usage" }, "usedBy": [ "conversations:appendMessage", "conversations:sendMessage", "conversations:sendMessageSync" ], "usedByRoots": [], "fields": [ { "name": "promptTokens", "description": "Prompt-token usage reported by the model provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "completionTokens", "description": "Completion-token usage reported by the model provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "totalTokens", "description": "Total token usage reported by the model provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "costEstimate", "description": "Estimated cost in USD.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "completionTokensDetails", "description": "Breakdown of completion tokens.", "presence": "message", "required": false, "requestRequired": false }, { "name": "promptTokensDetails", "description": "Breakdown of prompt tokens (cache).", "presence": "message", "required": false, "requestRequired": false }, { "name": "costDetails", "description": "Breakdown of upstream provider cost (BYOK routes).", "presence": "message", "required": false, "requestRequired": false }, { "name": "isByok", "description": "Whether this generation used the customer's own model-provider key.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "UsageOptions", "title": "UsageOptions", "slug": "/api/models/usage-options", "description": "Usage accounting preferences", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "UsageOptions", "slug": "/api/models/usage-options" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "include", "description": "Whether usage accounting should be included in the provider response.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "UsageOptionsInput", "title": "UsageOptions", "slug": "/api/models/usage-options-input", "description": "Usage accounting preferences", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "UsageOptions", "slug": "/api/models/usage-options" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:appendMessage", "conversations:createThread", "conversations:sendMessage", "conversations:sendMessageSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [ "generation-config" ], "fields": [ { "name": "include", "description": "Whether usage accounting should be included in the provider response.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "UsageOptionsWebhook", "title": "UsageOptions", "slug": "/api/models/usage-options-webhook", "description": "Usage accounting preferences", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "UsageOptions", "slug": "/api/models/usage-options" }, "usedBy": [], "usedByRoots": [ "llm.generation_started", "llm.message_published" ], "fields": [ { "name": "include", "description": "Whether usage accounting should be included in the provider response.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "UsageWebhook", "title": "Usage", "slug": "/api/models/usage-webhook", "description": "Usage accounting", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "Usage", "slug": "/api/models/usage" }, "usedBy": [], "usedByRoots": [ "llm.generation_completed", "llm.message_published" ], "fields": [ { "name": "prompt_tokens", "description": "Prompt-token usage reported by the model provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "completion_tokens", "description": "Completion-token usage reported by the model provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "total_tokens", "description": "Total token usage reported by the model provider.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "cost_estimate", "description": "Estimated cost in USD.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "completion_tokens_details", "description": "Breakdown of completion tokens.", "presence": "message", "required": false, "requestRequired": false }, { "name": "prompt_tokens_details", "description": "Breakdown of prompt tokens (cache).", "presence": "message", "required": false, "requestRequired": false }, { "name": "cost_details", "description": "Breakdown of upstream provider cost (BYOK routes).", "presence": "message", "required": false, "requestRequired": false }, { "name": "is_byok", "description": "Whether this generation used the customer's own model-provider key.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "WebSearchOptions", "title": "WebSearchOptions", "slug": "/api/models/web-search-options", "description": "Amount of web-search context requested for generation.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "WebSearchOptions", "slug": "/api/models/web-search-options" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:getAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:listAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:deleteMessageRating", "conversations:getConversationState", "conversations:rateMessage", "conversations:sendMessageSync", "conversations:submitClientToolResultsSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:getEndUser" ], "usedByRoots": [], "fields": [ { "name": "searchContextSize", "description": "Requested amount of web-search context: low, medium, or high.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "WebSearchOptionsInput", "title": "WebSearchOptions", "slug": "/api/models/web-search-options-input", "description": "Amount of web-search context requested for generation.", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "WebSearchOptions", "slug": "/api/models/web-search-options" }, "usedBy": [ "agent-profiles:createAgentProfile", "agent-profiles:importAgentProfiles", "agent-profiles:updateAgentProfile", "conversations:appendMessage", "conversations:createThread", "conversations:sendMessage", "conversations:sendMessageSync", "conversations:updateContextManagementSettings", "conversations:updateDefaultGenerationConfig", "end-users:updateDefaultGenerationConfig" ], "usedByRoots": [ "generation-config" ], "fields": [ { "name": "searchContextSize", "description": "Requested amount of web-search context: low, medium, or high.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "WebSearchOptionsWebhook", "title": "WebSearchOptions", "slug": "/api/models/web-search-options-webhook", "description": "Amount of web-search context requested for generation.", "semantics": "", "direction": "response", "serialization": "proto-names", "presentation": { "domain": "model-controls", "role": "domain-model", "title": "WebSearchOptions", "slug": "/api/models/web-search-options" }, "usedBy": [], "usedByRoots": [ "llm.generation_started", "llm.message_published" ], "fields": [ { "name": "search_context_size", "description": "Requested amount of web-search context: low, medium, or high.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "WindowingConfig", "title": "WindowingConfig", "slug": "/api/models/windowing-config", "description": "Configuration for windowing strategy", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "WindowingConfig", "slug": "/api/models/windowing-config" }, "usedBy": [ "conversations:getConversationState", "conversations:updateContextManagementSettings" ], "usedByRoots": [], "fields": [ { "name": "maxMessages", "description": "Maximum number of conversation messages to retain in the context window.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "WindowingConfigInput", "title": "WindowingConfig", "slug": "/api/models/windowing-config-input", "description": "Configuration for windowing strategy", "semantics": "", "direction": "request", "serialization": "json-names", "presentation": { "domain": "conversations", "role": "domain-model", "title": "WindowingConfig", "slug": "/api/models/windowing-config" }, "usedBy": [ "conversations:createThread", "conversations:updateContextManagementSettings" ], "usedByRoots": [], "fields": [ { "name": "maxMessages", "description": "Maximum number of conversation messages to retain in the context window.", "presence": "implicit", "required": false, "requestRequired": false } ] }, { "schemaName": "WorkflowPreferences", "title": "WorkflowPreferences", "slug": "/api/models/workflow-preferences", "description": "Per-workflow notification channel preferences for a subscriber.", "semantics": "", "direction": "response", "serialization": "json-names", "presentation": { "domain": "notifications", "role": "domain-model", "title": "WorkflowPreferences", "slug": "/api/models/workflow-preferences" }, "usedBy": [ "notifications:getPreferences", "notifications:getSubscriber" ], "usedByRoots": [], "fields": [ { "name": "workflowId", "description": "Novu workflow identifier (slug).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "workflowName", "description": "Human-readable display name.", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "critical", "description": "If true, subscriber cannot opt out (admin-enforced).", "presence": "implicit", "required": false, "requestRequired": false }, { "name": "tags", "description": "Workflow tags for grouping in settings UI.", "presence": "collection", "required": false, "requestRequired": false }, { "name": "channels", "description": "Channel switches recorded for these subscriber preferences.", "presence": "message", "required": false, "requestRequired": false } ] } ], "examples": [ { "id": "memory-search-request", "operationId": "searchMemories", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Search dietary preferences", "payload": { "query": "dietary preferences", "topK": 10 }, "operationKey": "conversations:searchMemories", "schemaName": "SearchMemoriesRequest" }, { "id": "memory-search-response", "operationId": "searchMemories", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative dietary preferences returned", "payload": { "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" } ] }, "status": "200", "operationKey": "conversations:searchMemories", "schemaName": "SearchMemoriesResponse" }, { "id": "agent-profiles-createAgentProfile-request", "operationId": "createAgentProfile", "operationKey": "agent-profiles:createAgentProfile", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Create a reusable support profile; choose a new profileId in your project.", "payload": { "profile": { "profileId": "support-assistant", "name": "Support assistant", "whenToUse": "Help users answer product questions.", "generationConfig": { "systemPrompt": "Answer clearly using the supplied product information." } } }, "schemaName": "CreateAgentProfileRequest" }, { "id": "agent-profiles-createAgentProfile-response", "operationId": "createAgentProfile", "operationKey": "agent-profiles:createAgentProfile", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "profile": { "profileId": "example_123", "name": "example", "description": "example", "whenToUse": "example", "keywords": [ "example_123" ], "enabled": true, "generationConfig": { "model": "example", "models": [ "example" ], "systemPrompt": "Example text", "transforms": [ "example" ], "temperature": 1, "topP": 1, "maxOutputTokens": 1, "frequencyPenalty": 1, "presencePenalty": 1, "stopSequences": [ "example" ], "seed": "1", "allowParallelToolCalls": true, "topK": 1, "repetitionPenalty": 1, "topLogprobs": 1, "minP": 1, "topA": 1, "user": "example", "modalities": [ "MODALITY_TEXT" ], "languagePreference": "en-US", "requestTimeoutSeconds": 1, "clearTools": true }, "mcpServers": [ { "serverId": "example_123", "enabled": true, "priority": 1, "allowlistToolPatterns": [ "example" ], "blocklistToolPatterns": [ "example" ] } ], "variableSpecs": [ { "name": "example", "description": "example", "required": true, "defaultValue": "example", "type": "VAR_TYPE_STRING" } ], "version": 1, "disableDefaultTools": true } }, "status": "200", "schemaName": "CreateAgentProfileResponse" }, { "id": "agent-profiles-getAgentProfile-request", "operationId": "getAgentProfile", "operationKey": "agent-profiles:getAgentProfile", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Use the profileId of an existing profile in your project.", "payload": { "profileId": "support-assistant" }, "schemaName": "GetAgentProfileRequest" }, { "id": "agent-profiles-getAgentProfile-response", "operationId": "getAgentProfile", "operationKey": "agent-profiles:getAgentProfile", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "profile": { "profileId": "example_123", "name": "example", "description": "example", "whenToUse": "example", "keywords": [ "example_123" ], "enabled": true, "generationConfig": { "model": "example", "models": [ "example" ], "systemPrompt": "Example text", "transforms": [ "example" ], "temperature": 1, "topP": 1, "maxOutputTokens": 1, "frequencyPenalty": 1, "presencePenalty": 1, "stopSequences": [ "example" ], "seed": "1", "allowParallelToolCalls": true, "topK": 1, "repetitionPenalty": 1, "topLogprobs": 1, "minP": 1, "topA": 1, "user": "example", "modalities": [ "MODALITY_TEXT" ], "languagePreference": "en-US", "requestTimeoutSeconds": 1, "clearTools": true }, "mcpServers": [ { "serverId": "example_123", "enabled": true, "priority": 1, "allowlistToolPatterns": [ "example" ], "blocklistToolPatterns": [ "example" ] } ], "variableSpecs": [ { "name": "example", "description": "example", "required": true, "defaultValue": "example", "type": "VAR_TYPE_STRING" } ], "version": 1, "disableDefaultTools": true } }, "status": "200", "schemaName": "GetAgentProfileResponse" }, { "id": "agent-profiles-listAgentProfiles-request", "operationId": "listAgentProfiles", "operationKey": "agent-profiles:listAgentProfiles", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Read a bounded first page from the project library.", "payload": { "page": 1, "pageSize": 20 }, "schemaName": "ListAgentProfilesRequest" }, { "id": "agent-profiles-listAgentProfiles-response", "operationId": "listAgentProfiles", "operationKey": "agent-profiles:listAgentProfiles", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "profiles": [ { "profileId": "example_123", "name": "example", "description": "example", "whenToUse": "example", "keywords": [ "example_123" ], "enabled": true, "generationConfig": { "model": "example", "models": [ "example" ], "systemPrompt": "Example text", "transforms": [ "example" ], "temperature": 1, "topP": 1, "maxOutputTokens": 1, "frequencyPenalty": 1, "presencePenalty": 1, "stopSequences": [ "example" ], "seed": "1", "allowParallelToolCalls": true, "topK": 1, "repetitionPenalty": 1, "topLogprobs": 1, "minP": 1, "topA": 1, "user": "example", "modalities": [ "MODALITY_TEXT" ], "languagePreference": "en-US", "requestTimeoutSeconds": 1, "clearTools": true }, "mcpServers": [ { "serverId": "example_123", "enabled": true, "priority": 1, "allowlistToolPatterns": [ "example" ], "blocklistToolPatterns": [ "example" ] } ], "variableSpecs": [ { "name": "example", "description": "example", "required": true, "defaultValue": "example", "type": "VAR_TYPE_STRING" } ], "version": 1, "disableDefaultTools": true } ], "totalCount": 1, "hasMore": true }, "status": "200", "schemaName": "ListAgentProfilesResponse" }, { "id": "agent-profiles-updateAgentProfile-request", "operationId": "updateAgentProfile", "operationKey": "agent-profiles:updateAgentProfile", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Rename an existing profile without replacing its generation configuration.", "payload": { "profileId": "support-assistant", "profile": { "name": "Customer support assistant" }, "updateMask": "name" }, "schemaName": "UpdateAgentProfileRequest" }, { "id": "agent-profiles-updateAgentProfile-response", "operationId": "updateAgentProfile", "operationKey": "agent-profiles:updateAgentProfile", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "profile": { "profileId": "example_123", "name": "example", "description": "example", "whenToUse": "example", "keywords": [ "example_123" ], "enabled": true, "generationConfig": { "model": "example", "models": [ "example" ], "systemPrompt": "Example text", "transforms": [ "example" ], "temperature": 1, "topP": 1, "maxOutputTokens": 1, "frequencyPenalty": 1, "presencePenalty": 1, "stopSequences": [ "example" ], "seed": "1", "allowParallelToolCalls": true, "topK": 1, "repetitionPenalty": 1, "topLogprobs": 1, "minP": 1, "topA": 1, "user": "example", "modalities": [ "MODALITY_TEXT" ], "languagePreference": "en-US", "requestTimeoutSeconds": 1, "clearTools": true }, "mcpServers": [ { "serverId": "example_123", "enabled": true, "priority": 1, "allowlistToolPatterns": [ "example" ], "blocklistToolPatterns": [ "example" ] } ], "variableSpecs": [ { "name": "example", "description": "example", "required": true, "defaultValue": "example", "type": "VAR_TYPE_STRING" } ], "version": 1, "disableDefaultTools": true } }, "status": "200", "schemaName": "UpdateAgentProfileResponse" }, { "id": "agent-profiles-deleteAgentProfile-request", "operationId": "deleteAgentProfile", "operationKey": "agent-profiles:deleteAgentProfile", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Use the profileId of an existing profile in your project.", "payload": { "profileId": "support-assistant" }, "schemaName": "DeleteAgentProfileRequest" }, { "id": "agent-profiles-deleteAgentProfile-response", "operationId": "deleteAgentProfile", "operationKey": "agent-profiles:deleteAgentProfile", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": {}, "status": "200", "schemaName": "DeleteAgentProfileResponse" }, { "id": "agent-profiles-getAgentProfileLibrary-request", "operationId": "getAgentProfileLibrary", "operationKey": "agent-profiles:getAgentProfileLibrary", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Read the enabled profile library in the authenticated project; no additional body fields are needed.", "payload": {}, "schemaName": "GetAgentProfileLibraryRequest" }, { "id": "agent-profiles-getAgentProfileLibrary-response", "operationId": "getAgentProfileLibrary", "operationKey": "agent-profiles:getAgentProfileLibrary", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "library": { "profiles": [ { "profileId": "example_123", "name": "example", "description": "example", "whenToUse": "example", "keywords": [ "example_123" ], "enabled": true } ], "defaultProfileId": "example_123" } }, "status": "200", "schemaName": "GetAgentProfileLibraryResponse" }, { "id": "agent-profiles-listAgentProfileVersions-request", "operationId": "listAgentProfileVersions", "operationKey": "agent-profiles:listAgentProfileVersions", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Use the profileId of an existing profile in your project.", "payload": { "profileId": "support-assistant" }, "schemaName": "ListAgentProfileVersionsRequest" }, { "id": "agent-profiles-listAgentProfileVersions-response", "operationId": "listAgentProfileVersions", "operationKey": "agent-profiles:listAgentProfileVersions", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "versions": [ { "version": 1, "createdAt": "2026-09-16T12:00:00Z" } ] }, "status": "200", "schemaName": "ListAgentProfileVersionsResponse" }, { "id": "agent-profiles-getPromptFragmentSet-request", "operationId": "getPromptFragmentSet", "operationKey": "agent-profiles:getPromptFragmentSet", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "setVersion": 1 }, "schemaName": "GetPromptFragmentSetRequest" }, { "id": "agent-profiles-getPromptFragmentSet-response", "operationId": "getPromptFragmentSet", "operationKey": "agent-profiles:getPromptFragmentSet", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "setVersion": 1, "fragments": [ { "fragmentId": "example_123", "name": "example", "content": "Example text" } ] }, "status": "200", "schemaName": "GetPromptFragmentSetResponse" }, { "id": "agent-profiles-createPromptFragment-request", "operationId": "createPromptFragment", "operationKey": "agent-profiles:createPromptFragment", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Create a reusable prompt fragment with a new fragmentId.", "payload": { "fragment": { "fragmentId": "answer-style", "name": "Answer style", "content": "Use short paragraphs and explain any assumptions." } }, "schemaName": "CreatePromptFragmentRequest" }, { "id": "agent-profiles-createPromptFragment-response", "operationId": "createPromptFragment", "operationKey": "agent-profiles:createPromptFragment", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "fragment": { "fragmentId": "example_123", "name": "example", "content": "Example text" } }, "status": "200", "schemaName": "CreatePromptFragmentResponse" }, { "id": "agent-profiles-getPromptFragment-request", "operationId": "getPromptFragment", "operationKey": "agent-profiles:getPromptFragment", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Use the fragmentId of an existing prompt fragment in your project.", "payload": { "fragmentId": "answer-style" }, "schemaName": "GetPromptFragmentRequest" }, { "id": "agent-profiles-getPromptFragment-response", "operationId": "getPromptFragment", "operationKey": "agent-profiles:getPromptFragment", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "fragment": { "fragmentId": "example_123", "name": "example", "content": "Example text" } }, "status": "200", "schemaName": "GetPromptFragmentResponse" }, { "id": "agent-profiles-listPromptFragments-request", "operationId": "listPromptFragments", "operationKey": "agent-profiles:listPromptFragments", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Read a bounded first page from the project library.", "payload": { "page": 1, "pageSize": 20 }, "schemaName": "ListPromptFragmentsRequest" }, { "id": "agent-profiles-listPromptFragments-response", "operationId": "listPromptFragments", "operationKey": "agent-profiles:listPromptFragments", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "fragments": [ { "fragmentId": "example_123", "name": "example", "content": "Example text" } ], "totalCount": 1, "hasMore": true, "setVersion": 1 }, "status": "200", "schemaName": "ListPromptFragmentsResponse" }, { "id": "agent-profiles-updatePromptFragment-request", "operationId": "updatePromptFragment", "operationKey": "agent-profiles:updatePromptFragment", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Replace the content of an existing fragment, preserving its other fields.", "payload": { "fragmentId": "answer-style", "fragment": { "content": "Use short paragraphs and include the next action." }, "updateMask": "content" }, "schemaName": "UpdatePromptFragmentRequest" }, { "id": "agent-profiles-updatePromptFragment-response", "operationId": "updatePromptFragment", "operationKey": "agent-profiles:updatePromptFragment", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "fragment": { "fragmentId": "example_123", "name": "example", "content": "Example text" } }, "status": "200", "schemaName": "UpdatePromptFragmentResponse" }, { "id": "agent-profiles-deletePromptFragment-request", "operationId": "deletePromptFragment", "operationKey": "agent-profiles:deletePromptFragment", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Use the fragmentId of an existing prompt fragment in your project.", "payload": { "fragmentId": "answer-style" }, "schemaName": "DeletePromptFragmentRequest" }, { "id": "agent-profiles-deletePromptFragment-response", "operationId": "deletePromptFragment", "operationKey": "agent-profiles:deletePromptFragment", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": {}, "status": "200", "schemaName": "DeletePromptFragmentResponse" }, { "id": "agent-profiles-importAgentProfiles-request", "operationId": "importAgentProfiles", "operationKey": "agent-profiles:importAgentProfiles", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Import one source template as a new profile; use overwrite only when replacement is intended.", "payload": { "templates": [ { "profileId": "support-assistant", "name": "Support assistant", "whenToUse": "Help users answer product questions.", "sourceDsl": "Answer clearly using the supplied product information." } ] }, "schemaName": "ImportAgentProfilesRequest" }, { "id": "agent-profiles-importAgentProfiles-response", "operationId": "importAgentProfiles", "operationKey": "agent-profiles:importAgentProfiles", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "profiles": [ { "profileId": "example_123", "name": "example", "description": "example", "whenToUse": "example", "keywords": [ "example_123" ], "enabled": true, "generationConfig": { "model": "example", "models": [ "example" ], "systemPrompt": "Example text", "transforms": [ "example" ], "temperature": 1, "topP": 1, "maxOutputTokens": 1, "frequencyPenalty": 1, "presencePenalty": 1, "stopSequences": [ "example" ], "seed": "1", "allowParallelToolCalls": true, "topK": 1, "repetitionPenalty": 1, "topLogprobs": 1, "minP": 1, "topA": 1, "user": "example", "modalities": [ "MODALITY_TEXT" ], "languagePreference": "en-US", "requestTimeoutSeconds": 1, "clearTools": true }, "mcpServers": [ { "serverId": "example_123", "enabled": true, "priority": 1, "allowlistToolPatterns": [ "example" ], "blocklistToolPatterns": [ "example" ] } ], "variableSpecs": [ { "name": "example", "description": "example", "required": true, "defaultValue": "example", "type": "VAR_TYPE_STRING" } ], "version": 1, "disableDefaultTools": true } ], "fragments": [ { "fragmentId": "example_123", "name": "example", "content": "Example text" } ] }, "status": "200", "schemaName": "ImportAgentProfilesResponse" }, { "id": "connected-apps-pipedreamListApps-request", "operationId": "pipedreamListApps", "operationKey": "connected-apps:pipedreamListApps", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "List available connected-app integrations with default paging.", "payload": {}, "schemaName": "PipedreamListAppsRequest" }, { "id": "connected-apps-pipedreamListApps-response", "operationId": "pipedreamListApps", "operationKey": "connected-apps:pipedreamListApps", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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" } }, "status": "200", "schemaName": "PipedreamListAppsResponse" }, { "id": "connected-apps-pipedreamRetrieveApp-request", "operationId": "pipedreamRetrieveApp", "operationKey": "connected-apps:pipedreamRetrieveApp", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Look up the GitHub app before starting a connection.", "payload": { "nameSlug": "github" }, "schemaName": "PipedreamRetrieveAppRequest" }, { "id": "connected-apps-pipedreamRetrieveApp-response", "operationId": "pipedreamRetrieveApp", "operationKey": "connected-apps:pipedreamRetrieveApp", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "app": { "id": "example_123", "nameSlug": "example", "name": "example", "authType": "AUTH_TYPE_KEYS", "description": "example", "imgSrc": "example", "customFieldsJson": "{}", "categories": [ "example" ], "featuredWeight": 1 } }, "status": "200", "schemaName": "PipedreamRetrieveAppResponse" }, { "id": "connected-apps-pipedreamListAppCategories-request", "operationId": "pipedreamListAppCategories", "operationKey": "connected-apps:pipedreamListAppCategories", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "List connected-app categories; this request has no selection fields.", "payload": {}, "schemaName": "PipedreamListAppCategoriesRequest" }, { "id": "connected-apps-pipedreamListAppCategories-response", "operationId": "pipedreamListAppCategories", "operationKey": "connected-apps:pipedreamListAppCategories", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "data": [ { "id": "example_123", "nameSlug": "example", "name": "example" } ], "pageInfo": { "count": 1, "totalCount": 1, "startCursor": "example", "endCursor": "example" } }, "status": "200", "schemaName": "PipedreamListAppCategoriesResponse" }, { "id": "connected-apps-pipedreamCreateConnectToken-request", "operationId": "pipedreamCreateConnectToken", "operationKey": "connected-apps:pipedreamCreateConnectToken", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Create a connection token for the authenticated end user using the configured provider defaults.", "payload": {}, "schemaName": "PipedreamCreateConnectTokenRequest" }, { "id": "connected-apps-pipedreamCreateConnectToken-response", "operationId": "pipedreamCreateConnectToken", "operationKey": "connected-apps:pipedreamCreateConnectToken", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "token": "example", "connectLinkUrl": "https://example.com/resource", "expiresAt": "2026-09-16T12:00:00Z" }, "status": "200", "schemaName": "PipedreamCreateConnectTokenResponse" }, { "id": "connected-apps-pipedreamListAccountsForCurrentUser-request", "operationId": "pipedreamListAccountsForCurrentUser", "operationKey": "connected-apps:pipedreamListAccountsForCurrentUser", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "List accounts belonging to the authenticated end user.", "payload": {}, "schemaName": "PipedreamListAccountsForCurrentUserRequest" }, { "id": "connected-apps-pipedreamListAccountsForCurrentUser-response", "operationId": "pipedreamListAccountsForCurrentUser", "operationKey": "connected-apps:pipedreamListAccountsForCurrentUser", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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" } }, "status": "200", "schemaName": "PipedreamListAccountsForCurrentUserResponse" }, { "id": "connected-apps-pipedreamDeleteAccountForCurrentUser-request", "operationId": "pipedreamDeleteAccountForCurrentUser", "operationKey": "connected-apps:pipedreamDeleteAccountForCurrentUser", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "accountId": "example_123" }, "schemaName": "PipedreamDeleteAccountForCurrentUserRequest" }, { "id": "connected-apps-pipedreamDeleteAccountForCurrentUser-response", "operationId": "pipedreamDeleteAccountForCurrentUser", "operationKey": "connected-apps:pipedreamDeleteAccountForCurrentUser", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "deleted": true }, "status": "200", "schemaName": "PipedreamDeleteAccountForCurrentUserResponse" }, { "id": "connected-apps-pipedreamDeleteExternalUserForCurrentUser-request", "operationId": "pipedreamDeleteExternalUserForCurrentUser", "operationKey": "connected-apps:pipedreamDeleteExternalUserForCurrentUser", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Delete the external connected-app user selected by authentication; no user identifier is accepted in this body.", "payload": {}, "schemaName": "PipedreamDeleteExternalUserForCurrentUserRequest" }, { "id": "connected-apps-pipedreamDeleteExternalUserForCurrentUser-response", "operationId": "pipedreamDeleteExternalUserForCurrentUser", "operationKey": "connected-apps:pipedreamDeleteExternalUserForCurrentUser", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "deleted": true, "accountsDeleted": 1 }, "status": "200", "schemaName": "PipedreamDeleteExternalUserForCurrentUserResponse" }, { "id": "connected-apps-pipedreamProxyForCurrentUser-request", "operationId": "pipedreamProxyForCurrentUser", "operationKey": "connected-apps:pipedreamProxyForCurrentUser", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Replace accountId with the authenticated user’s connected GitHub account; request that provider’s profile endpoint.", "payload": { "accountId": "apn_example", "method": "GET", "url": "https://api.github.com/user" }, "schemaName": "PipedreamProxyForCurrentUserRequest" }, { "id": "connected-apps-pipedreamProxyForCurrentUser-response", "operationId": "pipedreamProxyForCurrentUser", "operationKey": "connected-apps:pipedreamProxyForCurrentUser", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "status": 1, "headers": {}, "body": "ZXhhbXBsZQ==" }, "status": "200", "schemaName": "PipedreamProxyForCurrentUserResponse" }, { "id": "conversations-createThread-request", "operationId": "createThread", "operationKey": "conversations:createThread", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Create a titled conversation; identity comes from authenticated context.", "payload": { "title": "Travel planning", "tags": [ "travel" ] }, "schemaName": "CreateThreadRequest" }, { "id": "conversations-createThread-response", "operationId": "createThread", "operationKey": "conversations:createThread", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "thread": { "threadId": "example_123", "title": "example", "tags": [ "example" ], "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z", "externalId": "example_123" } }, "status": "200", "schemaName": "CreateThreadResponse" }, { "id": "conversations-listThreads-request", "operationId": "listThreads", "operationKey": "conversations:listThreads", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "List the authenticated user’s conversations with default paging.", "payload": {}, "schemaName": "ListThreadsRequest" }, { "id": "conversations-listThreads-response", "operationId": "listThreads", "operationKey": "conversations:listThreads", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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" }, "status": "200", "schemaName": "ListThreadsResponse" }, { "id": "conversations-sendMessage-request", "operationId": "sendMessage", "operationKey": "conversations:sendMessage", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "conversationKey": "example_123", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Hello" } ] } }, "schemaName": "SendMessageRequest" }, { "id": "conversations-sendMessage-response", "operationId": "sendMessage", "operationKey": "conversations:sendMessage", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "runId": "example_123", "interruptedPriorRun": true }, "status": "200", "schemaName": "SendMessageResponse" }, { "id": "conversations-appendMessage-request", "operationId": "appendMessage", "operationKey": "conversations:appendMessage", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "conversationKey": "example_123", "message": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Hello" } ] } }, "schemaName": "AppendMessageRequest" }, { "id": "conversations-appendMessage-response", "operationId": "appendMessage", "operationKey": "conversations:appendMessage", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": {}, "status": "200", "schemaName": "AppendMessageResponse" }, { "id": "conversations-sendMessageSync-request", "operationId": "sendMessageSync", "operationKey": "conversations:sendMessageSync", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "conversationKey": "example_123", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Hello" } ] } }, "schemaName": "SendMessageSyncRequest" }, { "id": "conversations-sendMessageSync-response", "operationId": "sendMessageSync", "operationKey": "conversations:sendMessageSync", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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 }, "status": "200", "schemaName": "SendMessageSyncResponse" }, { "id": "conversations-updateSettings-request", "operationId": "updateSettings", "operationKey": "conversations:updateSettings", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Replace settings on an existing conversation; include every setting you want to retain.", "payload": { "conversationKey": "example_123", "settings": { "maxLoops": 6, "maxParallelTools": 3 } }, "schemaName": "UpdateSettingsRequest" }, { "id": "conversations-updateSettings-response", "operationId": "updateSettings", "operationKey": "conversations:updateSettings", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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" } } }, "status": "200", "schemaName": "UpdateSettingsResponse" }, { "id": "conversations-updatePromptVariables-request", "operationId": "updatePromptVariables", "operationKey": "conversations:updatePromptVariables", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Merge a destination variable into an existing conversation’s prompt variables.", "payload": { "conversationKey": "example_123", "variables": { "destination": "Paris" } }, "schemaName": "UpdatePromptVariablesRequest" }, { "id": "conversations-updatePromptVariables-response", "operationId": "updatePromptVariables", "operationKey": "conversations:updatePromptVariables", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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" } } }, "status": "200", "schemaName": "UpdatePromptVariablesResponse" }, { "id": "conversations-updateDefaultGenerationConfig-request", "operationId": "updateDefaultGenerationConfig", "operationKey": "conversations:updateDefaultGenerationConfig", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Replace the default generation configuration on an existing conversation.", "payload": { "conversationKey": "example_123", "defaultGenerationConfig": { "languagePreference": "en-US", "maxOutputTokens": 512 } }, "schemaName": "ConversationUpdateDefaultGenerationConfigRequest" }, { "id": "conversations-updateDefaultGenerationConfig-response", "operationId": "updateDefaultGenerationConfig", "operationKey": "conversations:updateDefaultGenerationConfig", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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 } }, "status": "200", "schemaName": "ConversationUpdateDefaultGenerationConfigResponse" }, { "id": "conversations-updateContextManagementSettings-request", "operationId": "updateContextManagementSettings", "operationKey": "conversations:updateContextManagementSettings", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Update the window size for an existing conversation already using the windowing strategy.", "payload": { "conversationKey": "example_123", "contextManagementSettings": { "strategy": "CONTEXT_STRATEGY_WINDOWING", "windowingConfig": { "maxMessages": 50 } } }, "schemaName": "UpdateContextManagementSettingsRequest" }, { "id": "conversations-updateContextManagementSettings-response", "operationId": "updateContextManagementSettings", "operationKey": "conversations:updateContextManagementSettings", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "contextManagementSettings": { "strategy": "CONTEXT_STRATEGY_COMPACTION", "compactionConfig": { "mode": "COMPACTION_MODE_SYNC", "preserveRecent": 1 }, "windowingConfig": { "maxMessages": 1 }, "selectiveExclusionConfig": { "excludeToolResults": true, "excludeImages": true, "excludeFiles": true, "excludeReasoning": true } } }, "status": "200", "schemaName": "UpdateContextManagementSettingsResponse" }, { "id": "conversations-compactConversation-request", "operationId": "compactConversation", "operationKey": "conversations:compactConversation", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "conversationKey": "example_123" }, "schemaName": "CompactConversationRequest" }, { "id": "conversations-compactConversation-response", "operationId": "compactConversation", "operationKey": "conversations:compactConversation", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "compactionId": "example_123", "tokensBefore": 1, "tokensAfter": 1, "tokensSaved": 1, "durationMs": "1", "status": "COMPACTION_STATUS_PENDING" }, "status": "200", "schemaName": "CompactConversationResponse" }, { "id": "conversations-getConversationState-request", "operationId": "getConversationState", "operationKey": "conversations:getConversationState", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "conversationKey": "example_123" }, "schemaName": "GetConversationStateRequest" }, { "id": "conversations-getConversationState-response", "operationId": "getConversationState", "operationKey": "conversations:getConversationState", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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" }, "status": "200", "schemaName": "GetConversationStateResponse" }, { "id": "conversations-rateMessage-request", "operationId": "rateMessage", "operationKey": "conversations:rateMessage", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Give an existing assistant message a positive thumb rating; replace its sequence number.", "payload": { "conversationKey": "example_123", "messageSequence": "1", "kind": "FEEDBACK_KIND_THUMB", "thumbUp": true }, "schemaName": "RateMessageRequest" }, { "id": "conversations-rateMessage-response", "operationId": "rateMessage", "operationKey": "conversations:rateMessage", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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 }, "status": "200", "schemaName": "RateMessageResponse" }, { "id": "conversations-deleteMessageRating-request", "operationId": "deleteMessageRating", "operationKey": "conversations:deleteMessageRating", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "conversationKey": "example_123", "messageSequence": "1" }, "schemaName": "DeleteMessageRatingRequest" }, { "id": "conversations-deleteMessageRating-response", "operationId": "deleteMessageRating", "operationKey": "conversations:deleteMessageRating", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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 }, "status": "200", "schemaName": "DeleteMessageRatingResponse" }, { "id": "conversations-createDailySession-request", "operationId": "createDailySession", "operationKey": "conversations:createDailySession", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "conversationKey": "example_123" }, "schemaName": "CreateDailySessionRequest" }, { "id": "conversations-createDailySession-response", "operationId": "createDailySession", "operationKey": "conversations:createDailySession", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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" } }, "status": "200", "schemaName": "CreateDailySessionResponse" }, { "id": "conversations-mintSttToken-request", "operationId": "mintSttToken", "operationKey": "conversations:mintSttToken", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Request a speech-to-text token using the configured provider; no body fields are required.", "payload": {}, "schemaName": "MintSttTokenRequest" }, { "id": "conversations-mintSttToken-response", "operationId": "mintSttToken", "operationKey": "conversations:mintSttToken", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "token": "example", "expiresInSeconds": 1 }, "status": "200", "schemaName": "MintSttTokenResponse" }, { "id": "conversations-listPendingApprovals-request", "operationId": "listPendingApprovals", "operationKey": "conversations:listPendingApprovals", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "conversationKey": "example_123" }, "schemaName": "ListPendingApprovalsRequest" }, { "id": "conversations-listPendingApprovals-response", "operationId": "listPendingApprovals", "operationKey": "conversations:listPendingApprovals", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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" } ] }, "status": "200", "schemaName": "ListPendingApprovalsResponse" }, { "id": "conversations-submitToolApprovals-request", "operationId": "submitToolApprovals", "operationKey": "conversations:submitToolApprovals", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Approve a pending tool call; use its ID from listPendingApprovals.", "payload": { "conversationKey": "example_123", "approvals": [ { "toolCallId": "tool_call_123", "approved": true } ] }, "schemaName": "SubmitToolApprovalsRequest" }, { "id": "conversations-submitToolApprovals-response", "operationId": "submitToolApprovals", "operationKey": "conversations:submitToolApprovals", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": {}, "status": "200", "schemaName": "SubmitToolApprovalsResponse" }, { "id": "conversations-submitClientToolResults-request", "operationId": "submitClientToolResults", "operationKey": "conversations:submitClientToolResults", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Return a result for a pending client tool call; use its actual ID, name and expected result shape.", "payload": { "conversationKey": "example_123", "results": [ { "toolCallId": "tool_call_123", "toolName": "lookup_booking", "resultJson": { "bookingStatus": "confirmed" } } ] }, "schemaName": "SubmitClientToolResultsRequest" }, { "id": "conversations-submitClientToolResults-response", "operationId": "submitClientToolResults", "operationKey": "conversations:submitClientToolResults", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "runId": "example_123" }, "status": "200", "schemaName": "SubmitClientToolResultsResponse" }, { "id": "conversations-submitClientToolResultsSync-request", "operationId": "submitClientToolResultsSync", "operationKey": "conversations:submitClientToolResultsSync", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Return a result for a pending client tool call; use its actual ID, name and expected result shape.", "payload": { "conversationKey": "example_123", "results": [ { "toolCallId": "tool_call_123", "toolName": "lookup_booking", "resultJson": { "bookingStatus": "confirmed" } } ] }, "schemaName": "SubmitClientToolResultsSyncRequest" }, { "id": "conversations-submitClientToolResultsSync-response", "operationId": "submitClientToolResultsSync", "operationKey": "conversations:submitClientToolResultsSync", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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": {} } }, "status": "200", "schemaName": "SubmitClientToolResultsSyncResponse" }, { "id": "conversations-listPendingClientTools-request", "operationId": "listPendingClientTools", "operationKey": "conversations:listPendingClientTools", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "conversationKey": "example_123" }, "schemaName": "ListPendingClientToolsRequest" }, { "id": "conversations-listPendingClientTools-response", "operationId": "listPendingClientTools", "operationKey": "conversations:listPendingClientTools", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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" } ] }, "status": "200", "schemaName": "ListPendingClientToolsResponse" }, { "id": "conversations-getToolCall-request", "operationId": "getToolCall", "operationKey": "conversations:getToolCall", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Inspect a tool call using an ID previously returned by the conversation.", "payload": { "conversationKey": "example_123", "toolCallId": "tool_call_123" }, "schemaName": "GetToolCallRequest" }, { "id": "conversations-getToolCall-response", "operationId": "getToolCall", "operationKey": "conversations:getToolCall", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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" } }, "status": "200", "schemaName": "GetToolCallResponse" }, { "id": "conversations-mcpListAvailableServers-request", "operationId": "mcpListAvailableServers", "operationKey": "conversations:mcpListAvailableServers", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Discover servers available in the authenticated scope; no body filters are supplied.", "payload": {}, "schemaName": "MCPListAvailableServersRequest" }, { "id": "conversations-mcpListAvailableServers-response", "operationId": "mcpListAvailableServers", "operationKey": "conversations:mcpListAvailableServers", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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 } ] }, "status": "200", "schemaName": "MCPListAvailableServersResponse" }, { "id": "conversations-mcpGetServerInfo-request", "operationId": "mcpGetServerInfo", "operationKey": "conversations:mcpGetServerInfo", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Inspect a registered custom MCP server; replace the example server ID.", "payload": { "serverId": "custom:product-tools" }, "schemaName": "MCPGetServerInfoRequest" }, { "id": "conversations-mcpGetServerInfo-response", "operationId": "mcpGetServerInfo", "operationKey": "conversations:mcpGetServerInfo", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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" } }, "status": "200", "schemaName": "MCPGetServerInfoResponse" }, { "id": "conversations-mcpListTools-request", "operationId": "mcpListTools", "operationKey": "conversations:mcpListTools", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "List tools exposed by a registered custom MCP server; replace the server ID.", "payload": { "servers": [ { "serverId": "custom:product-tools", "enabled": true } ] }, "schemaName": "MCPListToolsRequest" }, { "id": "conversations-mcpListTools-response", "operationId": "mcpListTools", "operationKey": "conversations:mcpListTools", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "tools": [ { "name": "example", "description": "example", "parametersJsonSchema": { "example": "value" }, "metadata": {}, "serverId": "example_123", "tags": [ "example" ], "documentationUrl": "https://example.com/resource", "outputJsonSchema": { "example": "value" } } ], "totalCount": 1 }, "status": "200", "schemaName": "MCPListToolsResponse" }, { "id": "conversations-mcpCallTool-request", "operationId": "mcpCallTool", "operationKey": "conversations:mcpCallTool", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Call a tool discovered through mcpListTools; replace the server, tool name and arguments with that tool’s schema.", "payload": { "toolCall": { "id": "tool_call_123", "serverId": "custom:product-tools", "name": "lookup_booking", "argumentsJson": { "booking_id": "BK-123" } } }, "schemaName": "MCPCallToolRequest" }, { "id": "conversations-mcpCallTool-response", "operationId": "mcpCallTool", "operationKey": "conversations:mcpCallTool", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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 }, "status": "200", "schemaName": "MCPCallToolResponse" }, { "id": "conversations-mcpListResources-request", "operationId": "mcpListResources", "operationKey": "conversations:mcpListResources", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Illustrative request shape; the current handler returns an empty result without fetching resources or prompts.", "payload": { "serverId": "custom:product-tools" }, "schemaName": "MCPListResourcesRequest" }, { "id": "conversations-mcpListResources-response", "operationId": "mcpListResources", "operationKey": "conversations:mcpListResources", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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 }, "status": "200", "schemaName": "MCPListResourcesResponse" }, { "id": "conversations-mcpReadResource-request", "operationId": "mcpReadResource", "operationKey": "conversations:mcpReadResource", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Illustrative request shape; the current handler returns an empty result without fetching resources or prompts.", "payload": { "serverId": "custom:product-tools", "uri": "resource://bookings/BK-123" }, "schemaName": "MCPReadResourceRequest" }, { "id": "conversations-mcpReadResource-response", "operationId": "mcpReadResource", "operationKey": "conversations:mcpReadResource", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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" } }, "status": "200", "schemaName": "MCPReadResourceResponse" }, { "id": "conversations-mcpListPrompts-request", "operationId": "mcpListPrompts", "operationKey": "conversations:mcpListPrompts", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Illustrative request shape; the current handler returns an empty result without fetching resources or prompts.", "payload": { "serverId": "custom:product-tools" }, "schemaName": "MCPListPromptsRequest" }, { "id": "conversations-mcpListPrompts-response", "operationId": "mcpListPrompts", "operationKey": "conversations:mcpListPrompts", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "prompts": [ { "name": "example", "title": "example", "description": "example", "parameters": [ { "name": "example", "description": "example", "type": "example", "required": true } ], "template": "example" } ], "totalCount": 1 }, "status": "200", "schemaName": "MCPListPromptsResponse" }, { "id": "conversations-mcpGetPrompt-request", "operationId": "mcpGetPrompt", "operationKey": "conversations:mcpGetPrompt", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Illustrative request shape; the current handler returns an empty result without fetching resources or prompts.", "payload": { "serverId": "custom:product-tools", "name": "travel-summary" }, "schemaName": "MCPGetPromptRequest" }, { "id": "conversations-mcpGetPrompt-response", "operationId": "mcpGetPrompt", "operationKey": "conversations:mcpGetPrompt", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "prompt": { "name": "example", "title": "example", "description": "example", "parameters": [ { "name": "example", "description": "example", "type": "example", "required": true } ], "template": "example" } }, "status": "200", "schemaName": "MCPGetPromptResponse" }, { "id": "conversations-listMemories-request", "operationId": "listMemories", "operationKey": "conversations:listMemories", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "limit": 1 }, "schemaName": "ListMemoriesRequest" }, { "id": "conversations-listMemories-response", "operationId": "listMemories", "operationKey": "conversations:listMemories", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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" } ] }, "status": "200", "schemaName": "ListMemoriesResponse" }, { "id": "conversations-getMemory-request", "operationId": "getMemory", "operationKey": "conversations:getMemory", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "memoryId": "example_123" }, "schemaName": "GetMemoryRequest" }, { "id": "conversations-getMemory-response", "operationId": "getMemory", "operationKey": "conversations:getMemory", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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" } }, "status": "200", "schemaName": "GetMemoryResponse" }, { "id": "conversations-updateMemory-request", "operationId": "updateMemory", "operationKey": "conversations:updateMemory", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "memoryId": "example_123", "text": "Example text" }, "schemaName": "UpdateMemoryRequest" }, { "id": "conversations-updateMemory-response", "operationId": "updateMemory", "operationKey": "conversations:updateMemory", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": {}, "status": "200", "schemaName": "UpdateMemoryResponse" }, { "id": "conversations-deleteMemory-request", "operationId": "deleteMemory", "operationKey": "conversations:deleteMemory", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "memoryId": "example_123" }, "schemaName": "DeleteMemoryRequest" }, { "id": "conversations-deleteMemory-response", "operationId": "deleteMemory", "operationKey": "conversations:deleteMemory", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "success": true }, "status": "200", "schemaName": "DeleteMemoryResponse" }, { "id": "end-users-getEndUser-request", "operationId": "getEndUser", "operationKey": "end-users:getEndUser", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Read the end user selected by authentication; no user identifier is accepted in this body.", "payload": {}, "schemaName": "GetEndUserRequest" }, { "id": "end-users-getEndUser-response", "operationId": "getEndUser", "operationKey": "end-users:getEndUser", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "endUser": { "subject": "example", "tenantId": "example_123", "issuer": "example", "projectId": "example_123", "email": "user@example.com", "emailVerified": true, "name": "example", "givenName": "example", "familyName": "example", "preferredUsername": "example", "picture": "example", "phoneNumber": "example", "phoneNumberVerified": true, "signInProvider": "example_123", "authMethod": "example", "locale": "en-US", "zoneinfo": "example", "customClaims": {}, "location": { "latitude": 1, "longitude": 1, "city": "example", "timezone": "example" }, "localeOverride": "en-US", "defaultGenerationConfig": { "model": "example", "models": [ "example" ], "systemPrompt": "Example text", "transforms": [ "example" ], "temperature": 1, "topP": 1, "maxOutputTokens": 1, "frequencyPenalty": 1, "presencePenalty": 1, "stopSequences": [ "example" ], "seed": "1", "allowParallelToolCalls": true, "topK": 1, "repetitionPenalty": 1, "topLogprobs": 1, "minP": 1, "topA": 1, "user": "example", "modalities": [ "MODALITY_TEXT" ], "languagePreference": "en-US", "requestTimeoutSeconds": 1, "clearTools": true }, "metadata": {}, "firstSeenAt": "2026-09-16T12:00:00Z", "lastSeenAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z", "createdAt": "2026-09-16T12:00:00Z" } }, "status": "200", "schemaName": "GetEndUserResponse" }, { "id": "end-users-updateLocation-request", "operationId": "updateLocation", "operationKey": "end-users:updateLocation", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Set the authenticated end user’s location to the supplied coordinates.", "payload": { "latitude": 37.7749, "longitude": -122.4194 }, "schemaName": "UpdateLocationRequest" }, { "id": "end-users-updateLocation-response", "operationId": "updateLocation", "operationKey": "end-users:updateLocation", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "location": { "latitude": 1, "longitude": 1, "city": "example", "timezone": "example", "updatedAt": "2026-09-16T12:00:00Z" } }, "status": "200", "schemaName": "UpdateLocationResponse" }, { "id": "end-users-updateLocale-request", "operationId": "updateLocale", "operationKey": "end-users:updateLocale", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Set the authenticated end user’s locale override.", "payload": { "locale": "en-US" }, "schemaName": "UpdateLocaleRequest" }, { "id": "end-users-updateLocale-response", "operationId": "updateLocale", "operationKey": "end-users:updateLocale", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": {}, "status": "200", "schemaName": "UpdateLocaleResponse" }, { "id": "end-users-updateDefaultGenerationConfig-request", "operationId": "updateDefaultGenerationConfig", "operationKey": "end-users:updateDefaultGenerationConfig", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "config": { "languagePreference": "en-US" } }, "schemaName": "EndUserUpdateDefaultGenerationConfigRequest" }, { "id": "end-users-updateDefaultGenerationConfig-response", "operationId": "updateDefaultGenerationConfig", "operationKey": "end-users:updateDefaultGenerationConfig", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": {}, "status": "200", "schemaName": "EndUserUpdateDefaultGenerationConfigResponse" }, { "id": "end-users-updateMetadata-request", "operationId": "updateMetadata", "operationKey": "end-users:updateMetadata", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Merge a metadata key for the authenticated end user.", "payload": { "metadata": { "preferred_destination": "Paris" } }, "schemaName": "UpdateMetadataRequest" }, { "id": "end-users-updateMetadata-response", "operationId": "updateMetadata", "operationKey": "end-users:updateMetadata", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": {}, "status": "200", "schemaName": "UpdateMetadataResponse" }, { "id": "evals-addDatasetItem-request", "operationId": "addDatasetItem", "operationKey": "evals:addDatasetItem", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Harvest an existing trace into a named dataset; replace sourceTraceId with the trace being curated.", "payload": { "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.\"" }, "schemaName": "AddDatasetItemRequest" }, { "id": "evals-addDatasetItem-response", "operationId": "addDatasetItem", "operationKey": "evals:addDatasetItem", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "itemId": "example_123" }, "status": "200", "schemaName": "AddDatasetItemResponse" }, { "id": "evals-completeAnnotationQueueItem-request", "operationId": "completeAnnotationQueueItem", "operationKey": "evals:completeAnnotationQueueItem", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "queueId": "example_123", "itemId": "example_123" }, "schemaName": "CompleteAnnotationQueueItemRequest" }, { "id": "evals-completeAnnotationQueueItem-response", "operationId": "completeAnnotationQueueItem", "operationKey": "evals:completeAnnotationQueueItem", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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" } }, "status": "200", "schemaName": "CompleteAnnotationQueueItemResponse" }, { "id": "evals-createAnnotationQueue-request", "operationId": "createAnnotationQueue", "operationKey": "evals:createAnnotationQueue", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "name": "example", "scoreConfigIds": [ "example_123" ] }, "schemaName": "CreateAnnotationQueueRequest" }, { "id": "evals-createAnnotationQueue-response", "operationId": "createAnnotationQueue", "operationKey": "evals:createAnnotationQueue", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "queueId": "example_123" }, "status": "200", "schemaName": "CreateAnnotationQueueResponse" }, { "id": "evals-createComment-request", "operationId": "createComment", "operationKey": "evals:createComment", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "objectType": "COMMENT_OBJECT_TYPE_TRACE", "objectId": "example_123", "content": "Example text" }, "schemaName": "CreateCommentRequest" }, { "id": "evals-createComment-response", "operationId": "createComment", "operationKey": "evals:createComment", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "commentId": "example_123" }, "status": "200", "schemaName": "CreateCommentResponse" }, { "id": "evals-createDataset-request", "operationId": "createDataset", "operationKey": "evals:createDataset", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Create a named dataset for subsequent curation.", "payload": { "name": "support-answers", "description": "Curated product support questions and expected answers." }, "schemaName": "CreateDatasetRequest" }, { "id": "evals-createDataset-response", "operationId": "createDataset", "operationKey": "evals:createDataset", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "datasetId": "example_123" }, "status": "200", "schemaName": "CreateDatasetResponse" }, { "id": "evals-createScoreConfig-request", "operationId": "createScoreConfig", "operationKey": "evals:createScoreConfig", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Create a numeric scoring rubric ranging from zero to one.", "payload": { "name": "answer-quality", "dataType": "SCORE_DATA_TYPE_NUMERIC", "minValue": 0, "maxValue": 1 }, "schemaName": "CreateScoreConfigRequest" }, { "id": "evals-createScoreConfig-response", "operationId": "createScoreConfig", "operationKey": "evals:createScoreConfig", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "configId": "example_123" }, "status": "200", "schemaName": "CreateScoreConfigResponse" }, { "id": "evals-deleteComment-request", "operationId": "deleteComment", "operationKey": "evals:deleteComment", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "commentId": "example_123" }, "schemaName": "DeleteCommentRequest" }, { "id": "evals-deleteComment-response", "operationId": "deleteComment", "operationKey": "evals:deleteComment", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "deleted": true }, "status": "200", "schemaName": "DeleteCommentResponse" }, { "id": "evals-deleteScore-request", "operationId": "deleteScore", "operationKey": "evals:deleteScore", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "scoreId": "example_123" }, "schemaName": "DeleteScoreRequest" }, { "id": "evals-deleteScore-response", "operationId": "deleteScore", "operationKey": "evals:deleteScore", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "deleted": true }, "status": "200", "schemaName": "DeleteScoreResponse" }, { "id": "evals-enqueueForAnnotation-request", "operationId": "enqueueForAnnotation", "operationKey": "evals:enqueueForAnnotation", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "queueId": "example_123", "targetType": "EVAL_TARGET_TYPE_TRACE", "targetId": "example_123" }, "schemaName": "EnqueueForAnnotationRequest" }, { "id": "evals-enqueueForAnnotation-response", "operationId": "enqueueForAnnotation", "operationKey": "evals:enqueueForAnnotation", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "queueItemId": "example_123" }, "status": "200", "schemaName": "EnqueueForAnnotationResponse" }, { "id": "evals-getDatasetRun-request", "operationId": "getDatasetRun", "operationKey": "evals:getDatasetRun", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "datasetName": "example", "runName": "example" }, "schemaName": "GetDatasetRunRequest" }, { "id": "evals-getDatasetRun-response", "operationId": "getDatasetRun", "operationKey": "evals:getDatasetRun", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "run": { "runId": "example_123", "datasetId": "example_123", "name": "example", "description": "example", "metadataJson": "{}", "itemCount": 1, "createdAt": "2026-09-16T12:00:00Z" } }, "status": "200", "schemaName": "GetDatasetRunResponse" }, { "id": "evals-getOverview-request", "operationId": "getOverview", "operationKey": "evals:getOverview", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": {}, "schemaName": "GetOverviewRequest" }, { "id": "evals-getOverview-response", "operationId": "getOverview", "operationKey": "evals:getOverview", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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" } ] } }, "status": "200", "schemaName": "GetOverviewResponse" }, { "id": "evals-getSession-request", "operationId": "getSession", "operationKey": "evals:getSession", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "sessionId": "example_123" }, "schemaName": "GetSessionRequest" }, { "id": "evals-getSession-response", "operationId": "getSession", "operationKey": "evals:getSession", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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 }, "status": "200", "schemaName": "GetSessionResponse" }, { "id": "evals-getTrace-request", "operationId": "getTrace", "operationKey": "evals:getTrace", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "traceId": "trace_123" }, "schemaName": "GetTraceRequest" }, { "id": "evals-getTrace-response", "operationId": "getTrace", "operationKey": "evals:getTrace", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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 }, "status": "200", "schemaName": "GetTraceResponse" }, { "id": "evals-listAnnotationQueueItems-request", "operationId": "listAnnotationQueueItems", "operationKey": "evals:listAnnotationQueueItems", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "queueId": "example_123" }, "schemaName": "ListAnnotationQueueItemsRequest" }, { "id": "evals-listAnnotationQueueItems-response", "operationId": "listAnnotationQueueItems", "operationKey": "evals:listAnnotationQueueItems", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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 } }, "status": "200", "schemaName": "ListAnnotationQueueItemsResponse" }, { "id": "evals-listAnnotationQueues-request", "operationId": "listAnnotationQueues", "operationKey": "evals:listAnnotationQueues", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": {}, "schemaName": "ListAnnotationQueuesRequest" }, { "id": "evals-listAnnotationQueues-response", "operationId": "listAnnotationQueues", "operationKey": "evals:listAnnotationQueues", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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 } }, "status": "200", "schemaName": "ListAnnotationQueuesResponse" }, { "id": "evals-listComments-request", "operationId": "listComments", "operationKey": "evals:listComments", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": {}, "schemaName": "ListCommentsRequest" }, { "id": "evals-listComments-response", "operationId": "listComments", "operationKey": "evals:listComments", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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 } }, "status": "200", "schemaName": "ListCommentsResponse" }, { "id": "evals-listDatasetItems-request", "operationId": "listDatasetItems", "operationKey": "evals:listDatasetItems", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "List items from an existing dataset by name.", "payload": { "datasetName": "support-answers", "page": 1, "pageSize": 20 }, "schemaName": "ListDatasetItemsRequest" }, { "id": "evals-listDatasetItems-response", "operationId": "listDatasetItems", "operationKey": "evals:listDatasetItems", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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 } }, "status": "200", "schemaName": "ListDatasetItemsResponse" }, { "id": "evals-listDatasetRuns-request", "operationId": "listDatasetRuns", "operationKey": "evals:listDatasetRuns", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "datasetName": "example" }, "schemaName": "ListDatasetRunsRequest" }, { "id": "evals-listDatasetRuns-response", "operationId": "listDatasetRuns", "operationKey": "evals:listDatasetRuns", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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 } }, "status": "200", "schemaName": "ListDatasetRunsResponse" }, { "id": "evals-listDatasets-request", "operationId": "listDatasets", "operationKey": "evals:listDatasets", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": {}, "schemaName": "ListDatasetsRequest" }, { "id": "evals-listDatasets-response", "operationId": "listDatasets", "operationKey": "evals:listDatasets", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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 } }, "status": "200", "schemaName": "ListDatasetsResponse" }, { "id": "evals-listObservations-request", "operationId": "listObservations", "operationKey": "evals:listObservations", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": {}, "schemaName": "ListObservationsRequest" }, { "id": "evals-listObservations-response", "operationId": "listObservations", "operationKey": "evals:listObservations", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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 } }, "status": "200", "schemaName": "ListObservationsResponse" }, { "id": "evals-listScoreConfigs-request", "operationId": "listScoreConfigs", "operationKey": "evals:listScoreConfigs", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": {}, "schemaName": "ListScoreConfigsRequest" }, { "id": "evals-listScoreConfigs-response", "operationId": "listScoreConfigs", "operationKey": "evals:listScoreConfigs", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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 } }, "status": "200", "schemaName": "ListScoreConfigsResponse" }, { "id": "evals-listScores-request", "operationId": "listScores", "operationKey": "evals:listScores", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": {}, "schemaName": "ListScoresRequest" }, { "id": "evals-listScores-response", "operationId": "listScores", "operationKey": "evals:listScores", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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 } }, "status": "200", "schemaName": "ListScoresResponse" }, { "id": "evals-listSessions-request", "operationId": "listSessions", "operationKey": "evals:listSessions", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": {}, "schemaName": "ListSessionsRequest" }, { "id": "evals-listSessions-response", "operationId": "listSessions", "operationKey": "evals:listSessions", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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 } }, "status": "200", "schemaName": "ListSessionsResponse" }, { "id": "evals-listTraces-request", "operationId": "listTraces", "operationKey": "evals:listTraces", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": {}, "schemaName": "ListTracesRequest" }, { "id": "evals-listTraces-response", "operationId": "listTraces", "operationKey": "evals:listTraces", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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 } }, "status": "200", "schemaName": "ListTracesResponse" }, { "id": "evals-recordDatasetRun-request", "operationId": "recordDatasetRun", "operationKey": "evals:recordDatasetRun", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "datasetId": "example_123", "runName": "example", "items": [ { "datasetItemId": "example_123", "traceId": "example_123" } ] }, "schemaName": "RecordDatasetRunRequest" }, { "id": "evals-recordDatasetRun-response", "operationId": "recordDatasetRun", "operationKey": "evals:recordDatasetRun", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "runId": "example_123" }, "status": "200", "schemaName": "RecordDatasetRunResponse" }, { "id": "evals-recordScore-request", "operationId": "recordScore", "operationKey": "evals:recordScore", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Score an existing trace as an authenticated rater; this numeric example records 0.9.", "payload": { "targetType": "EVAL_TARGET_TYPE_TRACE", "targetId": "trace_123", "name": "answer-quality", "dataType": "SCORE_DATA_TYPE_NUMERIC", "numericValue": 0.9 }, "schemaName": "RecordScoreRequest" }, { "id": "evals-recordScore-response", "operationId": "recordScore", "operationKey": "evals:recordScore", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "scoreId": "example_123", "targetId": "example_123", "targetType": "EVAL_TARGET_TYPE_TRACE" }, "status": "200", "schemaName": "RecordScoreResponse" }, { "id": "evals-updateDatasetItem-request", "operationId": "updateDatasetItem", "operationKey": "evals:updateDatasetItem", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Replace an existing item using its dataset name; retain the input when revising its expected output.", "payload": { "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.\"" }, "schemaName": "UpdateDatasetItemRequest" }, { "id": "evals-updateDatasetItem-response", "operationId": "updateDatasetItem", "operationKey": "evals:updateDatasetItem", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "itemId": "example_123" }, "status": "200", "schemaName": "UpdateDatasetItemResponse" }, { "id": "evals-updateScoreConfig-request", "operationId": "updateScoreConfig", "operationKey": "evals:updateScoreConfig", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "configId": "example_123", "name": "example" }, "schemaName": "UpdateScoreConfigRequest" }, { "id": "evals-updateScoreConfig-response", "operationId": "updateScoreConfig", "operationKey": "evals:updateScoreConfig", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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" } }, "status": "200", "schemaName": "UpdateScoreConfigResponse" }, { "id": "mcp-servers-createCustomMcpServer-request", "operationId": "createCustomMcpServer", "operationKey": "mcp-servers:createCustomMcpServer", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Register an enabled server without authentication; replace the example endpoint with your reachable MCP endpoint.", "payload": { "server": { "serverId": "product-tools", "displayName": "Product tools", "endpoint": "https://mcp.example.com/mcp", "authType": "CUSTOM_MCP_SERVER_AUTH_TYPE_NONE", "enabled": true } }, "schemaName": "CreateCustomMCPServerRequest" }, { "id": "mcp-servers-createCustomMcpServer-response", "operationId": "createCustomMcpServer", "operationKey": "mcp-servers:createCustomMcpServer", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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" } }, "status": "200", "schemaName": "CreateCustomMCPServerResponse" }, { "id": "mcp-servers-getCustomMcpServer-request", "operationId": "getCustomMcpServer", "operationKey": "mcp-servers:getCustomMcpServer", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Use the unprefixed serverId of a custom server registered in your project.", "payload": { "serverId": "product-tools" }, "schemaName": "GetCustomMCPServerRequest" }, { "id": "mcp-servers-getCustomMcpServer-response", "operationId": "getCustomMcpServer", "operationKey": "mcp-servers:getCustomMcpServer", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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" } }, "status": "200", "schemaName": "GetCustomMCPServerResponse" }, { "id": "mcp-servers-listCustomMcpServers-request", "operationId": "listCustomMcpServers", "operationKey": "mcp-servers:listCustomMcpServers", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "List enabled custom MCP servers in the authenticated project.", "payload": {}, "schemaName": "ListCustomMCPServersRequest" }, { "id": "mcp-servers-listCustomMcpServers-response", "operationId": "listCustomMcpServers", "operationKey": "mcp-servers:listCustomMcpServers", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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 }, "status": "200", "schemaName": "ListCustomMCPServersResponse" }, { "id": "mcp-servers-updateCustomMcpServer-request", "operationId": "updateCustomMcpServer", "operationKey": "mcp-servers:updateCustomMcpServer", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Replace an existing server configuration; preserve the intended authentication and enabled settings.", "payload": { "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 } }, "schemaName": "UpdateCustomMCPServerRequest" }, { "id": "mcp-servers-updateCustomMcpServer-response", "operationId": "updateCustomMcpServer", "operationKey": "mcp-servers:updateCustomMcpServer", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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" } }, "status": "200", "schemaName": "UpdateCustomMCPServerResponse" }, { "id": "mcp-servers-deleteCustomMcpServer-request", "operationId": "deleteCustomMcpServer", "operationKey": "mcp-servers:deleteCustomMcpServer", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Use the unprefixed serverId of a custom server registered in your project.", "payload": { "serverId": "product-tools" }, "schemaName": "DeleteCustomMCPServerRequest" }, { "id": "mcp-servers-deleteCustomMcpServer-response", "operationId": "deleteCustomMcpServer", "operationKey": "mcp-servers:deleteCustomMcpServer", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "deleted": true }, "status": "200", "schemaName": "DeleteCustomMCPServerResponse" }, { "id": "mcp-servers-testCustomMcpServerConnection-request", "operationId": "testCustomMcpServerConnection", "operationKey": "mcp-servers:testCustomMcpServerConnection", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Use the unprefixed serverId of a custom server registered in your project.", "payload": { "serverId": "product-tools" }, "schemaName": "TestCustomMCPServerConnectionRequest" }, { "id": "mcp-servers-testCustomMcpServerConnection-response", "operationId": "testCustomMcpServerConnection", "operationKey": "mcp-servers:testCustomMcpServerConnection", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "success": true, "toolCount": 1, "latencyMs": "1", "error": "example" }, "status": "200", "schemaName": "TestCustomMCPServerConnectionResponse" }, { "id": "notifications-registerPushDevice-request", "operationId": "registerPushDevice", "operationKey": "notifications:registerPushDevice", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Register the selected user’s actual device token; the displayed token is a placeholder.", "payload": { "fcmToken": "REPLACE_WITH_DEVICE_FCM_TOKEN" }, "schemaName": "RegisterPushDeviceRequest" }, { "id": "notifications-registerPushDevice-response", "operationId": "registerPushDevice", "operationKey": "notifications:registerPushDevice", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "success": true, "subscriberId": "example_123" }, "status": "200", "schemaName": "RegisterPushDeviceResponse" }, { "id": "notifications-unregisterPushDevice-request", "operationId": "unregisterPushDevice", "operationKey": "notifications:unregisterPushDevice", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Remove a device token previously registered for the selected user.", "payload": { "fcmToken": "REPLACE_WITH_DEVICE_FCM_TOKEN" }, "schemaName": "UnregisterPushDeviceRequest" }, { "id": "notifications-unregisterPushDevice-response", "operationId": "unregisterPushDevice", "operationKey": "notifications:unregisterPushDevice", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "subscriberId": "example_123", "remainingCredentialCount": 1 }, "status": "200", "schemaName": "UnregisterPushDeviceResponse" }, { "id": "notifications-getRegisteredChannels-request", "operationId": "getRegisteredChannels", "operationKey": "notifications:getRegisteredChannels", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Read the notification channels registered for the selected user.", "payload": {}, "schemaName": "GetRegisteredChannelsRequest" }, { "id": "notifications-getRegisteredChannels-response", "operationId": "getRegisteredChannels", "operationKey": "notifications:getRegisteredChannels", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "channels": [ { "channel": "CHANNEL_PUSH", "registered": true, "credentialCount": 1 } ] }, "status": "200", "schemaName": "GetRegisteredChannelsResponse" }, { "id": "notifications-getInboxSession-request", "operationId": "getInboxSession", "operationKey": "notifications:getInboxSession", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Create an inbox session for the selected user; identity comes from authentication.", "payload": {}, "schemaName": "GetInboxSessionRequest" }, { "id": "notifications-getInboxSession-response", "operationId": "getInboxSession", "operationKey": "notifications:getInboxSession", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "token": "example", "socketUrl": "https://example.com/resource", "expiresIn": "1" }, "status": "200", "schemaName": "GetInboxSessionResponse" }, { "id": "notifications-getInboxFeed-request", "operationId": "getInboxFeed", "operationKey": "notifications:getInboxFeed", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Read the selected user’s inbox using default paging and filters.", "payload": {}, "schemaName": "GetInboxFeedRequest" }, { "id": "notifications-getInboxFeed-response", "operationId": "getInboxFeed", "operationKey": "notifications:getInboxFeed", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "messages": [ { "messageId": "example_123", "notificationId": "example_123", "title": "example", "body": "example", "data": {}, "deepLink": "example", "imageUrl": "https://example.com/resource", "status": "MESSAGE_STATUS_UNSEEN", "category": "example", "createdAt": "2026-09-16T12:00:00Z", "seenAt": "2026-09-16T12:00:00Z", "readAt": "2026-09-16T12:00:00Z", "actions": [ { "actionId": "example_123", "label": "example", "url": "https://example.com/resource", "isPrimary": true, "completed": true } ], "tags": [ "example" ], "archived": true, "archivedAt": "2026-09-16T12:00:00Z" } ], "totalCount": 1, "page": 1, "pageSize": 1, "hasMore": true }, "status": "200", "schemaName": "GetInboxFeedResponse" }, { "id": "notifications-getInboxUnseenCount-request", "operationId": "getInboxUnseenCount", "operationKey": "notifications:getInboxUnseenCount", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Count unseen messages in the selected user’s inbox.", "payload": {}, "schemaName": "GetInboxUnseenCountRequest" }, { "id": "notifications-getInboxUnseenCount-response", "operationId": "getInboxUnseenCount", "operationKey": "notifications:getInboxUnseenCount", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "unseenCount": 1, "unreadCount": 1, "hasMoreUnseen": true, "hasMoreUnread": true }, "status": "200", "schemaName": "GetInboxUnseenCountResponse" }, { "id": "notifications-markInboxMessageAs-request", "operationId": "markInboxMessageAs", "operationKey": "notifications:markInboxMessageAs", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Mark an existing inbox message as read.", "payload": { "messageId": "msg_123", "markAs": "MESSAGE_STATUS_READ" }, "schemaName": "MarkInboxMessageAsRequest" }, { "id": "notifications-markInboxMessageAs-response", "operationId": "markInboxMessageAs", "operationKey": "notifications:markInboxMessageAs", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "messages": [ { "messageId": "example_123", "channel": "example", "read": true, "seen": true, "archived": true, "content": "Example text", "subject": "example", "status": "example", "createdAt": "example", "lastReadDate": "example", "lastSeenDate": "example" } ] }, "status": "200", "schemaName": "MarkInboxMessageAsResponse" }, { "id": "notifications-markAllInboxMessagesAs-request", "operationId": "markAllInboxMessagesAs", "operationKey": "notifications:markAllInboxMessagesAs", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Mark all inbox messages in the selected user scope as read.", "payload": { "markAs": "MESSAGE_STATUS_READ" }, "schemaName": "MarkAllInboxMessagesAsRequest" }, { "id": "notifications-markAllInboxMessagesAs-response", "operationId": "markAllInboxMessagesAs", "operationKey": "notifications:markAllInboxMessagesAs", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "updatedCount": 1 }, "status": "200", "schemaName": "MarkAllInboxMessagesAsResponse" }, { "id": "notifications-deleteInboxMessage-request", "operationId": "deleteInboxMessage", "operationKey": "notifications:deleteInboxMessage", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "messageId": "example_123" }, "schemaName": "DeleteInboxMessageRequest" }, { "id": "notifications-deleteInboxMessage-response", "operationId": "deleteInboxMessage", "operationKey": "notifications:deleteInboxMessage", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "status": { "acknowledged": true, "status": "example" } }, "status": "200", "schemaName": "DeleteInboxMessageResponse" }, { "id": "notifications-archiveInboxMessage-request", "operationId": "archiveInboxMessage", "operationKey": "notifications:archiveInboxMessage", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "notificationId": "example_123" }, "schemaName": "ArchiveInboxMessageRequest" }, { "id": "notifications-archiveInboxMessage-response", "operationId": "archiveInboxMessage", "operationKey": "notifications:archiveInboxMessage", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "status": { "acknowledged": true, "status": "example" } }, "status": "200", "schemaName": "ArchiveInboxMessageResponse" }, { "id": "notifications-unarchiveInboxMessage-request", "operationId": "unarchiveInboxMessage", "operationKey": "notifications:unarchiveInboxMessage", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "notificationId": "example_123" }, "schemaName": "UnarchiveInboxMessageRequest" }, { "id": "notifications-unarchiveInboxMessage-response", "operationId": "unarchiveInboxMessage", "operationKey": "notifications:unarchiveInboxMessage", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "status": { "acknowledged": true, "status": "example" } }, "status": "200", "schemaName": "UnarchiveInboxMessageResponse" }, { "id": "notifications-archiveAllInboxMessages-request", "operationId": "archiveAllInboxMessages", "operationKey": "notifications:archiveAllInboxMessages", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Archive all messages in the selected user’s inbox; no tag filter is supplied.", "payload": {}, "schemaName": "ArchiveAllInboxMessagesRequest" }, { "id": "notifications-archiveAllInboxMessages-response", "operationId": "archiveAllInboxMessages", "operationKey": "notifications:archiveAllInboxMessages", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "archivedCount": 1 }, "status": "200", "schemaName": "ArchiveAllInboxMessagesResponse" }, { "id": "notifications-archiveAllReadInboxMessages-request", "operationId": "archiveAllReadInboxMessages", "operationKey": "notifications:archiveAllReadInboxMessages", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Archive all read messages in the selected user’s inbox; no tag filter is supplied.", "payload": {}, "schemaName": "ArchiveAllReadInboxMessagesRequest" }, { "id": "notifications-archiveAllReadInboxMessages-response", "operationId": "archiveAllReadInboxMessages", "operationKey": "notifications:archiveAllReadInboxMessages", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "archivedCount": 1 }, "status": "200", "schemaName": "ArchiveAllReadInboxMessagesResponse" }, { "id": "notifications-completeInboxAction-request", "operationId": "completeInboxAction", "operationKey": "notifications:completeInboxAction", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "notificationId": "example_123", "actionType": "ACTION_TYPE_PRIMARY" }, "schemaName": "CompleteInboxActionRequest" }, { "id": "notifications-completeInboxAction-response", "operationId": "completeInboxAction", "operationKey": "notifications:completeInboxAction", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "status": { "acknowledged": true, "status": "example" } }, "status": "200", "schemaName": "CompleteInboxActionResponse" }, { "id": "notifications-revertInboxAction-request", "operationId": "revertInboxAction", "operationKey": "notifications:revertInboxAction", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "notificationId": "example_123", "actionType": "ACTION_TYPE_PRIMARY" }, "schemaName": "RevertInboxActionRequest" }, { "id": "notifications-revertInboxAction-response", "operationId": "revertInboxAction", "operationKey": "notifications:revertInboxAction", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "status": { "acknowledged": true, "status": "example" } }, "status": "200", "schemaName": "RevertInboxActionResponse" }, { "id": "notifications-getPreferences-request", "operationId": "getPreferences", "operationKey": "notifications:getPreferences", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Read notification preferences for the selected user.", "payload": {}, "schemaName": "GetPreferencesRequest" }, { "id": "notifications-getPreferences-response", "operationId": "getPreferences", "operationKey": "notifications:getPreferences", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "global": { "enabled": true, "channels": { "inApp": true, "push": true, "email": true, "sms": true, "chat": true } }, "workflows": [ { "workflowId": "example_123", "workflowName": "example", "critical": true, "tags": [ "example" ], "channels": { "inApp": true, "push": true, "email": true, "sms": true, "chat": true } } ] }, "status": "200", "schemaName": "GetPreferencesResponse" }, { "id": "notifications-updateGlobalPreference-request", "operationId": "updateGlobalPreference", "operationKey": "notifications:updateGlobalPreference", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Disable push notifications while leaving omitted channels unchanged.", "payload": { "channels": { "push": false } }, "schemaName": "UpdateGlobalPreferenceRequest" }, { "id": "notifications-updateGlobalPreference-response", "operationId": "updateGlobalPreference", "operationKey": "notifications:updateGlobalPreference", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": {}, "status": "200", "schemaName": "ProtobufEmpty" }, { "id": "notifications-updateWorkflowPreference-request", "operationId": "updateWorkflowPreference", "operationKey": "notifications:updateWorkflowPreference", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Disable push for an existing workflow while leaving other channels unchanged.", "payload": { "workflowId": "promotional", "channels": { "push": false } }, "schemaName": "UpdateWorkflowPreferenceRequest" }, { "id": "notifications-updateWorkflowPreference-response", "operationId": "updateWorkflowPreference", "operationKey": "notifications:updateWorkflowPreference", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": {}, "status": "200", "schemaName": "ProtobufEmpty" }, { "id": "notifications-bulkUpdatePreferences-request", "operationId": "bulkUpdatePreferences", "operationKey": "notifications:bulkUpdatePreferences", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Update two existing workflows; inspect the per-entry outcomes.", "payload": { "entries": [ { "workflowId": "promotional", "channels": { "push": false } }, { "workflowId": "weekly-summary", "channels": { "inApp": true, "push": true } } ] }, "schemaName": "BulkUpdatePreferencesRequest" }, { "id": "notifications-bulkUpdatePreferences-response", "operationId": "bulkUpdatePreferences", "operationKey": "notifications:bulkUpdatePreferences", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "updatedCount": 1 }, "status": "200", "schemaName": "BulkUpdatePreferencesResponse" }, { "id": "notifications-sendNotification-request", "operationId": "sendNotification", "operationKey": "notifications:sendNotification", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Trigger the prepared welcome workflow for an enrolled user; replace the workflow and user identifiers.", "payload": { "workflowId": "welcome-notification", "userId": "user-1", "payload": {} }, "schemaName": "SendNotificationRequest" }, { "id": "notifications-sendNotification-response", "operationId": "sendNotification", "operationKey": "notifications:sendNotification", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "acknowledged": true, "status": "example", "transactionId": "example_123", "errors": [ "example" ] }, "status": "200", "schemaName": "SendNotificationResponse" }, { "id": "notifications-sendBulkNotification-request", "operationId": "sendBulkNotification", "operationKey": "notifications:sendBulkNotification", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Trigger a prepared workflow for two enrolled users; inspect every returned result.", "payload": { "events": [ { "workflowId": "push-notification", "userId": "user-1", "payload": { "title": "Update", "body": "New feature available" } }, { "workflowId": "push-notification", "userId": "user-2", "payload": { "title": "Update", "body": "New feature available" } } ] }, "schemaName": "SendBulkNotificationRequest" }, { "id": "notifications-sendBulkNotification-response", "operationId": "sendBulkNotification", "operationKey": "notifications:sendBulkNotification", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "results": [ { "acknowledged": true, "status": "example", "transactionId": "example_123", "errors": [ "example" ] } ] }, "status": "200", "schemaName": "SendBulkNotificationResponse" }, { "id": "notifications-cancelNotification-request", "operationId": "cancelNotification", "operationKey": "notifications:cancelNotification", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "transactionId": "example_123" }, "schemaName": "CancelNotificationRequest" }, { "id": "notifications-cancelNotification-response", "operationId": "cancelNotification", "operationKey": "notifications:cancelNotification", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "cancelled": true, "message": "example" }, "status": "200", "schemaName": "CancelNotificationResponse" }, { "id": "notifications-createTopic-request", "operationId": "createTopic", "operationKey": "notifications:createTopic", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Create a topic before adding its subscribers.", "payload": { "topicKey": "product-updates", "name": "Product updates" }, "schemaName": "CreateTopicRequest" }, { "id": "notifications-createTopic-response", "operationId": "createTopic", "operationKey": "notifications:createTopic", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "topicKey": "example_123", "topicId": "example_123" }, "status": "200", "schemaName": "CreateTopicResponse" }, { "id": "notifications-deleteTopic-request", "operationId": "deleteTopic", "operationKey": "notifications:deleteTopic", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "topicKey": "example_123" }, "schemaName": "DeleteTopicRequest" }, { "id": "notifications-deleteTopic-response", "operationId": "deleteTopic", "operationKey": "notifications:deleteTopic", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "status": { "acknowledged": true, "status": "example" } }, "status": "200", "schemaName": "DeleteTopicResponse" }, { "id": "notifications-addSubscribersToTopic-request", "operationId": "addSubscribersToTopic", "operationKey": "notifications:addSubscribersToTopic", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Add existing application users to an existing topic.", "payload": { "topicKey": "product-updates", "userIds": [ "user-1", "user-2" ] }, "schemaName": "AddSubscribersToTopicRequest" }, { "id": "notifications-addSubscribersToTopic-response", "operationId": "addSubscribersToTopic", "operationKey": "notifications:addSubscribersToTopic", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "result": { "totalCount": 1, "successful": 1, "failed": 1, "errors": [ { "subscriberId": "example_123", "code": "example", "message": "example" } ] } }, "status": "200", "schemaName": "AddSubscribersToTopicResponse" }, { "id": "notifications-removeSubscribersFromTopic-request", "operationId": "removeSubscribersFromTopic", "operationKey": "notifications:removeSubscribersFromTopic", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Remove the selected application user from an existing topic.", "payload": { "topicKey": "product-updates", "userIds": [ "user-1" ] }, "schemaName": "RemoveSubscribersFromTopicRequest" }, { "id": "notifications-removeSubscribersFromTopic-response", "operationId": "removeSubscribersFromTopic", "operationKey": "notifications:removeSubscribersFromTopic", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "result": { "totalCount": 1, "successful": 1, "failed": 1, "errors": [ { "subscriberId": "example_123", "code": "example", "message": "example" } ] } }, "status": "200", "schemaName": "RemoveSubscribersFromTopicResponse" }, { "id": "notifications-listTopicSubscribers-request", "operationId": "listTopicSubscribers", "operationKey": "notifications:listTopicSubscribers", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "topicKey": "example_123" }, "schemaName": "ListTopicSubscribersRequest" }, { "id": "notifications-listTopicSubscribers-response", "operationId": "listTopicSubscribers", "operationKey": "notifications:listTopicSubscribers", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "userIds": [ "example_123" ], "totalCount": 1, "hasMore": true }, "status": "200", "schemaName": "ListTopicSubscribersResponse" }, { "id": "notifications-checkTopicSubscription-request", "operationId": "checkTopicSubscription", "operationKey": "notifications:checkTopicSubscription", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "topicKey": "example_123", "userId": "example_123" }, "schemaName": "CheckTopicSubscriptionRequest" }, { "id": "notifications-checkTopicSubscription-response", "operationId": "checkTopicSubscription", "operationKey": "notifications:checkTopicSubscription", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "isSubscribed": true }, "status": "200", "schemaName": "CheckTopicSubscriptionResponse" }, { "id": "notifications-sendToTopic-request", "operationId": "sendToTopic", "operationKey": "notifications:sendToTopic", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Trigger a prepared workflow for subscribers to an existing topic.", "payload": { "workflowId": "push-notification", "topicKey": "product-updates", "payload": { "title": "Update", "body": "New feature available" } }, "schemaName": "SendToTopicRequest" }, { "id": "notifications-sendToTopic-response", "operationId": "sendToTopic", "operationKey": "notifications:sendToTopic", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "acknowledged": true, "status": "example", "transactionId": "example_123", "errors": [ "example" ] }, "status": "200", "schemaName": "SendToTopicResponse" }, { "id": "notifications-sendWithDigest-request", "operationId": "sendWithDigest", "operationKey": "notifications:sendWithDigest", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Submit one event to a workflow that already has a digest step configured.", "payload": { "workflowId": "activity-digest", "userId": "user-1", "payload": { "title": "Account activity", "body": "A new report is available." } }, "schemaName": "SendWithDigestRequest" }, { "id": "notifications-sendWithDigest-response", "operationId": "sendWithDigest", "operationKey": "notifications:sendWithDigest", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "acknowledged": true, "status": "example", "transactionId": "example_123", "errors": [ "example" ] }, "status": "200", "schemaName": "SendWithDigestResponse" }, { "id": "notifications-cancelDigestEvent-request", "operationId": "cancelDigestEvent", "operationKey": "notifications:cancelDigestEvent", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "transactionId": "example_123" }, "schemaName": "CancelDigestEventRequest" }, { "id": "notifications-cancelDigestEvent-response", "operationId": "cancelDigestEvent", "operationKey": "notifications:cancelDigestEvent", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "cancelled": true, "message": "example" }, "status": "200", "schemaName": "CancelDigestEventResponse" }, { "id": "notifications-createSubscriber-request", "operationId": "createSubscriber", "operationKey": "notifications:createSubscriber", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Enroll an application user for notification delivery; use their stable application user ID.", "payload": { "subscriberId": "user-1", "email": "alex@example.com", "firstName": "Alex", "locale": "en-US" }, "schemaName": "CreateSubscriberRequest" }, { "id": "notifications-createSubscriber-response", "operationId": "createSubscriber", "operationKey": "notifications:createSubscriber", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "novuSubscriberId": "example_123", "subscriberId": "example_123" }, "status": "200", "schemaName": "CreateSubscriberResponse" }, { "id": "notifications-getSubscriber-request", "operationId": "getSubscriber", "operationKey": "notifications:getSubscriber", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Read the subscriber selected by authentication; no subscriber ID is accepted in this body.", "payload": {}, "schemaName": "GetSubscriberRequest" }, { "id": "notifications-getSubscriber-response", "operationId": "getSubscriber", "operationKey": "notifications:getSubscriber", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "subscriberId": "example_123", "data": { "firstName": "example", "lastName": "example", "email": "user@example.com", "phone": "example", "avatarUrl": "https://example.com/resource", "locale": "en-US", "timezone": "example", "customData": {} }, "channels": [ { "channel": "CHANNEL_PUSH", "registered": true, "credentialCount": 1 } ], "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z", "globalPreferences": { "enabled": true, "channels": { "inApp": true, "push": true, "email": true, "sms": true, "chat": true } }, "workflowPreferences": [ { "workflowId": "example_123", "workflowName": "example", "critical": true, "tags": [ "example" ], "channels": { "inApp": true, "push": true, "email": true, "sms": true, "chat": true } } ] }, "status": "200", "schemaName": "GetSubscriberResponse" }, { "id": "notifications-updateSubscriberData-request", "operationId": "updateSubscriberData", "operationKey": "notifications:updateSubscriberData", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Update attributes for the user selected by authentication.", "payload": { "data": { "firstName": "Alex", "locale": "en-US", "timezone": "America/New_York" } }, "schemaName": "UpdateSubscriberDataRequest" }, { "id": "notifications-updateSubscriberData-response", "operationId": "updateSubscriberData", "operationKey": "notifications:updateSubscriberData", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "data": { "firstName": "example", "lastName": "example", "email": "user@example.com", "phone": "example", "avatarUrl": "https://example.com/resource", "locale": "en-US", "timezone": "example", "customData": {} }, "updatedAt": "2026-09-16T12:00:00Z" }, "status": "200", "schemaName": "UpdateSubscriberDataResponse" }, { "id": "notifications-deleteSubscriber-request", "operationId": "deleteSubscriber", "operationKey": "notifications:deleteSubscriber", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Delete the subscriber selected by authentication; no subscriber ID is accepted in this body.", "payload": {}, "schemaName": "DeleteSubscriberRequest" }, { "id": "notifications-deleteSubscriber-response", "operationId": "deleteSubscriber", "operationKey": "notifications:deleteSubscriber", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "status": { "acknowledged": true, "status": "example" } }, "status": "200", "schemaName": "DeleteSubscriberResponse" }, { "id": "notifications-listSubscribers-request", "operationId": "listSubscribers", "operationKey": "notifications:listSubscribers", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "List subscribers in the authenticated tenant with default paging.", "payload": {}, "schemaName": "ListSubscribersRequest" }, { "id": "notifications-listSubscribers-response", "operationId": "listSubscribers", "operationKey": "notifications:listSubscribers", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "subscribers": [ { "subscriberId": "example_123", "email": "user@example.com", "firstName": "example", "lastName": "example", "isOnline": true, "lastOnlineAt": "2026-09-16T12:00:00Z" } ], "totalCount": 1, "hasMore": true }, "status": "200", "schemaName": "ListSubscribersResponse" }, { "id": "notifications-getDeliveryStatus-request", "operationId": "getDeliveryStatus", "operationKey": "notifications:getDeliveryStatus", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "transactionId": "example_123" }, "schemaName": "GetDeliveryStatusRequest" }, { "id": "notifications-getDeliveryStatus-response", "operationId": "getDeliveryStatus", "operationKey": "notifications:getDeliveryStatus", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "activity": { "example": "value" } }, "status": "200", "schemaName": "GetDeliveryStatusResponse" }, { "id": "notifications-getNotificationActivity-request", "operationId": "getNotificationActivity", "operationKey": "notifications:getNotificationActivity", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Read notification activity using default paging and filters.", "payload": {}, "schemaName": "GetNotificationActivityRequest" }, { "id": "notifications-getNotificationActivity-response", "operationId": "getNotificationActivity", "operationKey": "notifications:getNotificationActivity", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "entries": [ { "example": "value" } ], "hasMore": true }, "status": "200", "schemaName": "GetNotificationActivityResponse" }, { "id": "notifications-configureProvider-request", "operationId": "configureProvider", "operationKey": "notifications:configureProvider", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Configure email delivery with your SendGrid credential; the displayed key is a placeholder.", "payload": { "provider": "PROVIDER_TYPE_SENDGRID", "credentials": { "apiKey": "REPLACE_WITH_SENDGRID_API_KEY" }, "active": true }, "schemaName": "ConfigureProviderRequest" }, { "id": "notifications-configureProvider-response", "operationId": "configureProvider", "operationKey": "notifications:configureProvider", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "integrationId": "example_123", "active": true }, "status": "200", "schemaName": "ConfigureProviderResponse" }, { "id": "notifications-getProviders-request", "operationId": "getProviders", "operationKey": "notifications:getProviders", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "List configured notification delivery providers.", "payload": {}, "schemaName": "GetProvidersRequest" }, { "id": "notifications-getProviders-response", "operationId": "getProviders", "operationKey": "notifications:getProviders", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "providers": [ { "provider": "PROVIDER_TYPE_FCM", "integrationId": "example_123", "active": true } ] }, "status": "200", "schemaName": "GetProvidersResponse" }, { "id": "notifications-createWorkflow-request", "operationId": "createWorkflow", "operationKey": "notifications:createWorkflow", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Create the in-app welcome definition from the administration recipe; provider JSON is passed through.", "payload": { "workflow": { "name": "Welcome Notification", "description": "Sent when a user completes onboarding", "__source": "editor", "steps": [ { "name": "In-App Step", "type": "in_app", "controlValues": { "body": "Welcome to your health coaching journey!" } } ] } }, "schemaName": "CreateWorkflowRequest" }, { "id": "notifications-createWorkflow-response", "operationId": "createWorkflow", "operationKey": "notifications:createWorkflow", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "workflow": { "example": "value" } }, "status": "200", "schemaName": "CreateWorkflowResponse" }, { "id": "notifications-updateWorkflow-request", "operationId": "updateWorkflow", "operationKey": "notifications:updateWorkflow", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Replace an existing workflow with the complete definition; preserve every delivery step you intend to keep.", "payload": { "workflowId": "welcome-notification", "workflow": { "name": "Welcome Notification", "description": "Sent when a user completes onboarding", "__source": "editor", "steps": [ { "name": "In-App Step", "type": "in_app", "controlValues": { "body": "Welcome to your health coaching journey!" } } ] } }, "schemaName": "UpdateWorkflowRequest" }, { "id": "notifications-updateWorkflow-response", "operationId": "updateWorkflow", "operationKey": "notifications:updateWorkflow", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "workflow": { "example": "value" } }, "status": "200", "schemaName": "UpdateWorkflowResponse" }, { "id": "notifications-getWorkflow-request", "operationId": "getWorkflow", "operationKey": "notifications:getWorkflow", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Read an existing workflow using its saved workflow identifier.", "payload": { "workflowId": "welcome-notification" }, "schemaName": "GetWorkflowRequest" }, { "id": "notifications-getWorkflow-response", "operationId": "getWorkflow", "operationKey": "notifications:getWorkflow", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "workflow": { "example": "value" } }, "status": "200", "schemaName": "GetWorkflowResponse" }, { "id": "notifications-listWorkflows-request", "operationId": "listWorkflows", "operationKey": "notifications:listWorkflows", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "List notification workflows with default paging.", "payload": {}, "schemaName": "ListWorkflowsRequest" }, { "id": "notifications-listWorkflows-response", "operationId": "listWorkflows", "operationKey": "notifications:listWorkflows", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "workflows": [ { "example": "value" } ], "totalCount": 1, "hasMore": true }, "status": "200", "schemaName": "ListWorkflowsResponse" }, { "id": "notifications-deleteWorkflow-request", "operationId": "deleteWorkflow", "operationKey": "notifications:deleteWorkflow", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Retire an existing workflow after stopping new triggers.", "payload": { "workflowId": "welcome-notification" }, "schemaName": "DeleteWorkflowRequest" }, { "id": "notifications-deleteWorkflow-response", "operationId": "deleteWorkflow", "operationKey": "notifications:deleteWorkflow", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "workflowId": "example_123" }, "status": "200", "schemaName": "DeleteWorkflowResponse" }, { "id": "notifications-getPendingChanges-request", "operationId": "getPendingChanges", "operationKey": "notifications:getPendingChanges", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "List pending notification configuration changes in the configured environment.", "payload": {}, "schemaName": "GetPendingChangesRequest" }, { "id": "notifications-getPendingChanges-response", "operationId": "getPendingChanges", "operationKey": "notifications:getPendingChanges", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "changes": [ { "changeId": "example_123", "type": "example", "entityName": "example", "entityId": "example_123", "createdAt": "2026-09-16T12:00:00Z", "createdBy": "example" } ], "totalCount": 1 }, "status": "200", "schemaName": "GetPendingChangesResponse" }, { "id": "notifications-promoteChange-request", "operationId": "promoteChange", "operationKey": "notifications:promoteChange", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "changeId": "example_123" }, "schemaName": "PromoteChangeRequest" }, { "id": "notifications-promoteChange-response", "operationId": "promoteChange", "operationKey": "notifications:promoteChange", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "success": true, "productionEntityId": "example_123" }, "status": "200", "schemaName": "PromoteChangeResponse" }, { "id": "notifications-promoteAllChanges-request", "operationId": "promoteAllChanges", "operationKey": "notifications:promoteAllChanges", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Promote explicitly selected pending changes; replace changeIds with IDs from get-pending-changes.", "payload": { "changeIds": [ "change_123" ] }, "schemaName": "PromoteAllChangesRequest" }, { "id": "notifications-promoteAllChanges-response", "operationId": "promoteAllChanges", "operationKey": "notifications:promoteAllChanges", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "promotedCount": 1, "promotedIds": [ "example_123" ], "errors": [ { "changeId": "example_123", "error": "example" } ] }, "status": "200", "schemaName": "PromoteAllChangesResponse" }, { "id": "scheduled-jobs-createJob-request", "operationId": "createJob", "operationKey": "scheduled-jobs:createJob", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schedule a weekday digest while acting on behalf of its owner; replace the target URL with your endpoint.", "payload": { "name": "Daily digest", "scheduleType": "SCHEDULE_TYPE_CRON", "cronExpression": "0 9 * * 1-5", "timezone": "America/New_York", "target": { "url": "https://your-api.example.com/jobs/daily-digest", "kind": "digest", "payload": { "report": "daily" } } }, "schemaName": "CreateJobRequest" }, { "id": "scheduled-jobs-createJob-response", "operationId": "createJob", "operationKey": "scheduled-jobs:createJob", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "scheduleId": "sched_a1b2c3d4e5f60718", "tenantId": "example_123", "projectId": "example_123", "ownerSubject": "example", "name": "example", "description": "example", "scheduleType": "SCHEDULE_TYPE_CRON", "cronExpression": "0 9 * * *", "timezone": "example", "scheduledAt": "2026-09-16T12:00:00Z", "intervalSeconds": 1, "target": { "url": "https://example.com/callback", "method": "example", "kind": "example", "payload": { "example": "value" } }, "state": "SCHEDULE_STATUS_ACTIVE", "retryPolicy": { "maxAttempts": 1, "initialBackoffMs": 1, "maxBackoffMs": 1 }, "metadata": { "example": "value" }, "autoPauseThreshold": 1, "externalId": "example_123", "createdAt": "2026-09-16T12:00:00Z", "createdBySubject": "example", "updatedAt": "2026-09-16T12:00:00Z", "updatedBySubject": "example", "pausedAt": "2026-09-16T12:00:00Z", "pausedBySubject": "example", "pausedReason": "example", "resumedAt": "2026-09-16T12:00:00Z", "resumedBySubject": "example", "deletedAt": "2026-09-16T12:00:00Z", "deletedBySubject": "example", "lastTriggeredAt": "2026-09-16T12:00:00Z", "nextTriggerAt": "2026-09-16T12:00:00Z", "triggerCount": "1", "failureCount": "1", "consecutiveFailureCount": "1" }, "status": "200", "schemaName": "Schedule" }, { "id": "scheduled-jobs-getJob-request", "operationId": "getJob", "operationKey": "scheduled-jobs:getJob", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Replace scheduleId with the ID returned when the job was created.", "payload": { "scheduleId": "sched_a1b2c3d4e5f60718" }, "schemaName": "GetJobRequest" }, { "id": "scheduled-jobs-getJob-response", "operationId": "getJob", "operationKey": "scheduled-jobs:getJob", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "scheduleId": "sched_a1b2c3d4e5f60718", "tenantId": "example_123", "projectId": "example_123", "ownerSubject": "example", "name": "example", "description": "example", "scheduleType": "SCHEDULE_TYPE_CRON", "cronExpression": "0 9 * * *", "timezone": "example", "scheduledAt": "2026-09-16T12:00:00Z", "intervalSeconds": 1, "target": { "url": "https://example.com/callback", "method": "example", "kind": "example", "payload": { "example": "value" } }, "state": "SCHEDULE_STATUS_ACTIVE", "retryPolicy": { "maxAttempts": 1, "initialBackoffMs": 1, "maxBackoffMs": 1 }, "metadata": { "example": "value" }, "autoPauseThreshold": 1, "externalId": "example_123", "createdAt": "2026-09-16T12:00:00Z", "createdBySubject": "example", "updatedAt": "2026-09-16T12:00:00Z", "updatedBySubject": "example", "pausedAt": "2026-09-16T12:00:00Z", "pausedBySubject": "example", "pausedReason": "example", "resumedAt": "2026-09-16T12:00:00Z", "resumedBySubject": "example", "deletedAt": "2026-09-16T12:00:00Z", "deletedBySubject": "example", "lastTriggeredAt": "2026-09-16T12:00:00Z", "nextTriggerAt": "2026-09-16T12:00:00Z", "triggerCount": "1", "failureCount": "1", "consecutiveFailureCount": "1" }, "status": "200", "schemaName": "Schedule" }, { "id": "scheduled-jobs-listJobs-request", "operationId": "listJobs", "operationKey": "scheduled-jobs:listJobs", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "List jobs visible in the authenticated scope with default paging.", "payload": {}, "schemaName": "ListJobsRequest" }, { "id": "scheduled-jobs-listJobs-response", "operationId": "listJobs", "operationKey": "scheduled-jobs:listJobs", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "schedules": [ { "scheduleId": "sched_a1b2c3d4e5f60718", "tenantId": "example_123", "projectId": "example_123", "ownerSubject": "example", "name": "example", "description": "example", "scheduleType": "SCHEDULE_TYPE_CRON", "cronExpression": "0 9 * * *", "timezone": "example", "scheduledAt": "2026-09-16T12:00:00Z", "intervalSeconds": 1, "target": { "url": "https://example.com/callback", "method": "example", "kind": "example" }, "state": "SCHEDULE_STATUS_ACTIVE", "retryPolicy": { "maxAttempts": 1, "initialBackoffMs": 1, "maxBackoffMs": 1 }, "metadata": { "example": "value" }, "autoPauseThreshold": 1, "externalId": "example_123", "createdAt": "2026-09-16T12:00:00Z", "createdBySubject": "example", "updatedAt": "2026-09-16T12:00:00Z", "updatedBySubject": "example", "pausedAt": "2026-09-16T12:00:00Z", "pausedBySubject": "example", "pausedReason": "example", "resumedAt": "2026-09-16T12:00:00Z", "resumedBySubject": "example", "deletedAt": "2026-09-16T12:00:00Z", "deletedBySubject": "example", "lastTriggeredAt": "2026-09-16T12:00:00Z", "nextTriggerAt": "2026-09-16T12:00:00Z", "triggerCount": "1", "failureCount": "1", "consecutiveFailureCount": "1" } ], "nextPageToken": "example", "totalCount": 1 }, "status": "200", "schemaName": "ListJobsResponse" }, { "id": "scheduled-jobs-updateJob-request", "operationId": "updateJob", "operationKey": "scheduled-jobs:updateJob", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Rename an existing job using its returned scheduleId.", "payload": { "scheduleId": "sched_a1b2c3d4e5f60718", "name": "Weekday morning digest" }, "schemaName": "UpdateJobRequest" }, { "id": "scheduled-jobs-updateJob-response", "operationId": "updateJob", "operationKey": "scheduled-jobs:updateJob", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "schedule": { "scheduleId": "sched_a1b2c3d4e5f60718", "tenantId": "example_123", "projectId": "example_123", "ownerSubject": "example", "name": "example", "description": "example", "scheduleType": "SCHEDULE_TYPE_CRON", "cronExpression": "0 9 * * *", "timezone": "example", "scheduledAt": "2026-09-16T12:00:00Z", "intervalSeconds": 1, "target": { "url": "https://example.com/callback", "method": "example", "kind": "example" }, "state": "SCHEDULE_STATUS_ACTIVE", "retryPolicy": { "maxAttempts": 1, "initialBackoffMs": 1, "maxBackoffMs": 1 }, "metadata": { "example": "value" }, "autoPauseThreshold": 1, "externalId": "example_123", "createdAt": "2026-09-16T12:00:00Z", "createdBySubject": "example", "updatedAt": "2026-09-16T12:00:00Z", "updatedBySubject": "example", "pausedAt": "2026-09-16T12:00:00Z", "pausedBySubject": "example", "pausedReason": "example", "resumedAt": "2026-09-16T12:00:00Z", "resumedBySubject": "example", "deletedAt": "2026-09-16T12:00:00Z", "deletedBySubject": "example", "lastTriggeredAt": "2026-09-16T12:00:00Z", "nextTriggerAt": "2026-09-16T12:00:00Z", "triggerCount": "1", "failureCount": "1", "consecutiveFailureCount": "1" }, "effectiveAt": "example" }, "status": "200", "schemaName": "UpdateJobResponse" }, { "id": "scheduled-jobs-pauseJob-request", "operationId": "pauseJob", "operationKey": "scheduled-jobs:pauseJob", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Replace scheduleId with the ID returned when the job was created.", "payload": { "scheduleId": "sched_a1b2c3d4e5f60718" }, "schemaName": "PauseJobRequest" }, { "id": "scheduled-jobs-pauseJob-response", "operationId": "pauseJob", "operationKey": "scheduled-jobs:pauseJob", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "scheduleId": "sched_a1b2c3d4e5f60718", "tenantId": "example_123", "projectId": "example_123", "ownerSubject": "example", "name": "example", "description": "example", "scheduleType": "SCHEDULE_TYPE_CRON", "cronExpression": "0 9 * * *", "timezone": "example", "scheduledAt": "2026-09-16T12:00:00Z", "intervalSeconds": 1, "target": { "url": "https://example.com/callback", "method": "example", "kind": "example", "payload": { "example": "value" } }, "state": "SCHEDULE_STATUS_ACTIVE", "retryPolicy": { "maxAttempts": 1, "initialBackoffMs": 1, "maxBackoffMs": 1 }, "metadata": { "example": "value" }, "autoPauseThreshold": 1, "externalId": "example_123", "createdAt": "2026-09-16T12:00:00Z", "createdBySubject": "example", "updatedAt": "2026-09-16T12:00:00Z", "updatedBySubject": "example", "pausedAt": "2026-09-16T12:00:00Z", "pausedBySubject": "example", "pausedReason": "example", "resumedAt": "2026-09-16T12:00:00Z", "resumedBySubject": "example", "deletedAt": "2026-09-16T12:00:00Z", "deletedBySubject": "example", "lastTriggeredAt": "2026-09-16T12:00:00Z", "nextTriggerAt": "2026-09-16T12:00:00Z", "triggerCount": "1", "failureCount": "1", "consecutiveFailureCount": "1" }, "status": "200", "schemaName": "Schedule" }, { "id": "scheduled-jobs-resumeJob-request", "operationId": "resumeJob", "operationKey": "scheduled-jobs:resumeJob", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Replace scheduleId with the ID returned when the job was created.", "payload": { "scheduleId": "sched_a1b2c3d4e5f60718" }, "schemaName": "ResumeJobRequest" }, { "id": "scheduled-jobs-resumeJob-response", "operationId": "resumeJob", "operationKey": "scheduled-jobs:resumeJob", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "scheduleId": "sched_a1b2c3d4e5f60718", "tenantId": "example_123", "projectId": "example_123", "ownerSubject": "example", "name": "example", "description": "example", "scheduleType": "SCHEDULE_TYPE_CRON", "cronExpression": "0 9 * * *", "timezone": "example", "scheduledAt": "2026-09-16T12:00:00Z", "intervalSeconds": 1, "target": { "url": "https://example.com/callback", "method": "example", "kind": "example", "payload": { "example": "value" } }, "state": "SCHEDULE_STATUS_ACTIVE", "retryPolicy": { "maxAttempts": 1, "initialBackoffMs": 1, "maxBackoffMs": 1 }, "metadata": { "example": "value" }, "autoPauseThreshold": 1, "externalId": "example_123", "createdAt": "2026-09-16T12:00:00Z", "createdBySubject": "example", "updatedAt": "2026-09-16T12:00:00Z", "updatedBySubject": "example", "pausedAt": "2026-09-16T12:00:00Z", "pausedBySubject": "example", "pausedReason": "example", "resumedAt": "2026-09-16T12:00:00Z", "resumedBySubject": "example", "deletedAt": "2026-09-16T12:00:00Z", "deletedBySubject": "example", "lastTriggeredAt": "2026-09-16T12:00:00Z", "nextTriggerAt": "2026-09-16T12:00:00Z", "triggerCount": "1", "failureCount": "1", "consecutiveFailureCount": "1" }, "status": "200", "schemaName": "Schedule" }, { "id": "scheduled-jobs-deleteJob-request", "operationId": "deleteJob", "operationKey": "scheduled-jobs:deleteJob", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Replace scheduleId with the ID returned when the job was created.", "payload": { "scheduleId": "sched_a1b2c3d4e5f60718" }, "schemaName": "DeleteJobRequest" }, { "id": "scheduled-jobs-deleteJob-response", "operationId": "deleteJob", "operationKey": "scheduled-jobs:deleteJob", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "scheduleId": "sched_a1b2c3d4e5f60718" }, "status": "200", "schemaName": "DeleteJobResponse" }, { "id": "scheduled-jobs-deleteJobsForProject-request", "operationId": "deleteJobsForProject", "operationKey": "scheduled-jobs:deleteJobsForProject", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Delete all jobs in the authenticated project; this operation has no per-job selector.", "payload": {}, "schemaName": "DeleteJobsForProjectRequest" }, { "id": "scheduled-jobs-deleteJobsForProject-response", "operationId": "deleteJobsForProject", "operationKey": "scheduled-jobs:deleteJobsForProject", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "deletedCount": 1 }, "status": "200", "schemaName": "DeleteJobsForProjectResponse" }, { "id": "scheduled-jobs-deleteJobsForOwner-request", "operationId": "deleteJobsForOwner", "operationKey": "scheduled-jobs:deleteJobsForOwner", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Delete all jobs owned by the authenticated end user in the current project.", "payload": {}, "schemaName": "DeleteJobsForOwnerRequest" }, { "id": "scheduled-jobs-deleteJobsForOwner-response", "operationId": "deleteJobsForOwner", "operationKey": "scheduled-jobs:deleteJobsForOwner", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "deletedCount": 1 }, "status": "200", "schemaName": "DeleteJobsForOwnerResponse" }, { "id": "scheduled-jobs-listExecutions-request", "operationId": "listExecutions", "operationKey": "scheduled-jobs:listExecutions", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Replace scheduleId with the ID returned when the job was created.", "payload": { "scheduleId": "sched_a1b2c3d4e5f60718" }, "schemaName": "ListExecutionsRequest" }, { "id": "scheduled-jobs-listExecutions-response", "operationId": "listExecutions", "operationKey": "scheduled-jobs:listExecutions", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "executions": [ { "executionId": "1", "scheduleId": "sched_a1b2c3d4e5f60718", "tenantId": "example_123", "projectId": "example_123", "scheduledTime": "2026-09-16T12:00:00Z", "startedAt": "2026-09-16T12:00:00Z", "completedAt": "2026-09-16T12:00:00Z", "status": "EXECUTION_STATUS_COMPLETED", "httpStatus": 1, "attempt": 1, "durationMs": 1, "targetKind": "example", "error": "example", "riverJobId": "1", "responseBody": "example", "responseHeaders": {}, "responseTruncated": true, "responseSizeBytes": 1, "endReason": "example" } ], "nextPageToken": "example" }, "status": "200", "schemaName": "ListExecutionsResponse" }, { "id": "secrets-putSecret-request", "operationId": "putSecret", "operationKey": "secrets:putSecret", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Store an example-named provider credential; replace the placeholder with the value to store.", "payload": { "name": "travel-provider-api-key", "value": "replace-with-provider-api-key", "description": "API key for the travel provider" }, "schemaName": "PutSecretRequest" }, { "id": "secrets-putSecret-response", "operationId": "putSecret", "operationKey": "secrets:putSecret", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "metadata": { "name": "example", "projectId": "example_123", "description": "example", "labels": {}, "version": "1", "createdBy": "example", "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z" } }, "status": "200", "schemaName": "PutSecretResponse" }, { "id": "secrets-getSecretMetadata-request", "operationId": "getSecretMetadata", "operationKey": "secrets:getSecretMetadata", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Use the name of an existing secret in the authenticated project.", "payload": { "name": "travel-provider-api-key" }, "schemaName": "GetSecretMetadataRequest" }, { "id": "secrets-getSecretMetadata-response", "operationId": "getSecretMetadata", "operationKey": "secrets:getSecretMetadata", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "metadata": { "name": "example", "projectId": "example_123", "description": "example", "labels": {}, "version": "1", "createdBy": "example", "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z" } }, "status": "200", "schemaName": "GetSecretMetadataResponse" }, { "id": "secrets-listSecrets-request", "operationId": "listSecrets", "operationKey": "secrets:listSecrets", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "List the first page of secret metadata for the authenticated project.", "payload": { "page": 0, "pageSize": 20 }, "schemaName": "ListSecretsRequest" }, { "id": "secrets-listSecrets-response", "operationId": "listSecrets", "operationKey": "secrets:listSecrets", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "secrets": [ { "name": "example", "projectId": "example_123", "description": "example", "labels": {}, "version": "1", "createdBy": "example", "createdAt": "2026-09-16T12:00:00Z", "updatedAt": "2026-09-16T12:00:00Z" } ], "total": 1 }, "status": "200", "schemaName": "ListSecretsResponse" }, { "id": "secrets-deleteSecret-request", "operationId": "deleteSecret", "operationKey": "secrets:deleteSecret", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Use the name of an existing secret in the authenticated project.", "payload": { "name": "travel-provider-api-key" }, "schemaName": "DeleteSecretRequest" }, { "id": "secrets-deleteSecret-response", "operationId": "deleteSecret", "operationKey": "secrets:deleteSecret", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "deleted": true }, "status": "200", "schemaName": "DeleteSecretResponse" }, { "id": "storage-createFolder-request", "operationId": "createFolder", "operationKey": "storage:createFolder", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Create a reports folder in the authenticated user’s storage namespace.", "payload": { "folderPath": "reports" }, "schemaName": "CreateFolderRequest" }, { "id": "storage-createFolder-response", "operationId": "createFolder", "operationKey": "storage:createFolder", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "folder": { "folderId": "example_123", "name": "example", "path": "documents/example.txt", "parentPath": "documents/example.txt", "createdAt": "example", "modifiedAt": "example", "metadata": {}, "fileCount": 1, "subfolderCount": 1, "totalSizeBytes": "1" }, "created": true }, "status": "200", "schemaName": "CreateFolderResponse" }, { "id": "storage-deleteFolder-request", "operationId": "deleteFolder", "operationKey": "storage:deleteFolder", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Delete the selected empty folder; recursive deletion is not requested.", "payload": { "folderPath": "reports", "recursive": false }, "schemaName": "DeleteFolderRequest" }, { "id": "storage-deleteFolder-response", "operationId": "deleteFolder", "operationKey": "storage:deleteFolder", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "deleted": true, "filesDeleted": 1, "foldersDeleted": 1 }, "status": "200", "schemaName": "DeleteFolderResponse" }, { "id": "storage-listFiles-request", "operationId": "listFiles", "operationKey": "storage:listFiles", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "List a bounded page of files from the reports folder.", "payload": { "folderPath": "reports", "pageSize": 20 }, "schemaName": "ListFilesRequest" }, { "id": "storage-listFiles-response", "operationId": "listFiles", "operationKey": "storage:listFiles", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "files": [ { "fileId": "example_123", "name": "example", "path": "documents/example.txt", "folderPath": "documents/example.txt", "sizeBytes": "1", "contentType": "Example text", "uploadedAt": "example", "modifiedAt": "example", "metadata": {}, "tags": [ "example" ], "description": "example", "storageRef": { "bucket": "example", "key": "example_123", "provider": "STORAGE_PROVIDER_GCS" }, "checksum": "example", "version": 1 } ], "folders": [ { "folderId": "example_123", "name": "example", "path": "documents/example.txt", "parentPath": "documents/example.txt", "createdAt": "example", "modifiedAt": "example", "metadata": {}, "fileCount": 1, "subfolderCount": 1, "totalSizeBytes": "1" } ], "nextPageToken": "example", "totalCount": 1 }, "status": "200", "schemaName": "ListFilesResponse" }, { "id": "storage-uploadFile-request", "operationId": "uploadFile", "operationKey": "storage:uploadFile", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Upload the base64 encoding of Hello followed by a newline.", "payload": { "folderPath": "reports", "fileName": "welcome.txt", "content": "SGVsbG8K", "contentType": "text/plain" }, "schemaName": "UploadFileRequest" }, { "id": "storage-uploadFile-response", "operationId": "uploadFile", "operationKey": "storage:uploadFile", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "file": { "fileId": "example_123", "name": "example", "path": "documents/example.txt", "folderPath": "documents/example.txt", "sizeBytes": "1", "contentType": "Example text", "uploadedAt": "example", "modifiedAt": "example", "metadata": {}, "tags": [ "example" ], "description": "example", "storageRef": { "bucket": "example", "key": "example_123", "provider": "STORAGE_PROVIDER_GCS" }, "checksum": "example", "version": 1 }, "uploaded": true }, "status": "200", "schemaName": "UploadFileResponse" }, { "id": "storage-deleteFile-request", "operationId": "deleteFile", "operationKey": "storage:deleteFile", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Replace fileId with an existing file returned by upload or listing.", "payload": { "fileId": "0123456789abcdef0123456789abcdef" }, "schemaName": "DeleteFileRequest" }, { "id": "storage-deleteFile-response", "operationId": "deleteFile", "operationKey": "storage:deleteFile", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "deleted": true, "spaceFreedBytes": "1" }, "status": "200", "schemaName": "DeleteFileResponse" }, { "id": "storage-moveFile-request", "operationId": "moveFile", "operationKey": "storage:moveFile", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Move an existing file to the archive folder and rename it.", "payload": { "fileId": "0123456789abcdef0123456789abcdef", "destinationFolder": "archive", "newName": "welcome-archived.txt" }, "schemaName": "MoveFileRequest" }, { "id": "storage-moveFile-response", "operationId": "moveFile", "operationKey": "storage:moveFile", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "file": { "fileId": "example_123", "name": "example", "path": "documents/example.txt", "folderPath": "documents/example.txt", "sizeBytes": "1", "contentType": "Example text", "uploadedAt": "example", "modifiedAt": "example", "metadata": {}, "tags": [ "example" ], "description": "example", "storageRef": { "bucket": "example", "key": "example_123", "provider": "STORAGE_PROVIDER_GCS" }, "checksum": "example", "version": 1 }, "moved": true }, "status": "200", "schemaName": "MoveFileResponse" }, { "id": "storage-searchFiles-request", "operationId": "searchFiles", "operationKey": "storage:searchFiles", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Find matching files within the authenticated user’s storage namespace.", "payload": { "query": "welcome", "maxResults": 20 }, "schemaName": "SearchFilesRequest" }, { "id": "storage-searchFiles-response", "operationId": "searchFiles", "operationKey": "storage:searchFiles", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "files": [ { "fileId": "example_123", "name": "example", "path": "documents/example.txt", "folderPath": "documents/example.txt", "sizeBytes": "1", "contentType": "Example text", "uploadedAt": "example", "modifiedAt": "example", "metadata": {}, "tags": [ "example" ], "description": "example", "storageRef": { "bucket": "example", "key": "example_123", "provider": "STORAGE_PROVIDER_GCS" }, "checksum": "example", "version": 1 } ], "totalMatches": 1 }, "status": "200", "schemaName": "SearchFilesResponse" }, { "id": "storage-getFileMetadata-request", "operationId": "getFileMetadata", "operationKey": "storage:getFileMetadata", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Read metadata for an existing file returned by upload or listing.", "payload": { "fileId": "0123456789abcdef0123456789abcdef" }, "schemaName": "GetFileMetadataRequest" }, { "id": "storage-getFileMetadata-response", "operationId": "getFileMetadata", "operationKey": "storage:getFileMetadata", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "file": { "fileId": "example_123", "name": "example", "path": "documents/example.txt", "folderPath": "documents/example.txt", "sizeBytes": "1", "contentType": "Example text", "uploadedAt": "example", "modifiedAt": "example", "metadata": {}, "tags": [ "example" ], "description": "example", "storageRef": { "bucket": "example", "key": "example_123", "provider": "STORAGE_PROVIDER_GCS" }, "checksum": "example", "version": 1 } }, "status": "200", "schemaName": "GetFileMetadataResponse" }, { "id": "storage-updateFileMetadata-request", "operationId": "updateFileMetadata", "operationKey": "storage:updateFileMetadata", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Set descriptive metadata on an existing file.", "payload": { "fileId": "0123456789abcdef0123456789abcdef", "description": "Welcome message", "tags": [ "onboarding" ], "metadata": { "category": "help" } }, "schemaName": "UpdateFileMetadataRequest" }, { "id": "storage-updateFileMetadata-response", "operationId": "updateFileMetadata", "operationKey": "storage:updateFileMetadata", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "file": { "fileId": "example_123", "name": "example", "path": "documents/example.txt", "folderPath": "documents/example.txt", "sizeBytes": "1", "contentType": "Example text", "uploadedAt": "example", "modifiedAt": "example", "metadata": {}, "tags": [ "example" ], "description": "example", "storageRef": { "bucket": "example", "key": "example_123", "provider": "STORAGE_PROVIDER_GCS" }, "checksum": "example", "version": 1 }, "updated": true }, "status": "200", "schemaName": "UpdateFileMetadataResponse" }, { "id": "storage-generateUploadUrl-request", "operationId": "generateUploadUrl", "operationKey": "storage:generateUploadUrl", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Request a signed upload for the six bytes Hello plus newline; send the returned required headers during upload.", "payload": { "folderPath": "reports", "fileName": "welcome.txt", "contentType": "text/plain", "sizeBytes": "6", "expiresSeconds": 900 }, "schemaName": "GenerateUploadUrlRequest" }, { "id": "storage-generateUploadUrl-response", "operationId": "generateUploadUrl", "operationKey": "storage:generateUploadUrl", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "url": "https://example.com/resource", "fileId": "example_123", "fullPath": "documents/example.txt", "requiredHeaders": {} }, "status": "200", "schemaName": "GenerateUploadUrlResponse" }, { "id": "storage-registerUploadedFile-request", "operationId": "registerUploadedFile", "operationKey": "storage:registerUploadedFile", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "After uploading, use the fileId returned by generate-upload-url and the same folderPath and fileName.", "payload": { "fileId": "0123456789abcdef0123456789abcdef", "folderPath": "reports", "fileName": "welcome.txt" }, "schemaName": "RegisterUploadedFileRequest" }, { "id": "storage-registerUploadedFile-response", "operationId": "registerUploadedFile", "operationKey": "storage:registerUploadedFile", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "file": { "fileId": "example_123", "name": "example", "path": "documents/example.txt", "folderPath": "documents/example.txt", "sizeBytes": "1", "contentType": "Example text", "uploadedAt": "example", "modifiedAt": "example", "metadata": {}, "tags": [ "example" ], "description": "example", "storageRef": { "bucket": "example", "key": "example_123", "provider": "STORAGE_PROVIDER_GCS" }, "checksum": "example", "version": 1 }, "registered": true }, "status": "200", "schemaName": "RegisterUploadedFileResponse" }, { "id": "storage-generateDownloadUrl-request", "operationId": "generateDownloadUrl", "operationKey": "storage:generateDownloadUrl", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Request a short-lived download URL for an existing file.", "payload": { "fileId": "0123456789abcdef0123456789abcdef", "expiresSeconds": 900 }, "schemaName": "GenerateDownloadUrlRequest" }, { "id": "storage-generateDownloadUrl-response", "operationId": "generateDownloadUrl", "operationKey": "storage:generateDownloadUrl", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "url": "https://example.com/resource", "file": { "fileId": "example_123", "name": "example", "path": "documents/example.txt", "folderPath": "documents/example.txt", "sizeBytes": "1", "contentType": "Example text", "uploadedAt": "example", "modifiedAt": "example", "metadata": {}, "tags": [ "example" ], "description": "example", "storageRef": { "bucket": "example", "key": "example_123", "provider": "STORAGE_PROVIDER_GCS" }, "checksum": "example", "version": 1 } }, "status": "200", "schemaName": "GenerateDownloadUrlResponse" }, { "id": "storage-batchGenerateDownloadUrls-request", "operationId": "batchGenerateDownloadUrls", "operationKey": "storage:batchGenerateDownloadUrls", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Resolve existing file IDs together; inspect each result separately.", "payload": { "fileIds": [ "0123456789abcdef0123456789abcdef" ], "expiresSeconds": 900 }, "schemaName": "BatchGenerateDownloadUrlsRequest" }, { "id": "storage-batchGenerateDownloadUrls-response", "operationId": "batchGenerateDownloadUrls", "operationKey": "storage:batchGenerateDownloadUrls", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "results": [ { "fileId": "example_123", "url": "https://example.com/resource", "success": true, "error": "example", "contentType": "Example text" } ] }, "status": "200", "schemaName": "BatchGenerateDownloadUrlsResponse" }, { "id": "storage-getStorageQuota-request", "operationId": "getStorageQuota", "operationKey": "storage:getStorageQuota", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Read quota and usage for the authenticated user’s storage namespace.", "payload": {}, "schemaName": "GetStorageQuotaRequest" }, { "id": "storage-getStorageQuota-response", "operationId": "getStorageQuota", "operationKey": "storage:getStorageQuota", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "usedBytes": "1", "quotaBytes": "1", "fileCount": 1, "folderCount": 1, "usagePercentage": 1 }, "status": "200", "schemaName": "GetStorageQuotaResponse" }, { "id": "storage-getState-request", "operationId": "getState", "operationKey": "storage:getState", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Read the authenticated user’s storage state; no file or folder selector is needed.", "payload": {}, "schemaName": "GetStateRequest" }, { "id": "storage-getState-response", "operationId": "getState", "operationKey": "storage:getState", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "state": { "userId": "example_123", "folders": {}, "files": {}, "totalSizeBytes": "1", "quotaBytes": "1", "totalFileCount": 1, "totalFolderCount": 1, "createdAt": "example", "lastModified": "example" } }, "status": "200", "schemaName": "GetStateResponse" }, { "id": "webhooks-createWebhookEndpoint-request", "operationId": "createWebhookEndpoint", "operationKey": "webhooks:createWebhookEndpoint", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Create a receiver for generation completion; replace the URL with your verified receiver.", "payload": { "name": "Generation events", "url": "https://api.example.com/hooks/travila", "eventTypes": [ "llm.generation_completed" ] }, "schemaName": "CreateWebhookEndpointRequest" }, { "id": "webhooks-createWebhookEndpoint-response", "operationId": "createWebhookEndpoint", "operationKey": "webhooks:createWebhookEndpoint", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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" } }, "status": "200", "schemaName": "CreateWebhookEndpointResponse" }, { "id": "webhooks-listWebhookEndpoints-request", "operationId": "listWebhookEndpoints", "operationKey": "webhooks:listWebhookEndpoints", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "List endpoints in the authenticated scope with default paging.", "payload": {}, "schemaName": "ListWebhookEndpointsRequest" }, { "id": "webhooks-listWebhookEndpoints-response", "operationId": "listWebhookEndpoints", "operationKey": "webhooks:listWebhookEndpoints", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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 } }, "status": "200", "schemaName": "ListWebhookEndpointsResponse" }, { "id": "webhooks-updateWebhookEndpoint-request", "operationId": "updateWebhookEndpoint", "operationKey": "webhooks:updateWebhookEndpoint", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Update an existing endpoint after verifying the replacement receiver.", "payload": { "endpointId": "ep_abc123", "url": "https://api.example.com/hooks/travila-v2" }, "schemaName": "UpdateWebhookEndpointRequest" }, { "id": "webhooks-updateWebhookEndpoint-response", "operationId": "updateWebhookEndpoint", "operationKey": "webhooks:updateWebhookEndpoint", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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" } }, "status": "200", "schemaName": "UpdateWebhookEndpointResponse" }, { "id": "webhooks-deleteWebhookEndpoint-request", "operationId": "deleteWebhookEndpoint", "operationKey": "webhooks:deleteWebhookEndpoint", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Use an existing endpointId when retiring a receiver.", "payload": { "endpointId": "ep_abc123" }, "schemaName": "DeleteWebhookEndpointRequest" }, { "id": "webhooks-deleteWebhookEndpoint-response", "operationId": "deleteWebhookEndpoint", "operationKey": "webhooks:deleteWebhookEndpoint", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": {}, "status": "200", "schemaName": "DeleteWebhookEndpointResponse" }, { "id": "webhooks-createWebhookSubscription-request", "operationId": "createWebhookSubscription", "operationKey": "webhooks:createWebhookSubscription", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Subscribe an existing endpoint that does not already have a live subscription.", "payload": { "endpointId": "ep_abc123", "eventTypes": [ "llm.generation_completed" ] }, "schemaName": "CreateWebhookSubscriptionRequest" }, { "id": "webhooks-createWebhookSubscription-response", "operationId": "createWebhookSubscription", "operationKey": "webhooks:createWebhookSubscription", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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" } }, "status": "200", "schemaName": "CreateWebhookSubscriptionResponse" }, { "id": "webhooks-listWebhookSubscriptions-request", "operationId": "listWebhookSubscriptions", "operationKey": "webhooks:listWebhookSubscriptions", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "List subscriptions for an existing endpoint.", "payload": { "endpointId": "ep_abc123", "page": 1, "perPage": 25 }, "schemaName": "ListWebhookSubscriptionsRequest" }, { "id": "webhooks-listWebhookSubscriptions-response", "operationId": "listWebhookSubscriptions", "operationKey": "webhooks:listWebhookSubscriptions", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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 } }, "status": "200", "schemaName": "ListWebhookSubscriptionsResponse" }, { "id": "webhooks-deleteWebhookSubscription-request", "operationId": "deleteWebhookSubscription", "operationKey": "webhooks:deleteWebhookSubscription", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "subscriptionId": "example_123" }, "schemaName": "DeleteWebhookSubscriptionRequest" }, { "id": "webhooks-deleteWebhookSubscription-response", "operationId": "deleteWebhookSubscription", "operationKey": "webhooks:deleteWebhookSubscription", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": {}, "status": "200", "schemaName": "DeleteWebhookSubscriptionResponse" }, { "id": "webhooks-listWebhookDeliveries-request", "operationId": "listWebhookDeliveries", "operationKey": "webhooks:listWebhookDeliveries", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Inspect a bounded page of deliveries for an existing endpoint.", "payload": { "endpointId": "ep_abc123", "page": 1, "perPage": 25 }, "schemaName": "ListWebhookDeliveriesRequest" }, { "id": "webhooks-listWebhookDeliveries-response", "operationId": "listWebhookDeliveries", "operationKey": "webhooks:listWebhookDeliveries", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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 } }, "status": "200", "schemaName": "ListWebhookDeliveriesResponse" }, { "id": "webhooks-retryWebhookDelivery-request", "operationId": "retryWebhookDelivery", "operationKey": "webhooks:retryWebhookDelivery", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.", "payload": { "deliveryId": "example_123" }, "schemaName": "RetryWebhookDeliveryRequest" }, { "id": "webhooks-retryWebhookDelivery-response", "operationId": "retryWebhookDelivery", "operationKey": "webhooks:retryWebhookDelivery", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response shape; omitted default fields and actual outcomes depend on the operation.", "payload": { "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" } }, "status": "200", "schemaName": "RetryWebhookDeliveryResponse" }, { "id": "cookbook-core-platform-files-data-files-01-request", "operationId": "generateUploadUrl", "operationKey": "storage:generateUploadUrl", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Upload and confirm the recording. Replace example resource identifiers with your own authorized values.", "payload": { "folderPath": "/media", "fileName": "video.mp4", "contentType": "video/mp4", "sizeBytes": 52428800, "expiresSeconds": 3600 }, "schemaName": "GenerateUploadUrlRequest" }, { "id": "cookbook-core-platform-files-data-files-03-request", "operationId": "registerUploadedFile", "operationKey": "storage:registerUploadedFile", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Upload and confirm the recording. Replace example resource identifiers with your own authorized values.", "payload": { "fileId": "a1b2c3d4e5f60718293a4b5c6d7e8f90", "folderPath": "/media", "fileName": "video.mp4" }, "schemaName": "RegisterUploadedFileRequest" }, { "id": "cookbook-core-platform-files-data-files-04-request", "operationId": "generateDownloadUrl", "operationKey": "storage:generateDownloadUrl", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Let the customer reopen the attachment. Replace example resource identifiers with your own authorized values.", "payload": { "fileId": "a1b2c3d4e5f60718293a4b5c6d7e8f90", "expiresSeconds": 3600 }, "schemaName": "GenerateDownloadUrlRequest" }, { "id": "cookbook-core-platform-files-data-files-05-request", "operationId": "batchGenerateDownloadUrls", "operationKey": "storage:batchGenerateDownloadUrls", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Show several attachments on the case. Replace example resource identifiers with your own authorized values.", "payload": { "fileIds": [ "a1b2c3d4e5f60718293a4b5c6d7e8f90", "b2c3d4e5f60718293a4b5c6d7e8f901a" ], "expiresSeconds": 3600 }, "schemaName": "BatchGenerateDownloadUrlsRequest" }, { "id": "cookbook-core-platform-files-data-folders-01-request", "operationId": "createFolder", "operationKey": "storage:createFolder", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Prepare a folder and add the first document. Replace example resource identifiers with your own authorized values.", "payload": { "folderPath": "/documents/work" }, "schemaName": "CreateFolderRequest" }, { "id": "cookbook-core-platform-files-data-folders-02-request", "operationId": "deleteFolder", "operationKey": "storage:deleteFolder", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Remove the project’s documents when the customer chooses. Replace example resource identifiers with your own authorized values.", "payload": { "folderPath": "/documents/work", "recursive": true }, "schemaName": "DeleteFolderRequest" }, { "id": "cookbook-core-platform-files-data-managing-01-request", "operationId": "listFiles", "operationKey": "storage:listFiles", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Populate the folder view. Replace example resource identifiers with your own authorized values.", "payload": { "folderPath": "/documents", "recursive": true, "pageSize": 20 }, "schemaName": "ListFilesRequest" }, { "id": "cookbook-core-platform-files-data-managing-02-request", "operationId": "searchFiles", "operationKey": "storage:searchFiles", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Find a report when its folder is unknown. Replace example resource identifiers with your own authorized values.", "payload": { "query": "quarterly report", "maxResults": 10, "filter": { "extensions": [ ".pdf" ], "tags": [ "finance" ], "minSizeBytes": 1024, "maxSizeBytes": 52428800, "nameContains": "Q1" } }, "schemaName": "SearchFilesRequest" }, { "id": "cookbook-core-platform-files-data-managing-03-request", "operationId": "getFileMetadata", "operationKey": "storage:getFileMetadata", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Open the selected document’s details. Replace example resource identifiers with your own authorized values.", "payload": { "fileId": "a1b2c3d4e5f60718293a4b5c6d7e8f90" }, "schemaName": "GetFileMetadataRequest" }, { "id": "cookbook-core-platform-files-data-managing-04-request", "operationId": "updateFileMetadata", "operationKey": "storage:updateFileMetadata", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Save the review labels without erasing other labels. Replace example resource identifiers with your own authorized values.", "payload": { "fileId": "a1b2c3d4e5f60718293a4b5c6d7e8f90", "metadata": { "reviewed": "true", "category": "internal" }, "tags": [ "notes", "reviewed" ], "description": "Meeting notes from Q1 planning" }, "schemaName": "UpdateFileMetadataRequest" }, { "id": "cookbook-core-platform-files-data-managing-05-request", "operationId": "moveFile", "operationKey": "storage:moveFile", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Archive a completed document. Replace example resource identifiers with your own authorized values.", "payload": { "fileId": "a1b2c3d4e5f60718293a4b5c6d7e8f90", "destinationFolder": "/archive", "newName": "notes-2025-q1.txt" }, "schemaName": "MoveFileRequest" }, { "id": "cookbook-core-platform-files-data-managing-06-request", "operationId": "deleteFile", "operationKey": "storage:deleteFile", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Delete a document the customer no longer needs. Replace example resource identifiers with your own authorized values.", "payload": { "fileId": "a1b2c3d4e5f60718293a4b5c6d7e8f90" }, "schemaName": "DeleteFileRequest" }, { "id": "cookbook-core-platform-identity-access-end-users-02-request", "operationId": "updateLocale", "operationKey": "end-users:updateLocale", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 2. Save the user’s preferred language. Replace example resource identifiers with your own authorized values.", "payload": { "locale": "es-MX" }, "schemaName": "UpdateLocaleRequest" }, { "id": "cookbook-core-platform-identity-access-end-users-03-request", "operationId": "updateDefaultGenerationConfig", "operationKey": "end-users:updateDefaultGenerationConfig", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 3. Offer supported model and response preferences. Replace example resource identifiers with your own authorized values.", "payload": { "config": { "model": "google/gemini-3.6-flash", "temperature": 0.4, "maxOutputTokens": 2048, "languagePreference": "es" } }, "schemaName": "EndUserUpdateDefaultGenerationConfigRequest" }, { "id": "cookbook-core-platform-identity-access-end-users-04-request", "operationId": "updateMetadata", "operationKey": "end-users:updateMetadata", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Variant: remember a display preference. Replace example resource identifiers with your own authorized values.", "payload": { "metadata": { "preferredView": "compact", "dismissedWelcome": "true" } }, "schemaName": "UpdateMetadataRequest" }, { "id": "cookbook-core-platform-identity-access-end-users-05-request", "operationId": "updateLocation", "operationKey": "end-users:updateLocation", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Variant: use location for local-time context. Replace example resource identifiers with your own authorized values.", "payload": { "latitude": 51.5072, "longitude": -0.1276 }, "schemaName": "UpdateLocationRequest" }, { "id": "cookbook-core-platform-identity-access-scopes-permissions-01-request", "operationId": "sendMessage", "operationKey": "conversations:sendMessage", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for The `users:impersonate` scope and `X-On-Behalf-Of`. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "conv_abc", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Hello" } ] } }, "schemaName": "SendMessageRequest" }, { "id": "cookbook-core-platform-scheduling-build-scheduled-agents-01-request", "operationId": "sendMessageSync", "operationKey": "conversations:sendMessageSync", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 3: Drive an agent turn from the callback. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "b81d5345-c1f9-4fb9-b558-a6327c75b842", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Generate the daily briefing." } ] } }, "schemaName": "SendMessageSyncRequest" }, { "id": "cookbook-core-platform-scheduling-build-scheduled-agents-02-request", "operationId": "createJob", "operationKey": "scheduled-jobs:createJob", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 4: Create the schedule. Replace example resource identifiers with your own authorized values.", "payload": { "name": "Daily agent briefing", "scheduleType": "SCHEDULE_TYPE_CRON", "cronExpression": "0 9 * * 1-5", "timezone": "America/New_York", "target": { "url": "https://api.example.com/hooks/scheduled-agent", "kind": "agent-briefing", "payload": { "task": "daily-briefing" } } }, "schemaName": "CreateJobRequest" }, { "id": "cookbook-core-platform-scheduling-build-scheduled-agents-03-request", "operationId": "createWebhookEndpoint", "operationKey": "webhooks:createWebhookEndpoint", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 5: Subscribe to the results webhook (Optional). Replace example resource identifiers with your own authorized values.", "payload": { "name": "scheduled-agent-results", "url": "https://api.example.com/hooks/agent-results", "description": "Receives assistant messages from scheduled agent runs", "eventTypes": [ "llm.message_published" ] }, "schemaName": "CreateWebhookEndpointRequest" }, { "id": "cookbook-core-platform-scheduling-creating-02-request", "operationId": "createJob", "operationKey": "scheduled-jobs:createJob", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Variant: remind the user once at a chosen time. Replace example resource identifiers with your own authorized values.", "payload": { "name": "Send welcome email", "scheduleType": "SCHEDULE_TYPE_ONCE", "scheduledAt": "2026-10-10T14:00:00Z", "target": { "url": "https://your-api.example.com/jobs/welcome", "kind": "notification", "payload": { "user_id": "usr_abc123" } } }, "schemaName": "CreateJobRequest" }, { "id": "cookbook-core-platform-scheduling-creating-03-request", "operationId": "createJob", "operationKey": "scheduled-jobs:createJob", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Variant: refresh application data every few minutes. Replace example resource identifiers with your own authorized values.", "payload": { "name": "Sync cache", "scheduleType": "SCHEDULE_TYPE_RECURRING_INTERVAL", "intervalSeconds": 300, "target": { "url": "https://your-api.example.com/jobs/cache-sync", "kind": "maintenance" } }, "schemaName": "CreateJobRequest" }, { "id": "cookbook-core-platform-scheduling-execution-01-request", "operationId": "listExecutions", "operationKey": "scheduled-jobs:listExecutions", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Find where the missing digest stopped. Replace example resource identifiers with your own authorized values.", "payload": { "scheduleId": "sched_a1b2c3d4e5f60718", "pageSize": 20, "statusFilter": "EXECUTION_STATUS_FAILED" }, "schemaName": "ListExecutionsRequest" }, { "id": "cookbook-core-platform-scheduling-execution-02-request", "operationId": "createJob", "operationKey": "scheduled-jobs:createJob", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Recover a temporary receiver failure. Replace example resource identifiers with your own authorized values.", "payload": { "name": "Critical alert", "scheduleType": "SCHEDULE_TYPE_CRON", "cronExpression": "*/5 * * * *", "target": { "url": "https://your-api.example.com/jobs/alert", "kind": "alert" }, "retryPolicy": { "maxAttempts": 3, "initialBackoffMs": 1000, "maxBackoffMs": 10000 } }, "schemaName": "CreateJobRequest" }, { "id": "cookbook-core-platform-scheduling-managing-01-request", "operationId": "getJob", "operationKey": "scheduled-jobs:getJob", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 1. Load the reminder being changed. Replace example resource identifiers with your own authorized values.", "payload": { "scheduleId": "sched_a1b2c3d4e5f60718" }, "schemaName": "GetJobRequest" }, { "id": "cookbook-core-platform-scheduling-managing-02-request", "operationId": "listJobs", "operationKey": "scheduled-jobs:listJobs", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Variant: show the user’s reminder list. Replace example resource identifiers with your own authorized values.", "payload": { "pageSize": 20, "stateFilter": "SCHEDULE_STATUS_ACTIVE" }, "schemaName": "ListJobsRequest" }, { "id": "cookbook-core-platform-scheduling-managing-03-request", "operationId": "updateJob", "operationKey": "scheduled-jobs:updateJob", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 2. Save a new delivery time. Replace example resource identifiers with your own authorized values.", "payload": { "scheduleId": "sched_a1b2c3d4e5f60718", "cronExpression": "0 10 * * 1-5" }, "schemaName": "UpdateJobRequest" }, { "id": "cookbook-core-platform-scheduling-managing-04-1-request", "operationId": "pauseJob", "operationKey": "scheduled-jobs:pauseJob", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 3. Let the user take a temporary break. Replace example resource identifiers with your own authorized values.", "payload": { "scheduleId": "sched_a1b2c3d4e5f60718", "reason": "Target service under maintenance" }, "schemaName": "PauseJobRequest" }, { "id": "cookbook-core-platform-scheduling-managing-04-2-request", "operationId": "resumeJob", "operationKey": "scheduled-jobs:resumeJob", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 3. Let the user take a temporary break. Replace example resource identifiers with your own authorized values.", "payload": { "scheduleId": "sched_a1b2c3d4e5f60718" }, "schemaName": "ResumeJobRequest" }, { "id": "cookbook-core-platform-scheduling-managing-05-request", "operationId": "deleteJob", "operationKey": "scheduled-jobs:deleteJob", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 4. Remove this reminder. Replace example resource identifiers with your own authorized values.", "payload": { "scheduleId": "sched_a1b2c3d4e5f60718" }, "schemaName": "DeleteJobRequest" }, { "id": "cookbook-core-platform-scheduling-managing-08-request", "operationId": "createJob", "operationKey": "scheduled-jobs:createJob", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Variant: use your application’s reminder identifier. Replace example resource identifiers with your own authorized values.", "payload": { "name": "Daily digest", "scheduleType": "SCHEDULE_TYPE_CRON", "cronExpression": "0 9 * * 1-5", "externalId": "user-42-daily-digest", "target": { "url": "https://your-api.example.com/jobs/daily-digest", "kind": "digest" } }, "schemaName": "CreateJobRequest" }, { "id": "cookbook-core-platform-scheduling-managing-09-request", "operationId": "getJob", "operationKey": "scheduled-jobs:getJob", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Variant: use your application’s reminder identifier. Replace example resource identifiers with your own authorized values.", "payload": { "externalId": "user-42-daily-digest" }, "schemaName": "GetJobRequest" }, { "id": "cookbook-developer-experience-local-tooling-testing-01-request", "operationId": "sendMessageSync", "operationKey": "conversations:sendMessageSync", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Verify that an in-app action returns control to the conversation. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "b81d5345-c1f9-4fb9-b558-a6327c75b842", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Navigate to my profile." } ] } }, "schemaName": "SendMessageSyncRequest" }, { "id": "cookbook-developer-experience-local-tooling-testing-02-request", "operationId": "submitClientToolResultsSync", "operationKey": "conversations:submitClientToolResultsSync", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Verify that an in-app action returns control to the conversation. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "b81d5345-c1f9-4fb9-b558-a6327c75b842", "clientToolCursor": 1, "results": [ { "toolCallId": "call_abc123", "toolName": "navigate_to", "resultJson": { "navigated_to": "/profile" } } ] }, "schemaName": "SubmitClientToolResultsSyncRequest" }, { "id": "cookbook-insights-evaluation-datasets-and-runs-01-request", "operationId": "createDataset", "operationKey": "evals:createDataset", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 1. Create the dataset. Replace example resource identifiers with your own authorized values.", "payload": { "name": "support-assistant-regressions", "description": "Turns we do not want to break" }, "schemaName": "CreateDatasetRequest" }, { "id": "cookbook-insights-evaluation-datasets-and-runs-02-request", "operationId": "addDatasetItem", "operationKey": "evals:addDatasetItem", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 2. Save the input needed to reproduce the problem. Replace example resource identifiers with your own authorized values.", "payload": { "datasetId": "support-assistant-regressions", "conversationId": "conv_123", "sourceUserMessageId": "msg_abc", "inputJson": "{\"question\":\"What is the return window?\"}" }, "schemaName": "AddDatasetItemRequest" }, { "id": "cookbook-insights-evaluation-datasets-and-runs-03-request", "operationId": "listDatasetItems", "operationKey": "evals:listDatasetItems", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 3. Define what an acceptable answer must do. Replace example resource identifiers with your own authorized values.", "payload": { "datasetName": "support-assistant-regressions", "onlyMissingExpectedOutput": true }, "schemaName": "ListDatasetItemsRequest" }, { "id": "cookbook-insights-evaluation-datasets-and-runs-04-request", "operationId": "updateDatasetItem", "operationKey": "evals:updateDatasetItem", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 3. Define what an acceptable answer must do. Replace example resource identifiers with your own authorized values.", "payload": { "itemId": "…", "datasetId": "support-assistant-regressions", "expectedOutputJson": "{\"answer\": \"…\"}" }, "schemaName": "UpdateDatasetItemRequest" }, { "id": "cookbook-insights-evaluation-datasets-and-runs-05-request", "operationId": "recordDatasetRun", "operationKey": "evals:recordDatasetRun", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 4. Run both configurations and retain their outcomes. Replace example resource identifiers with your own authorized values.", "payload": { "datasetId": "support-assistant-regressions", "runName": "nightly-2026-08-14", "profileRevisionHash": "a1b2c3…", "items": [ { "datasetItemId": "di_001", "traceId": "trc_a1b2c3" } ] }, "schemaName": "RecordDatasetRunRequest" }, { "id": "cookbook-insights-evaluation-datasets-and-runs-06-request", "operationId": "listDatasetRuns", "operationKey": "evals:listDatasetRuns", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 5. Decide whether the change fixes the problem without regressions. Replace example resource identifiers with your own authorized values.", "payload": { "datasetName": "support-assistant-regressions", "pageSize": 25 }, "schemaName": "ListDatasetRunsRequest" }, { "id": "cookbook-insights-evaluation-datasets-and-runs-07-request", "operationId": "getDatasetRun", "operationKey": "evals:getDatasetRun", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 5. Decide whether the change fixes the problem without regressions. Replace example resource identifiers with your own authorized values.", "payload": { "datasetName": "support-assistant-regressions", "runName": "2026-08-12-candidate" }, "schemaName": "GetDatasetRunRequest" }, { "id": "cookbook-insights-evaluation-datasets-and-runs-08-request", "operationId": "listDatasets", "operationKey": "evals:listDatasets", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Browse the datasets. Replace example resource identifiers with your own authorized values.", "payload": { "page": 1, "pageSize": 25 }, "schemaName": "ListDatasetsRequest" }, { "id": "cookbook-insights-evaluation-message-feedback-01-request", "operationId": "rateMessage", "operationKey": "conversations:rateMessage", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Save the user’s judgment beside the reply. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "support-chat-001", "messageSequence": 8, "kind": "FEEDBACK_KIND_THUMB", "thumbUp": true }, "schemaName": "RateMessageRequest" }, { "id": "cookbook-insights-evaluation-message-feedback-02-request", "operationId": "deleteMessageRating", "operationKey": "conversations:deleteMessageRating", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Let the user remove their judgment. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "support-chat-001", "messageSequence": 8 }, "schemaName": "DeleteMessageRatingRequest" }, { "id": "cookbook-insights-evaluation-reading-01-request", "operationId": "listTraces", "operationKey": "evals:listTraces", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Find the reply the customer reported. Replace example resource identifiers with your own authorized values.", "payload": { "profileId": "nutrition_coach", "fromTime": "2026-08-01T00:00:00Z", "toTime": "2026-08-14T00:00:00Z", "pageSize": 25 }, "schemaName": "ListTracesRequest" }, { "id": "cookbook-insights-evaluation-reading-02-request", "operationId": "getTrace", "operationKey": "evals:getTrace", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Locate the slow or failed step. Replace example resource identifiers with your own authorized values.", "payload": { "conversationId": "conv_123", "sourceUserMessageId": "msg_abc" }, "schemaName": "GetTraceRequest" }, { "id": "cookbook-insights-evaluation-reading-03-request", "operationId": "listScores", "operationKey": "evals:listScores", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Read judgments about that same reply. Replace example resource identifiers with your own authorized values.", "payload": { "conversationId": "conv_123", "dataType": "SCORE_DATA_TYPE_NUMERIC", "pageSize": 50 }, "schemaName": "ListScoresRequest" }, { "id": "cookbook-insights-evaluation-reading-04-request", "operationId": "listObservations", "operationKey": "evals:listObservations", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Check whether the same tool keeps failing. Replace example resource identifiers with your own authorized values.", "payload": { "filters": [ { "column": "level", "operator": "=", "type": "EVAL_FILTER_TYPE_STRING", "stringValue": "ERROR" } ], "pageSize": 50 }, "schemaName": "ListObservationsRequest" }, { "id": "cookbook-insights-evaluation-review-01-request", "operationId": "createScoreConfig", "operationKey": "evals:createScoreConfig", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 1. Define the dimensions first. Replace example resource identifiers with your own authorized values.", "payload": { "name": "helpfulness", "dataType": "SCORE_DATA_TYPE_NUMERIC", "minValue": 1, "maxValue": 5 }, "schemaName": "CreateScoreConfigRequest" }, { "id": "cookbook-insights-evaluation-review-02-request", "operationId": "createAnnotationQueue", "operationKey": "evals:createAnnotationQueue", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 2. Queue what needs reviewing. Replace example resource identifiers with your own authorized values.", "payload": { "name": "weekly-qa", "scoreConfigIds": [ "cfg_helpfulness" ] }, "schemaName": "CreateAnnotationQueueRequest" }, { "id": "cookbook-insights-evaluation-review-03-request", "operationId": "enqueueForAnnotation", "operationKey": "evals:enqueueForAnnotation", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 2. Queue what needs reviewing. Replace example resource identifiers with your own authorized values.", "payload": { "queueId": "q_weekly", "targetType": "EVAL_TARGET_TYPE_TRACE", "targetId": "trc_a1b2c3" }, "schemaName": "EnqueueForAnnotationRequest" }, { "id": "cookbook-insights-evaluation-review-04-request", "operationId": "listAnnotationQueueItems", "operationKey": "evals:listAnnotationQueueItems", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Pull the worklist. Replace example resource identifiers with your own authorized values.", "payload": { "queueId": "q_weekly", "status": "ANNOTATION_QUEUE_ITEM_STATUS_PENDING", "page": 1, "pageSize": 20 }, "schemaName": "ListAnnotationQueueItemsRequest" }, { "id": "cookbook-insights-evaluation-review-05-request", "operationId": "recordScore", "operationKey": "evals:recordScore", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 3. Record the rating. Replace example resource identifiers with your own authorized values.", "payload": { "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." }, "schemaName": "RecordScoreRequest" }, { "id": "cookbook-insights-evaluation-review-06-request", "operationId": "createComment", "operationKey": "evals:createComment", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Save the explanation with the reviewed turn. Replace example resource identifiers with your own authorized values.", "payload": { "objectType": "COMMENT_OBJECT_TYPE_TRACE", "objectId": "trc_a1b2c3", "content": "Tool call returned stale data." }, "schemaName": "CreateCommentRequest" }, { "id": "cookbook-insights-evaluation-review-07-request", "operationId": "completeAnnotationQueueItem", "operationKey": "evals:completeAnnotationQueueItem", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 4. Complete the saved review. Replace example resource identifiers with your own authorized values.", "payload": { "queueId": "q_weekly", "itemId": "qi_001" }, "schemaName": "CompleteAnnotationQueueItemRequest" }, { "id": "cookbook-insights-evaluation-review-08-request", "operationId": "deleteScore", "operationKey": "evals:deleteScore", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Withdraw a rating. Replace example resource identifiers with your own authorized values.", "payload": { "scoreId": "scr_7788" }, "schemaName": "DeleteScoreRequest" }, { "id": "cookbook-integrations-tools-connections-connected-apps-01-request", "operationId": "pipedreamListApps", "operationKey": "connected-apps:pipedreamListApps", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Find Google Calendar in the catalog. Replace example resource identifiers with your own authorized values.", "payload": { "q": "cal", "sortKey": "APP_SORT_KEY_FEATURED_WEIGHT", "sortDirection": "SORT_DIRECTION_DESC", "limit": 20 }, "schemaName": "PipedreamListAppsRequest" }, { "id": "cookbook-integrations-tools-connections-connected-apps-02-request", "operationId": "pipedreamCreateConnectToken", "operationKey": "connected-apps:pipedreamCreateConnectToken", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Create the authorization link when the customer clicks Connect. Replace example resource identifiers with your own authorized values.", "payload": { "appSlug": "google_calendar", "successRedirectUrl": "https://app.example.com/integrations?ok=1", "errorRedirectUrl": "https://app.example.com/integrations?ok=0", "state": "picker-session-8f3a" }, "schemaName": "PipedreamCreateConnectTokenRequest" }, { "id": "cookbook-integrations-tools-connections-connected-apps-03-request", "operationId": "pipedreamListAccountsForCurrentUser", "operationKey": "connected-apps:pipedreamListAccountsForCurrentUser", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Confirm the account before showing Connected. Replace example resource identifiers with your own authorized values.", "payload": { "app": "google_calendar" }, "schemaName": "PipedreamListAccountsForCurrentUserRequest" }, { "id": "cookbook-integrations-tools-connections-connected-apps-04-request", "operationId": "createThread", "operationKey": "conversations:createThread", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 2. Give this conversation access to the calendar. Replace example resource identifiers with your own authorized values.", "payload": { "conversationSettings": { "mcpServers": [ { "serverId": "pipedream:google_calendar", "enabled": true } ] } }, "schemaName": "CreateThreadRequest" }, { "id": "cookbook-integrations-tools-connections-connected-apps-05-request", "operationId": "pipedreamDeleteAccountForCurrentUser", "operationKey": "connected-apps:pipedreamDeleteAccountForCurrentUser", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Disconnect the selected calendar. Replace example resource identifiers with your own authorized values.", "payload": { "accountId": "apn_kAHeAr9" }, "schemaName": "PipedreamDeleteAccountForCurrentUserRequest" }, { "id": "cookbook-integrations-tools-connections-custom-mcp-servers-01-request", "operationId": "putSecret", "operationKey": "secrets:putSecret", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 1. Store the Firecrawl credential. Replace example resource identifiers with your own authorized values.", "payload": { "name": "firecrawl-api-key", "value": "fc-your-token-here", "description": "Firecrawl bearer token", "labels": { "kind": "mcp-auth" } }, "schemaName": "PutSecretRequest" }, { "id": "cookbook-integrations-tools-connections-custom-mcp-servers-02-request", "operationId": "createCustomMcpServer", "operationKey": "mcp-servers:createCustomMcpServer", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 2. Register the service you want Travila to call. Replace example resource identifiers with your own authorized values.", "payload": { "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" } }, "schemaName": "CreateCustomMCPServerRequest" }, { "id": "cookbook-integrations-tools-connections-custom-mcp-servers-03-request", "operationId": "testCustomMcpServerConnection", "operationKey": "mcp-servers:testCustomMcpServerConnection", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 3. Check the saved connection and choose its tools. Replace example resource identifiers with your own authorized values.", "payload": { "serverId": "firecrawl" }, "schemaName": "TestCustomMCPServerConnectionRequest" }, { "id": "cookbook-integrations-tools-connections-custom-mcp-servers-04-request", "operationId": "mcpListTools", "operationKey": "conversations:mcpListTools", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Inspect the names before setting filters or approvals. Replace example resource identifiers with your own authorized values.", "payload": { "servers": [ { "serverId": "custom:firecrawl", "enabled": true } ] }, "schemaName": "MCPListToolsRequest" }, { "id": "cookbook-integrations-tools-connections-custom-mcp-servers-05-request", "operationId": "sendMessage", "operationKey": "conversations:sendMessage", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 4. Ask about the page in a conversation. Replace example resource identifiers with your own authorized values.", "payload": { "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 } ] }, "schemaName": "SendMessageRequest" }, { "id": "cookbook-integrations-tools-connections-custom-mcp-servers-06-request", "operationId": "putSecret", "operationKey": "secrets:putSecret", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Rotate the credential. Replace example resource identifiers with your own authorized values.", "payload": { "name": "firecrawl-api-key", "value": "fc-the-new-token" }, "schemaName": "PutSecretRequest" }, { "id": "cookbook-integrations-tools-connections-index-02-request", "operationId": "updateSettings", "operationKey": "conversations:updateSettings", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 2. Enable research for the conversation. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "thread_abc123", "settings": { "mcpServers": [ { "serverId": "built-in:tavily" } ] } }, "schemaName": "UpdateSettingsRequest" }, { "id": "cookbook-integrations-webhooks-deliveries-01-request", "operationId": "listWebhookDeliveries", "operationKey": "webhooks:listWebhookDeliveries", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 1. Find where the update stopped. Replace example resource identifiers with your own authorized values.", "payload": { "endpointId": "ep_abc123", "status": "DELIVERY_STATUS_FAILED", "createdAfter": "2026-08-01T00:00:00Z", "perPage": 50 }, "schemaName": "ListWebhookDeliveriesRequest" }, { "id": "cookbook-integrations-webhooks-deliveries-02-request", "operationId": "retryWebhookDelivery", "operationKey": "webhooks:retryWebhookDelivery", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 3. Replay the original eligible delivery. Replace example resource identifiers with your own authorized values.", "payload": { "deliveryId": "del_xyz789" }, "schemaName": "RetryWebhookDeliveryRequest" }, { "id": "cookbook-integrations-webhooks-endpoints-01-request", "operationId": "createWebhookEndpoint", "operationKey": "webhooks:createWebhookEndpoint", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 1. Register the receiver for completed runs. Replace example resource identifiers with your own authorized values.", "payload": { "name": "orders-service", "url": "https://api.example.com/hooks/travila", "description": "Order pipeline consumer", "eventTypes": [ "llm.generation_completed" ] }, "schemaName": "CreateWebhookEndpointRequest" }, { "id": "cookbook-integrations-webhooks-endpoints-02-request", "operationId": "listWebhookEndpoints", "operationKey": "webhooks:listWebhookEndpoints", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Save the signing secret. Replace example resource identifiers with your own authorized values.", "payload": { "page": 1, "perPage": 25 }, "schemaName": "ListWebhookEndpointsRequest" }, { "id": "cookbook-managed-agents-conversations-build-chat-assistant-02-request", "operationId": "createThread", "operationKey": "conversations:createThread", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 2: Start one support conversation. Replace example resource identifiers with your own authorized values.", "payload": { "title": "My First Thread" }, "schemaName": "CreateThreadRequest" }, { "id": "cookbook-managed-agents-conversations-build-chat-assistant-03-request", "operationId": "sendMessage", "operationKey": "conversations:sendMessage", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Send the message. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "b81d5345-c1f9-4fb9-b558-a6327c75b842", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "What can you help me with?" } ] } }, "schemaName": "SendMessageRequest" }, { "id": "cookbook-managed-agents-conversations-build-chat-assistant-04-request", "operationId": "getConversationState", "operationKey": "conversations:getConversationState", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Poll conversation state. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "b81d5345-c1f9-4fb9-b558-a6327c75b842" }, "schemaName": "GetConversationStateRequest" }, { "id": "cookbook-managed-agents-conversations-build-chat-assistant-05-request", "operationId": "registerPushDevice", "operationKey": "notifications:registerPushDevice", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Variant: bring the user back when a notification arrives. Replace example resource identifiers with your own authorized values.", "payload": { "fcmToken": "firebase-cloud-messaging-token", "platform": "PLATFORM_IOS", "deviceId": "device-unique-id" }, "schemaName": "RegisterPushDeviceRequest" }, { "id": "cookbook-managed-agents-conversations-build-chat-assistant-06-request", "operationId": "unregisterPushDevice", "operationKey": "notifications:unregisterPushDevice", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Variant: bring the user back when a notification arrives. Replace example resource identifiers with your own authorized values.", "payload": { "fcmToken": "firebase-cloud-messaging-token" }, "schemaName": "UnregisterPushDeviceRequest" }, { "id": "cookbook-managed-agents-conversations-configuration-01-request", "operationId": "updateDefaultGenerationConfig", "operationKey": "conversations:updateDefaultGenerationConfig", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 1: Set the model and answer length. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "support-chat-001", "defaultGenerationConfig": { "model": "anthropic/claude-sonnet-5", "temperature": 0.7, "maxOutputTokens": 2048, "topP": 0.9 } }, "schemaName": "ConversationUpdateDefaultGenerationConfigRequest" }, { "id": "cookbook-managed-agents-conversations-configuration-02-request", "operationId": "updateSettings", "operationKey": "conversations:updateSettings", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 2: Keep one unresolved turn at a time. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "support-chat-001", "settings": { "interruptPolicy": "INTERRUPT_POLICY_REJECT_NEW", "maxLoops": 4 } }, "schemaName": "UpdateSettingsRequest" }, { "id": "cookbook-managed-agents-conversations-configuration-03-request", "operationId": "updatePromptVariables", "operationKey": "conversations:updatePromptVariables", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Variant: personalize the profile for this customer. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "support-chat-001", "variables": { "userName": "Jane", "planTier": "pro" } }, "schemaName": "UpdatePromptVariablesRequest" }, { "id": "cookbook-managed-agents-conversations-context-management-01-request", "operationId": "updateContextManagementSettings", "operationKey": "conversations:updateContextManagementSettings", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Recipe: compact the older history, then continue the thread. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "support-chat-001", "contextManagementSettings": { "strategy": "CONTEXT_STRATEGY_COMPACTION", "compactionConfig": { "mode": "COMPACTION_MODE_SYNC", "threshold": { "percentage": 80 }, "preserveRecent": 10 } } }, "schemaName": "UpdateContextManagementSettingsRequest" }, { "id": "cookbook-managed-agents-conversations-context-management-02-request", "operationId": "compactConversation", "operationKey": "conversations:compactConversation", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Recipe: compact the older history, then continue the thread. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "support-chat-001" }, "schemaName": "CompactConversationRequest" }, { "id": "cookbook-managed-agents-conversations-context-management-03-request", "operationId": "getConversationState", "operationKey": "conversations:getConversationState", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Recipe: compact the older history, then continue the thread. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "support-chat-001" }, "schemaName": "GetConversationStateRequest" }, { "id": "cookbook-managed-agents-conversations-context-management-04-request", "operationId": "updateContextManagementSettings", "operationKey": "conversations:updateContextManagementSettings", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "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.", "payload": { "conversationKey": "support-chat-001", "contextManagementSettings": { "strategy": "CONTEXT_STRATEGY_COMPACTION", "selectiveExclusionConfig": { "excludeToolResults": true, "excludeImages": true } } }, "schemaName": "UpdateContextManagementSettingsRequest" }, { "id": "cookbook-managed-agents-conversations-generation-01-request", "operationId": "sendMessage", "operationKey": "conversations:sendMessage", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 1: Send once and read the same conversation. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "b81d5345-c1f9-4fb9-b558-a6327c75b842", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Hello, what can you help me with?" } ] } }, "schemaName": "SendMessageRequest" }, { "id": "cookbook-managed-agents-conversations-generation-03-request", "operationId": "sendMessageSync", "operationKey": "conversations:sendMessageSync", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Separate recipe: wait for a backend summary in the response. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "b81d5345-c1f9-4fb9-b558-a6327c75b842", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Summarize this thread as JSON." } ] } }, "schemaName": "SendMessageSyncRequest" }, { "id": "cookbook-managed-agents-conversations-generation-04-request", "operationId": "appendMessage", "operationKey": "conversations:appendMessage", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Separate recipe: record an onboarding event without another reply. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "b81d5345-c1f9-4fb9-b558-a6327c75b842", "message": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "CONTEXT UPDATE: user completed onboarding." } ] } }, "schemaName": "AppendMessageRequest" }, { "id": "cookbook-managed-agents-conversations-index-01-request", "operationId": "createThread", "operationKey": "conversations:createThread", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 1: Create the support thread once. Replace example resource identifiers with your own authorized values.", "payload": { "title": "Support Chat" }, "schemaName": "CreateThreadRequest" }, { "id": "cookbook-managed-agents-conversations-index-02-request", "operationId": "sendMessage", "operationKey": "conversations:sendMessage", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 2: Send the customer’s first question. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "support-chat-001", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "How do I reset my password?" } ] } }, "schemaName": "SendMessageRequest" }, { "id": "cookbook-managed-agents-delegation-approvals-build-agent-with-tools-01-request", "operationId": "createThread", "operationKey": "conversations:createThread", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 1: Describe the navigation your app can perform. Replace example resource identifiers with your own authorized values.", "payload": { "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" ] } } ] } }, "schemaName": "CreateThreadRequest" }, { "id": "cookbook-managed-agents-delegation-approvals-using-tools-01-request", "operationId": "listPendingApprovals", "operationKey": "conversations:listPendingApprovals", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 2: Show the action awaiting a decision. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "support-chat-001" }, "schemaName": "ListPendingApprovalsRequest" }, { "id": "cookbook-managed-agents-delegation-approvals-using-tools-02-request", "operationId": "submitToolApprovals", "operationKey": "conversations:submitToolApprovals", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 3: Submit the decision and inspect the outcome. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "support-chat-001", "approvals": [ { "toolCallId": "call_abc123", "approved": true } ] }, "schemaName": "SubmitToolApprovalsRequest" }, { "id": "cookbook-managed-agents-delegation-approvals-using-tools-03-request", "operationId": "sendMessageSync", "operationKey": "conversations:sendMessageSync", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 1: Receive the complete navigation call. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "support-chat-001", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "Navigate to my profile." } ] } }, "schemaName": "SendMessageSyncRequest" }, { "id": "cookbook-managed-agents-delegation-approvals-using-tools-04-request", "operationId": "submitClientToolResultsSync", "operationKey": "conversations:submitClientToolResultsSync", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 2: Validate, open and return the real result. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "support-chat-001", "clientToolCursor": 1, "results": [ { "toolCallId": "call_306135", "toolName": "navigate_to", "resultJson": { "navigated_to": "/profile" } } ] }, "schemaName": "SubmitClientToolResultsSyncRequest" }, { "id": "cookbook-managed-agents-delegation-approvals-using-tools-05-request", "operationId": "listPendingClientTools", "operationKey": "conversations:listPendingClientTools", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Recover the original call after a disconnect. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "support-chat-001" }, "schemaName": "ListPendingClientToolsRequest" }, { "id": "cookbook-managed-agents-delegation-approvals-using-tools-06-request", "operationId": "getToolCall", "operationKey": "conversations:getToolCall", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Recover the original call after a disconnect. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "support-chat-001", "toolCallId": "call_306135" }, "schemaName": "GetToolCallRequest" }, { "id": "cookbook-managed-agents-memory-knowledge-index-02-request", "operationId": "listMemories", "operationKey": "conversations:listMemories", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 2: Let the user review the stored records. Replace example resource identifiers with your own authorized values.", "payload": { "limit": 100 }, "schemaName": "ListMemoriesRequest" }, { "id": "cookbook-managed-agents-memory-knowledge-index-03-request", "operationId": "getMemory", "operationKey": "conversations:getMemory", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Inspect the selected record before changing it. Replace example resource identifiers with your own authorized values.", "payload": { "memoryId": "mem_abc123" }, "schemaName": "GetMemoryRequest" }, { "id": "cookbook-managed-agents-memory-knowledge-index-04-request", "operationId": "updateMemory", "operationKey": "conversations:updateMemory", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 3: Correct an outdated preference. Replace example resource identifiers with your own authorized values.", "payload": { "memoryId": "mem_abc123", "text": "User is vegetarian, avoids gluten, and prefers organic produce" }, "schemaName": "UpdateMemoryRequest" }, { "id": "cookbook-managed-agents-memory-knowledge-index-05-request", "operationId": "deleteMemory", "operationKey": "conversations:deleteMemory", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Remove the selected record. Replace example resource identifiers with your own authorized values.", "payload": { "memoryId": "mem_abc123" }, "schemaName": "DeleteMemoryRequest" }, { "id": "cookbook-managed-agents-model-controls-examples-01-request", "operationId": "createThread", "operationKey": "conversations:createThread", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Recipe: keep a research conversation on large-context candidates. Replace example resource identifiers with your own authorized values.", "payload": { "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 } } }, "schemaName": "CreateThreadRequest" }, { "id": "cookbook-managed-agents-model-controls-examples-02-request", "operationId": "sendMessage", "operationKey": "conversations:sendMessage", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Recipe: summarize support notes with a catalog price filter. Replace example resource identifiers with your own authorized values.", "payload": { "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 } } }, "schemaName": "SendMessageRequest" }, { "id": "cookbook-managed-agents-model-controls-examples-03-request", "operationId": "sendMessage", "operationKey": "conversations:sendMessage", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Recipe: return a task summary after tool-assisted work. Replace example resource identifiers with your own authorized values.", "payload": { "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" ] } } }, "schemaName": "SendMessageRequest" }, { "id": "cookbook-managed-agents-model-controls-filtering-01-request", "operationId": "sendMessage", "operationKey": "conversations:sendMessage", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 1: send the image with its required capability. Replace example resource identifiers with your own authorized values.", "payload": { "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" ] } } }, "schemaName": "SendMessageRequest" }, { "id": "cookbook-managed-agents-model-controls-filtering-02-request", "operationId": "createThread", "operationKey": "conversations:createThread", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Variant: keep a capability requirement for a long research thread. Replace example resource identifiers with your own authorized values.", "payload": { "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" } } }, "schemaName": "CreateThreadRequest" }, { "id": "cookbook-managed-agents-profiles-prompts-index-01-request", "operationId": "createAgentProfile", "operationKey": "agent-profiles:createAgentProfile", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 1: Save the assistant instructions. Replace example resource identifiers with your own authorized values.", "payload": { "profile": { "profileId": "nutrition_coach", "name": "Nutrition Coach", "description": "Food, meals and macros.", "whenToUse": "Use when the user asks about food, meals, or macros.", "keywords": [ "nutrition", "food", "macros" ], "enabled": true, "generationConfig": { "model": "YOUR_MODEL_ID", "systemPrompt": "You are a nutrition coach. Be concise and practical.", "temperature": 0.4 } } }, "schemaName": "CreateAgentProfileRequest" }, { "id": "cookbook-managed-agents-profiles-prompts-index-02-request", "operationId": "getAgentProfile", "operationKey": "agent-profiles:getAgentProfile", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 2: Confirm what you saved. Replace example resource identifiers with your own authorized values.", "payload": { "profileId": "nutrition_coach" }, "schemaName": "GetAgentProfileRequest" }, { "id": "cookbook-managed-agents-profiles-prompts-index-03-request", "operationId": "updateAgentProfile", "operationKey": "agent-profiles:updateAgentProfile", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Recipe: change the response style without replacing the profile. Replace example resource identifiers with your own authorized values.", "payload": { "profileId": "nutrition_coach", "profile": { "generationConfig": { "temperature": 0.2 } }, "updateMask": "generationConfig.temperature" }, "schemaName": "UpdateAgentProfileRequest" }, { "id": "cookbook-managed-agents-profiles-prompts-index-04-request", "operationId": "listAgentProfileVersions", "operationKey": "agent-profiles:listAgentProfileVersions", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Recipe: investigate a change and restore earlier content. Replace example resource identifiers with your own authorized values.", "payload": { "profileId": "nutrition_coach" }, "schemaName": "ListAgentProfileVersionsRequest" }, { "id": "cookbook-managed-agents-profiles-prompts-index-06-request", "operationId": "listAgentProfiles", "operationKey": "agent-profiles:listAgentProfiles", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Variant: inventory profiles before a shared change. Replace example resource identifiers with your own authorized values.", "payload": { "page": 1, "pageSize": 25 }, "schemaName": "ListAgentProfilesRequest" }, { "id": "cookbook-managed-agents-profiles-prompts-index-07-request", "operationId": "deleteAgentProfile", "operationKey": "agent-profiles:deleteAgentProfile", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Retire an assistant without stranding its conversations. Replace example resource identifiers with your own authorized values.", "payload": { "profileId": "nutrition_coach" }, "schemaName": "DeleteAgentProfileRequest" }, { "id": "cookbook-managed-agents-profiles-prompts-index-08-request", "operationId": "importAgentProfiles", "operationKey": "agent-profiles:importAgentProfiles", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Variant: migrate an existing prompt library. Replace example resource identifiers with your own authorized values.", "payload": { "templates": [ { "profileId": "nutrition_coach", "name": "Nutrition Coach", "whenToUse": "Use when the user asks about food, meals, or macros.", "keywords": [ "nutrition" ], "sourceDsl": "@include _shared/safety.txt\n\nYou are a nutrition coach for {{user_name}}.", "generationConfig": { "model": "YOUR_MODEL_ID" } } ], "fragments": [ { "fragmentId": "safety", "name": "Safety rules", "path": "_shared/safety.txt", "sourceDsl": "Never give medical advice." } ], "emitFragments": true }, "schemaName": "ImportAgentProfilesRequest" }, { "id": "cookbook-managed-agents-profiles-prompts-prompt-fragments-01-request", "operationId": "createPromptFragment", "operationKey": "agent-profiles:createPromptFragment", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 1: Create the block and include it in the profile. Replace example resource identifiers with your own authorized values.", "payload": { "fragment": { "fragmentId": "safety", "name": "Safety rules", "content": "Never give medical advice. Refer the user to a clinician when asked." } }, "schemaName": "CreatePromptFragmentRequest" }, { "id": "cookbook-managed-agents-profiles-prompts-prompt-fragments-02-request", "operationId": "getPromptFragment", "operationKey": "agent-profiles:getPromptFragment", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 2: Check the sources and record their set version. Replace example resource identifiers with your own authorized values.", "payload": { "fragmentId": "safety" }, "schemaName": "GetPromptFragmentRequest" }, { "id": "cookbook-managed-agents-profiles-prompts-prompt-fragments-03-request", "operationId": "listPromptFragments", "operationKey": "agent-profiles:listPromptFragments", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 2: Check the sources and record their set version. Replace example resource identifiers with your own authorized values.", "payload": { "page": 1, "pageSize": 25 }, "schemaName": "ListPromptFragmentsRequest" }, { "id": "cookbook-managed-agents-profiles-prompts-prompt-fragments-04-request", "operationId": "updatePromptFragment", "operationKey": "agent-profiles:updatePromptFragment", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Recipe: change shared wording across the assistants. Replace example resource identifiers with your own authorized values.", "payload": { "fragmentId": "safety", "fragment": { "content": "Never give medical or dosage advice. Refer the user to a clinician." }, "updateMask": "content" }, "schemaName": "UpdatePromptFragmentRequest" }, { "id": "cookbook-managed-agents-profiles-prompts-prompt-fragments-05-request", "operationId": "getPromptFragmentSet", "operationKey": "agent-profiles:getPromptFragmentSet", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Recover the text used before a change. Replace example resource identifiers with your own authorized values.", "payload": { "setVersion": 7 }, "schemaName": "GetPromptFragmentSetRequest" }, { "id": "cookbook-managed-agents-profiles-prompts-prompt-fragments-06-request", "operationId": "deletePromptFragment", "operationKey": "agent-profiles:deletePromptFragment", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Retire a shared block without leaving broken includes. Replace example resource identifiers with your own authorized values.", "payload": { "fragmentId": "safety" }, "schemaName": "DeletePromptFragmentRequest" }, { "id": "cookbook-managed-agents-voice-media-index-01-request", "operationId": "createDailySession", "operationKey": "conversations:createDailySession", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 1: Start the voice session for the existing thread. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "support-chat-001", "agentName": "my-voice-agent", "createDailyRoom": true, "dailyRoomProperties": { "enableRecording": "RECORDING_MODE_DISABLED" } }, "schemaName": "CreateDailySessionRequest" }, { "id": "cookbook-core-platform-files-data-files-json-01-response", "operationId": "generateUploadUrl", "operationKey": "storage:generateUploadUrl", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Upload and confirm the recording. Replace example resource identifiers with your own authorized values.", "payload": { "url": "https://storage.googleapis.com/bucket/...", "fileId": "a1b2c3d4e5f60718293a4b5c6d7e8f90", "fullPath": "/media/video.mp4", "requiredHeaders": { "content-type": "video/mp4", "x-goog-content-length-range": "0,52428800" } }, "status": "200", "schemaName": "GenerateUploadUrlResponse" }, { "id": "cookbook-core-platform-files-data-files-json-02-response", "operationId": "generateDownloadUrl", "operationKey": "storage:generateDownloadUrl", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Let the customer reopen the attachment. Replace example resource identifiers with your own authorized values.", "payload": { "url": "https://storage.googleapis.com/bucket/...", "file": { "name": "video.mp4", "path": "/media/video.mp4", "sizeBytes": "52428800", "contentType": "video/mp4" } }, "status": "200", "schemaName": "GenerateDownloadUrlResponse" }, { "id": "cookbook-core-platform-files-data-files-json-03-request", "operationId": "generateDownloadUrl", "operationKey": "storage:generateDownloadUrl", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Let the customer reopen the attachment. Replace example resource identifiers with your own authorized values.", "payload": { "fileId": "a1b2c3d4e5f60718293a4b5c6d7e8f90", "responseContentDisposition": "attachment; filename=my-video.mp4" }, "schemaName": "GenerateDownloadUrlRequest" }, { "id": "cookbook-core-platform-files-data-files-json-04-response", "operationId": "batchGenerateDownloadUrls", "operationKey": "storage:batchGenerateDownloadUrls", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Show several attachments on the case. Replace example resource identifiers with your own authorized values.", "payload": { "results": [ { "fileId": "a1b2c3d4e5f60718293a4b5c6d7e8f90", "url": "https://storage.googleapis.com/bucket/...", "success": true, "contentType": "video/mp4" }, { "fileId": "b2c3d4e5f60718293a4b5c6d7e8f901a", "error": "file not found" } ] }, "status": "200", "schemaName": "BatchGenerateDownloadUrlsResponse" }, { "id": "cookbook-core-platform-files-data-managing-json-01-request", "operationId": "listFiles", "operationKey": "storage:listFiles", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Populate the folder view. Replace example resource identifiers with your own authorized values.", "payload": { "folderPath": "/", "recursive": true, "filter": { "extensions": [ ".pdf", ".docx" ], "tags": [ "work" ], "minSizeBytes": 1024, "nameContains": "report" } }, "schemaName": "ListFilesRequest" }, { "id": "cookbook-core-platform-files-data-managing-json-02-response", "operationId": "getStorageQuota", "operationKey": "storage:getStorageQuota", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Make room for another attachment. Replace example resource identifiers with your own authorized values.", "payload": { "usedBytes": "1048576", "quotaBytes": "1073741824", "fileCount": 15, "folderCount": 4, "usagePercentage": 0.098 }, "status": "200", "schemaName": "GetStorageQuotaResponse" }, { "id": "cookbook-core-platform-identity-access-end-users-json-01-response", "operationId": "getEndUser", "operationKey": "end-users:getEndUser", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for 1. Load the saved settings and account defaults. Replace example resource identifiers with your own authorized values.", "payload": { "endUser": { "subject": "user_123", "tenantId": "tenant_abc", "email": "jane@example.com", "emailVerified": true, "name": "Jane Doe", "givenName": "Jane", "picture": "https://…", "signInProvider": "google.com", "locale": "en-US", "zoneinfo": "Europe/London", "location": { "latitude": 51.5072, "longitude": -0.1276, "timezone": "Europe/London", "updatedAt": "2026-08-14T09:31:02Z" }, "localeOverride": "es-MX", "defaultGenerationConfig": { "model": "google/gemini-3.6-flash", "temperature": 0.4, "languagePreference": "es" }, "metadata": { "preferredView": "compact" }, "firstSeenAt": "2026-01-14T09:12:00Z", "lastSeenAt": "2026-08-14T09:30:58Z", "updatedAt": "2026-08-14T09:31:02Z", "createdAt": "2026-01-14T09:12:00Z" } }, "status": "200", "schemaName": "GetEndUserResponse" }, { "id": "cookbook-core-platform-identity-access-end-users-json-02-request", "operationId": "updateLocale", "operationKey": "end-users:updateLocale", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 2. Save the user’s preferred language. Replace example resource identifiers with your own authorized values.", "payload": { "locale": "" }, "schemaName": "UpdateLocaleRequest" }, { "id": "cookbook-core-platform-identity-access-end-users-json-05-request", "operationId": "updateMetadata", "operationKey": "end-users:updateMetadata", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Variant: remember a display preference. Replace example resource identifiers with your own authorized values.", "payload": { "metadata": { "dismissedWelcome": "" } }, "schemaName": "UpdateMetadataRequest" }, { "id": "cookbook-core-platform-identity-access-end-users-json-06-response", "operationId": "updateLocation", "operationKey": "end-users:updateLocation", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Variant: use location for local-time context. Replace example resource identifiers with your own authorized values.", "payload": { "location": { "latitude": 51.5072, "longitude": -0.1276, "timezone": "Europe/London", "updatedAt": "2026-08-14T09:31:02Z" } }, "status": "200", "schemaName": "UpdateLocationResponse" }, { "id": "cookbook-core-platform-notifications-administration-json-02-request", "operationId": "createSubscriber", "operationKey": "notifications:createSubscriber", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for 2. Enroll the same application user. Replace example resource identifiers with your own authorized values.", "payload": { "subscriberId": "user-1" }, "schemaName": "CreateSubscriberRequest" }, { "id": "cookbook-core-platform-scheduling-build-scheduled-agents-json-02-response", "operationId": "sendMessageSync", "operationKey": "conversations:sendMessageSync", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Step 3: Drive an agent turn from the callback. Replace example resource identifiers with your own authorized values.", "payload": { "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 } }, "status": "200", "schemaName": "SendMessageSyncResponse" }, { "id": "cookbook-core-platform-scheduling-build-scheduled-agents-json-03-response", "operationId": "createJob", "operationKey": "scheduled-jobs:createJob", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Step 4: Create the schedule. Replace example resource identifiers with your own authorized values.", "payload": { "scheduleId": "sched_a1b2c3d4e5f60718", "name": "Daily agent briefing", "state": "SCHEDULE_STATUS_ACTIVE", "scheduleType": "SCHEDULE_TYPE_CRON", "cronExpression": "0 9 * * 1-5", "timezone": "America/New_York", "nextTriggerAt": "2026-06-04T13:00:00Z", "createdAt": "2026-06-03T14:00:00Z" }, "status": "200", "schemaName": "Schedule" }, { "id": "cookbook-core-platform-scheduling-build-scheduled-agents-json-04-response", "operationId": "createWebhookEndpoint", "operationKey": "webhooks:createWebhookEndpoint", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Step 5: Subscribe to the results webhook (Optional). Replace example resource identifiers with your own authorized values.", "payload": { "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" ] } }, "status": "200", "schemaName": "CreateWebhookEndpointResponse" }, { "id": "cookbook-core-platform-scheduling-creating-json-01-response", "operationId": "createJob", "operationKey": "scheduled-jobs:createJob", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Confirm and save the next scheduled time. Replace example resource identifiers with your own authorized values.", "payload": { "scheduleId": "sched_a1b2c3d4e5f60718", "name": "Daily digest", "state": "SCHEDULE_STATUS_ACTIVE", "scheduleType": "SCHEDULE_TYPE_CRON", "cronExpression": "0 9 * * 1-5", "timezone": "America/New_York", "nextTriggerAt": "2026-06-04T13:00:00Z", "createdAt": "2026-06-03T14:00:00Z" }, "status": "200", "schemaName": "Schedule" }, { "id": "cookbook-core-platform-scheduling-managing-json-01-response", "operationId": "deleteJobsForOwner", "operationKey": "scheduled-jobs:deleteJobsForOwner", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Account cleanup: remove all of the user’s schedules. Replace example resource identifiers with your own authorized values.", "payload": { "deletedCount": 3 }, "status": "200", "schemaName": "DeleteJobsForOwnerResponse" }, { "id": "cookbook-core-platform-scheduling-managing-json-02-response", "operationId": "deleteJobsForProject", "operationKey": "scheduled-jobs:deleteJobsForProject", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Project teardown: remove schedules across all owners. Replace example resource identifiers with your own authorized values.", "payload": { "deletedCount": 47 }, "status": "200", "schemaName": "DeleteJobsForProjectResponse" }, { "id": "cookbook-insights-evaluation-datasets-and-runs-json-01-response", "operationId": "listDatasetRuns", "operationKey": "evals:listDatasetRuns", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for 5. Decide whether the change fixes the problem without regressions. Replace example resource identifiers with your own authorized values.", "payload": { "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 } }, "status": "200", "schemaName": "ListDatasetRunsResponse" }, { "id": "cookbook-insights-evaluation-datasets-and-runs-json-02-response", "operationId": "getDatasetRun", "operationKey": "evals:getDatasetRun", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for 5. Decide whether the change fixes the problem without regressions. Replace example resource identifiers with your own authorized values.", "payload": { "run": { "runId": "run_0912", "name": "2026-08-12-candidate", "datasetId": "ds_771", "itemCount": 120, "metadataJson": "{\"profileRevisionHash\":\"9f2c1e…\"}", "createdAt": "2026-08-12T18:00:00Z" } }, "status": "200", "schemaName": "GetDatasetRunResponse" }, { "id": "cookbook-insights-evaluation-datasets-and-runs-json-03-response", "operationId": "listDatasets", "operationKey": "evals:listDatasets", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Browse the datasets. Replace example resource identifiers with your own authorized values.", "payload": { "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 } }, "status": "200", "schemaName": "ListDatasetsResponse" }, { "id": "cookbook-insights-evaluation-message-feedback-json-01-response", "operationId": "rateMessage", "operationKey": "conversations:rateMessage", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Save the user’s judgment beside the reply. Replace example resource identifiers with your own authorized values.", "payload": { "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 }, "status": "200", "schemaName": "RateMessageResponse" }, { "id": "cookbook-insights-evaluation-message-feedback-json-02-request", "operationId": "rateMessage", "operationKey": "conversations:rateMessage", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Variant: use a 1–10 scale instead of thumbs. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "support-chat-001", "messageSequence": 8, "kind": "FEEDBACK_KIND_SCALE", "rating": 9, "reason": "Answered the question and cited the policy." }, "schemaName": "RateMessageRequest" }, { "id": "cookbook-insights-evaluation-message-feedback-json-03-response", "operationId": "deleteMessageRating", "operationKey": "conversations:deleteMessageRating", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Let the user remove their judgment. Replace example resource identifiers with your own authorized values.", "payload": { "ratedMessage": { "role": "ROLE_ASSISTANT", "sequence": "8", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "…" } ] }, "removed": true }, "status": "200", "schemaName": "DeleteMessageRatingResponse" }, { "id": "cookbook-insights-evaluation-reading-json-01-response", "operationId": "listScores", "operationKey": "evals:listScores", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Read judgments about that same reply. Replace example resource identifiers with your own authorized values.", "payload": { "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 }, "status": "200", "schemaName": "ListScoresResponse" }, { "id": "cookbook-insights-evaluation-reading-json-02-response", "operationId": "listObservations", "operationKey": "evals:listObservations", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Check whether the same tool keeps failing. Replace example resource identifiers with your own authorized values.", "payload": { "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 }, "status": "200", "schemaName": "ListObservationsResponse" }, { "id": "cookbook-insights-evaluation-review-json-01-response", "operationId": "listAnnotationQueueItems", "operationKey": "evals:listAnnotationQueueItems", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Pull the worklist. Replace example resource identifiers with your own authorized values.", "payload": { "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 } }, "status": "200", "schemaName": "ListAnnotationQueueItemsResponse" }, { "id": "cookbook-insights-evaluation-review-json-02-response", "operationId": "completeAnnotationQueueItem", "operationKey": "evals:completeAnnotationQueueItem", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for 4. Complete the saved review. Replace example resource identifiers with your own authorized values.", "payload": { "item": { "itemId": "qi_001", "queueId": "q_weekly", "status": "ANNOTATION_QUEUE_ITEM_STATUS_COMPLETED", "completedAt": "2026-08-12T17:14:22Z", "completedBy": "reviewer_9" } }, "status": "200", "schemaName": "CompleteAnnotationQueueItemResponse" }, { "id": "cookbook-integrations-tools-connections-connected-apps-json-01-response", "operationId": "pipedreamListApps", "operationKey": "connected-apps:pipedreamListApps", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Find Google Calendar in the catalog. Replace example resource identifiers with your own authorized values.", "payload": { "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=" } }, "status": "200", "schemaName": "PipedreamListAppsResponse" }, { "id": "cookbook-integrations-tools-connections-connected-apps-json-02-response", "operationId": "pipedreamCreateConnectToken", "operationKey": "connected-apps:pipedreamCreateConnectToken", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Create the authorization link when the customer clicks Connect. Replace example resource identifiers with your own authorized values.", "payload": { "token": "ctok_5xyz...", "connectLinkUrl": "https://pipedream.com/_static/connect.html?token=ctok_5xyz...&connectLink=true&app=google_calendar", "expiresAt": "2026-08-10T10:04:11Z" }, "status": "200", "schemaName": "PipedreamCreateConnectTokenResponse" }, { "id": "cookbook-integrations-tools-connections-connected-apps-json-03-response", "operationId": "pipedreamListAccountsForCurrentUser", "operationKey": "connected-apps:pipedreamListAccountsForCurrentUser", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Confirm the account before showing Connected. Replace example resource identifiers with your own authorized values.", "payload": { "data": [ { "id": "apn_kAHeAr9", "name": "user@example.com", "app": "google_calendar", "healthy": true, "createdAt": "2026-08-10T09:14:52Z" } ], "pageInfo": { "count": 1, "totalCount": 1 } }, "status": "200", "schemaName": "PipedreamListAccountsForCurrentUserResponse" }, { "id": "cookbook-integrations-tools-connections-connected-apps-json-04-response", "operationId": "pipedreamDeleteExternalUserForCurrentUser", "operationKey": "connected-apps:pipedreamDeleteExternalUserForCurrentUser", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Remove integration data when the customer leaves. Replace example resource identifiers with your own authorized values.", "payload": { "deleted": true, "accountsDeleted": 3 }, "status": "200", "schemaName": "PipedreamDeleteExternalUserForCurrentUserResponse" }, { "id": "cookbook-integrations-tools-connections-custom-mcp-servers-json-01-response", "operationId": "testCustomMcpServerConnection", "operationKey": "mcp-servers:testCustomMcpServerConnection", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for 3. Check the saved connection and choose its tools. Replace example resource identifiers with your own authorized values.", "payload": { "success": true, "toolCount": 26, "latencyMs": "556" }, "status": "200", "schemaName": "TestCustomMCPServerConnectionResponse" }, { "id": "cookbook-managed-agents-conversations-build-chat-assistant-json-01-response", "operationId": "listThreads", "operationKey": "conversations:listThreads", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Verify credentials with your first call. Replace example resource identifiers with your own authorized values.", "payload": {}, "status": "200", "schemaName": "ListThreadsResponse" }, { "id": "cookbook-managed-agents-conversations-build-chat-assistant-json-02-response", "operationId": "createThread", "operationKey": "conversations:createThread", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Step 2: Start one support conversation. Replace example resource identifiers with your own authorized values.", "payload": { "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" } }, "status": "200", "schemaName": "CreateThreadResponse" }, { "id": "cookbook-managed-agents-conversations-build-chat-assistant-json-03-response", "operationId": "sendMessage", "operationKey": "conversations:sendMessage", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Send the message. Replace example resource identifiers with your own authorized values.", "payload": { "runId": "64403669-5989-4ec3-ad9c-d84223f9679f" }, "status": "200", "schemaName": "SendMessageResponse" }, { "id": "cookbook-managed-agents-conversations-build-chat-assistant-json-04-response", "operationId": "getConversationState", "operationKey": "conversations:getConversationState", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Poll conversation state. Replace example resource identifiers with your own authorized values.", "payload": { "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 }, "status": "200", "schemaName": "GetConversationStateResponse" }, { "id": "cookbook-managed-agents-conversations-build-chat-assistant-json-05-response", "operationId": "getConversationState", "operationKey": "conversations:getConversationState", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Poll conversation state. Replace example resource identifiers with your own authorized values.", "payload": { "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" }, "status": "200", "schemaName": "GetConversationStateResponse" }, { "id": "cookbook-managed-agents-conversations-build-chat-assistant-json-06-response", "operationId": "registerPushDevice", "operationKey": "notifications:registerPushDevice", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Variant: bring the user back when a notification arrives. Replace example resource identifiers with your own authorized values.", "payload": { "subscriberId": "user_123", "success": true }, "status": "200", "schemaName": "RegisterPushDeviceResponse" }, { "id": "cookbook-managed-agents-conversations-configuration-json-01-request", "operationId": "createThread", "operationKey": "conversations:createThread", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Variant: reuse the same assistant setup across conversations. Replace example resource identifiers with your own authorized values.", "payload": { "title": "Nutrition check-in", "activeProfileId": "nutrition_coach" }, "schemaName": "CreateThreadRequest" }, { "id": "cookbook-managed-agents-conversations-configuration-json-02-request", "operationId": "sendMessage", "operationKey": "conversations:sendMessage", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Variant: reuse the same assistant setup across conversations. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "thread_abc", "userMessage": { "role": "ROLE_USER", "content": [ { "type": "CONTENT_PART_TYPE_TEXT", "content": "..." } ] }, "setActiveProfileId": "profile_escalation" }, "schemaName": "SendMessageRequest" }, { "id": "cookbook-managed-agents-conversations-configuration-json-03-request", "operationId": "updatePromptVariables", "operationKey": "conversations:updatePromptVariables", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Variant: personalize the profile for this customer. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "support-chat-001", "variables": { "planTier": "enterprise" }, "updateMask": "planTier" }, "schemaName": "UpdatePromptVariablesRequest" }, { "id": "cookbook-managed-agents-conversations-context-management-json-01-response", "operationId": "compactConversation", "operationKey": "conversations:compactConversation", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Recipe: compact the older history, then continue the thread. Replace example resource identifiers with your own authorized values.", "payload": { "compactionId": "cmp_a1b2c3d4", "tokensBefore": 48211, "tokensAfter": 604, "tokensSaved": 47607, "durationMs": "4120", "status": "COMPACTION_STATUS_COMPLETED" }, "status": "200", "schemaName": "CompactConversationResponse" }, { "id": "cookbook-managed-agents-conversations-generation-json-02-response", "operationId": "getConversationState", "operationKey": "conversations:getConversationState", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Step 1: Send once and read the same conversation. Replace example resource identifiers with your own authorized values.", "payload": { "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 }, "status": "200", "schemaName": "GetConversationStateResponse" }, { "id": "cookbook-managed-agents-conversations-generation-json-03-response", "operationId": "getConversationState", "operationKey": "conversations:getConversationState", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Step 1: Send once and read the same conversation. Replace example resource identifiers with your own authorized values.", "payload": { "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" }, "status": "200", "schemaName": "GetConversationStateResponse" }, { "id": "cookbook-managed-agents-conversations-generation-json-04-response", "operationId": "sendMessageSync", "operationKey": "conversations:sendMessageSync", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Separate recipe: wait for a backend summary in the response. Replace example resource identifiers with your own authorized values.", "payload": { "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 } }, "status": "200", "schemaName": "SendMessageSyncResponse" }, { "id": "cookbook-managed-agents-conversations-generation-json-05-response", "operationId": "sendMessageSync", "operationKey": "conversations:sendMessageSync", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Recover a summary that failed or returned no explanation. Replace example resource identifiers with your own authorized values.", "payload": { "runId": "9d4c...", "status": "AGENT_STATUS_FAILED" }, "status": "200", "schemaName": "SendMessageSyncResponse" }, { "id": "cookbook-managed-agents-delegation-approvals-build-agent-with-tools-json-01-response", "operationId": "createThread", "operationKey": "conversations:createThread", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Step 1: Describe the navigation your app can perform. Replace example resource identifiers with your own authorized values.", "payload": { "thread": { "threadId": "b81d5345-c1f9-4fb9-b558-a6327c75b842" } }, "status": "200", "schemaName": "CreateThreadResponse" }, { "id": "cookbook-managed-agents-delegation-approvals-build-agent-with-tools-json-02-response", "operationId": "sendMessageSync", "operationKey": "conversations:sendMessageSync", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Step 2: Ask to open the profile and retain the pending call. Replace example resource identifiers with your own authorized values.", "payload": { "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" } ] }, "status": "200", "schemaName": "SendMessageSyncResponse" }, { "id": "cookbook-managed-agents-delegation-approvals-build-agent-with-tools-json-03-response", "operationId": "submitClientToolResultsSync", "operationKey": "conversations:submitClientToolResultsSync", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Step 3: Navigate once and report what happened. Replace example resource identifiers with your own authorized values.", "payload": { "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" } ] }, "status": "200", "schemaName": "SubmitClientToolResultsSyncResponse" }, { "id": "cookbook-managed-agents-delegation-approvals-using-tools-json-02-response", "operationId": "sendMessageSync", "operationKey": "conversations:sendMessageSync", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Step 1: Receive the complete navigation call. Replace example resource identifiers with your own authorized values.", "payload": { "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" } ] }, "status": "200", "schemaName": "SendMessageSyncResponse" }, { "id": "cookbook-managed-agents-delegation-approvals-using-tools-json-03-response", "operationId": "submitClientToolResultsSync", "operationKey": "conversations:submitClientToolResultsSync", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Step 2: Validate, open and return the real result. Replace example resource identifiers with your own authorized values.", "payload": { "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" } ] }, "status": "200", "schemaName": "SubmitClientToolResultsSyncResponse" }, { "id": "cookbook-managed-agents-memory-knowledge-index-json-02-request", "operationId": "updateDefaultGenerationConfig", "operationKey": "conversations:updateDefaultGenerationConfig", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 4: Include relevant memory in later replies. Replace example resource identifiers with your own authorized values.", "payload": { "conversationKey": "conv_abc", "defaultGenerationConfig": { "mem0": { "enabled": true, "searchTopK": 5, "searchThreshold": 0.3, "injectAsSystemContext": true, "injectMemoryTimestamps": true } } }, "schemaName": "ConversationUpdateDefaultGenerationConfigRequest" }, { "id": "cookbook-managed-agents-profiles-prompts-index-json-01-response", "operationId": "createAgentProfile", "operationKey": "agent-profiles:createAgentProfile", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Step 1: Save the assistant instructions. Replace example resource identifiers with your own authorized values.", "payload": { "profile": { "profileId": "nutrition_coach", "name": "Nutrition Coach", "description": "Food, meals and macros.", "whenToUse": "Use when the user asks about food, meals, or macros.", "keywords": [ "nutrition", "food", "macros" ], "enabled": true, "generationConfig": { "model": "YOUR_MODEL_ID", "systemPrompt": "You are a nutrition coach. Be concise and practical.", "temperature": 0.4 }, "version": 1 } }, "status": "200", "schemaName": "CreateAgentProfileResponse" }, { "id": "cookbook-managed-agents-profiles-prompts-index-json-02-request", "operationId": "getAgentProfile", "operationKey": "agent-profiles:getAgentProfile", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 2: Confirm what you saved. Replace example resource identifiers with your own authorized values.", "payload": { "profileId": "nutrition_coach", "version": 3 }, "schemaName": "GetAgentProfileRequest" }, { "id": "cookbook-managed-agents-profiles-prompts-index-json-03-response", "operationId": "listAgentProfileVersions", "operationKey": "agent-profiles:listAgentProfileVersions", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Recipe: investigate a change and restore earlier content. Replace example resource identifiers with your own authorized values.", "payload": { "versions": [ { "version": 3, "createdAt": "2026-08-14T10:22:41Z" }, { "version": 2, "createdAt": "2026-07-02T16:04:09Z" }, { "version": 1, "createdAt": "2026-06-19T09:11:55Z" } ] }, "status": "200", "schemaName": "ListAgentProfileVersionsResponse" }, { "id": "cookbook-managed-agents-profiles-prompts-index-json-04-response", "operationId": "getAgentProfileLibrary", "operationKey": "agent-profiles:getAgentProfileLibrary", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Variant: let the user choose an assistant. Replace example resource identifiers with your own authorized values.", "payload": { "library": { "profiles": [ { "profileId": "nutrition_coach", "name": "Nutrition Coach", "description": "Food, meals and macros.", "whenToUse": "Use when the user asks about food, meals, or macros.", "keywords": [ "nutrition", "food", "macros" ], "enabled": true } ], "defaultProfileId": "generalist" } }, "status": "200", "schemaName": "GetAgentProfileLibraryResponse" }, { "id": "cookbook-managed-agents-profiles-prompts-index-json-05-response", "operationId": "listAgentProfiles", "operationKey": "agent-profiles:listAgentProfiles", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Variant: inventory profiles before a shared change. Replace example resource identifiers with your own authorized values.", "payload": { "profiles": [ { "profileId": "nutrition_coach", "name": "Nutrition Coach", "version": 3 } ], "totalCount": 1, "hasMore": false }, "status": "200", "schemaName": "ListAgentProfilesResponse" }, { "id": "cookbook-managed-agents-profiles-prompts-index-json-06-request", "operationId": "updateAgentProfile", "operationKey": "agent-profiles:updateAgentProfile", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Retire an assistant without stranding its conversations. Replace example resource identifiers with your own authorized values.", "payload": { "profileId": "nutrition_coach", "profile": { "enabled": false }, "updateMask": "enabled" }, "schemaName": "UpdateAgentProfileRequest" }, { "id": "cookbook-managed-agents-profiles-prompts-index-json-07-response", "operationId": "importAgentProfiles", "operationKey": "agent-profiles:importAgentProfiles", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Variant: migrate an existing prompt library. Replace example resource identifiers with your own authorized values.", "payload": { "profiles": [ { "profileId": "nutrition_coach", "version": 1 } ], "fragments": [ { "fragmentId": "safety", "name": "Safety rules" } ] }, "status": "200", "schemaName": "ImportAgentProfilesResponse" }, { "id": "cookbook-managed-agents-profiles-prompts-prompt-fragments-json-01-response", "operationId": "createPromptFragment", "operationKey": "agent-profiles:createPromptFragment", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Step 1: Create the block and include it in the profile. Replace example resource identifiers with your own authorized values.", "payload": { "fragment": { "fragmentId": "safety", "name": "Safety rules", "content": "Never give medical advice. Refer the user to a clinician when asked." } }, "status": "200", "schemaName": "CreatePromptFragmentResponse" }, { "id": "cookbook-managed-agents-profiles-prompts-prompt-fragments-json-02-request", "operationId": "updateAgentProfile", "operationKey": "agent-profiles:updateAgentProfile", "direction": "request", "mediaType": "application/json", "revision": 1, "summary": "Guide request for Step 1: Create the block and include it in the profile. Replace example resource identifiers with your own authorized values.", "payload": { "profileId": "nutrition_coach", "profile": { "generationConfig": { "systemPrompt": "{{template \"safety\" .}}\n\nYou are a nutrition coach for {{.userName}}." } }, "updateMask": "generationConfig.systemPrompt" }, "schemaName": "UpdateAgentProfileRequest" }, { "id": "cookbook-managed-agents-profiles-prompts-prompt-fragments-json-03-response", "operationId": "listPromptFragments", "operationKey": "agent-profiles:listPromptFragments", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Step 2: Check the sources and record their set version. Replace example resource identifiers with your own authorized values.", "payload": { "fragments": [ { "fragmentId": "safety", "name": "Safety rules", "content": "Never give medical advice. Refer the user to a clinician when asked." } ], "totalCount": 1, "hasMore": false, "setVersion": 7 }, "status": "200", "schemaName": "ListPromptFragmentsResponse" }, { "id": "cookbook-managed-agents-profiles-prompts-prompt-fragments-json-04-response", "operationId": "getPromptFragmentSet", "operationKey": "agent-profiles:getPromptFragmentSet", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Recover the text used before a change. Replace example resource identifiers with your own authorized values.", "payload": { "setVersion": 7, "fragments": [ { "fragmentId": "safety", "name": "Safety rules", "content": "Never give medical advice. Refer the user to a clinician when asked." } ] }, "status": "200", "schemaName": "GetPromptFragmentSetResponse" }, { "id": "cookbook-managed-agents-voice-media-index-json-01-response", "operationId": "createDailySession", "operationKey": "conversations:createDailySession", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Step 2: Join the room and confirm the exchange. Replace example resource identifiers with your own authorized values.", "payload": { "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 } } }, "status": "200", "schemaName": "CreateDailySessionResponse" }, { "id": "cookbook-managed-agents-voice-media-index-json-02-response", "operationId": "mintSttToken", "operationKey": "conversations:mintSttToken", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative response for Separate recipe: dictate a draft without starting a voice agent. Replace example resource identifiers with your own authorized values.", "payload": { "token": "stt_eph_...", "expiresInSeconds": 600 }, "status": "200", "schemaName": "MintSttTokenResponse" }, { "id": "event-llm-message-published", "rootKey": "llm.message_published", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event.", "payload": { "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" } }, "schemaName": "LLMMessagePublishedEventWebhook" }, { "id": "event-llm-generation-started", "rootKey": "llm.generation_started", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event.", "payload": { "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" }, "schemaName": "LLMGenerationStartedEventWebhook" }, { "id": "event-llm-generation-completed", "rootKey": "llm.generation_completed", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event.", "payload": { "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 } }, "schemaName": "LLMGenerationCompletedEventWebhook" }, { "id": "event-llm-tool-call-started", "rootKey": "llm.tool_call_started", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event.", "payload": { "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" } }, "schemaName": "ToolCallStartedEventWebhook" }, { "id": "event-llm-tool-call-approval-required", "rootKey": "llm.tool_call_approval_required", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event.", "payload": { "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" } }, "schemaName": "ToolCallStartedEventWebhook" }, { "id": "event-llm-tool-call-completed", "rootKey": "llm.tool_call_completed", "direction": "response", "mediaType": "application/json", "revision": 1, "summary": "Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event.", "payload": { "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 } } }, "schemaName": "ToolCallCompletedEventWebhook" } ] }