Intended use: Machine administration of tenant-project custom MCP configuration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require authenticated backend and project configuration entitlement; use a tenant backend without a user subject; agent tool calls are outside this intended access. Intended audience: Tenant backend. Machine administration of tenant-project custom MCP configuration.
" } ] }, "runtime_enforcement": false }, { "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 `404`. The response does not expose the referenced credential's value.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Answer questions about a website using your own Firecrawl account](/integrations/tools-connections/custom-mcp-servers)", "slug": "/api/mcp-servers/get-custom-mcp-server", "method": "POST", "path": "/api/v1/mcp-servers/get", "requestSchema": "llm_v1_services_mcp_v1_GetCustomMCPServerRequest", "responseSchema": "llm_v1_services_mcp_v1_GetCustomMCPServerResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Server returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine administration of tenant-project custom MCP configuration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require authenticated backend and project configuration entitlement; use a tenant backend without a user subject; agent tool calls are outside this intended access. Intended audience: Tenant backend. Machine administration of tenant-project custom MCP configuration.
" } ] }, "runtime_enforcement": false }, { "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 name filter to inspect dependencies before rotating or deleting a credential.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Answer questions about a website using your own Firecrawl account](/integrations/tools-connections/custom-mcp-servers)", "slug": "/api/mcp-servers/list-custom-mcp-servers", "method": "POST", "path": "/api/v1/mcp-servers/list", "requestSchema": "llm_v1_services_mcp_v1_ListCustomMCPServersRequest", "responseSchema": "llm_v1_services_mcp_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine administration of tenant-project custom MCP configuration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require authenticated backend and project configuration entitlement; use a tenant backend without a user subject; agent tool calls are outside this intended access. Intended audience: Tenant backend. Machine administration of tenant-project custom MCP configuration.
" } ] }, "runtime_enforcement": false }, { "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 saved record, edit the intended fields and submit the complete desired server: omitting [`enabled`](/api/models/schema-p1cuh9jgfq#request-field-enabled) disables it, and omitted optional fields are cleared. The top-level `serverId` selects the record; an update cannot rename it. There is no revision precondition, so concurrent stale updates can overwrite one another.\n\nA saved update does not confirm that every subsequent call has switched to the new configuration, and it does not cancel in-flight calls. Use `get` to inspect the saved record and `test-connection` to check a connection using it. The same validation as create applies; an unknown server returns `404`.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Answer questions about a website using your own Firecrawl account](/integrations/tools-connections/custom-mcp-servers)", "slug": "/api/mcp-servers/update-custom-mcp-server", "method": "POST", "path": "/api/v1/mcp-servers/update", "requestSchema": "llm_v1_services_mcp_v1_UpdateCustomMCPServerRequest", "responseSchema": "llm_v1_services_mcp_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine administration of tenant-project custom MCP configuration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require authenticated backend and project configuration entitlement; use a tenant backend without a user subject; agent tool calls are outside this intended access. Intended audience: Tenant backend. Machine administration of tenant-project custom MCP configuration.
" } ] }, "runtime_enforcement": false }, { "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`. Conversations and profiles retain references to the deleted ID, so remove those references separately. New resolution fails once deletion is observed; in-flight calls and previously loaded definitions are not recalled. The referenced secret is left in place.\n\nTo retain the configuration while disabling the server, set `enabled: false` through [update](/api/mcp-servers/update-custom-mcp-server).\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Answer questions about a website using your own Firecrawl account](/integrations/tools-connections/custom-mcp-servers)", "slug": "/api/mcp-servers/delete-custom-mcp-server", "method": "POST", "path": "/api/v1/mcp-servers/delete", "requestSchema": "llm_v1_services_mcp_v1_DeleteCustomMCPServerRequest", "responseSchema": "llm_v1_services_mcp_v1_DeleteCustomMCPServerResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Delete processed", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine administration of tenant-project custom MCP configuration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require authenticated backend and project configuration entitlement; use a tenant backend without a user subject; agent tool calls are outside this intended access. Intended audience: Tenant backend. Machine administration of tenant-project custom MCP configuration.
" } ] }, "runtime_enforcement": false }, { "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 returns the observed count and latency. A concurrent update can change the record after that read. This operation reads the stored definition directly, making it useful after a configuration change.\n\nCheck [`success`](/api/mcp-servers/test-custom-mcp-server-connection#response-field-success) is `true`; a connection failure can return HTTP 200 with `success` false or omitted and an error. Inspect the error and repair the endpoint, authentication or network access before retrying. Authentication, validation, rate limiting and infrastructure failures can also return non-success HTTP responses.\n\nTests are limited to 10 per minute per project; destination restrictions apply when connecting. Rate limiting does not replace network isolation or authorization. A successful test is a point-in-time connection check, not a guarantee that every advertised tool is safe or available.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Answer questions about a website using your own Firecrawl account](/integrations/tools-connections/custom-mcp-servers)", "slug": "/api/mcp-servers/test-custom-mcp-server-connection", "method": "POST", "path": "/api/v1/mcp-servers/test-connection", "requestSchema": "llm_v1_services_mcp_v1_TestCustomMCPServerConnectionRequest", "responseSchema": "llm_v1_services_mcp_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine administration of tenant-project custom MCP configuration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require authenticated backend and project configuration entitlement; use a tenant backend without a user subject; agent tool calls are outside this intended access. Intended audience: Tenant backend. Machine administration of tenant-project custom MCP configuration.
" } ] }, "runtime_enforcement": false }, { "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 its next matching time.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Run work on a schedule](/core-platform/scheduling) · [Manage jobs](/core-platform/scheduling/managing) · [Automate recurring agent work](/core-platform/scheduling/build-scheduled-agents) · [Create a scheduled job](/core-platform/scheduling/creating) · [Monitor executions and retries](/core-platform/scheduling/execution) · [Schedule retries and auto-pause](/api/scheduled-jobs/schedules)", "slug": "/api/scheduled-jobs/create-job", "method": "POST", "path": "/api/v1/scheduler/create-job", "requestSchema": "platform_v1_services_scheduler_gateway_v1_CreateJobRequest", "responseSchema": "platform_v1_services_scheduler_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant backend scheduled-job administration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Authenticate tenant/project job-management entitlement and target ownership; the current intended audience does not include delegated personal scheduling by an app user. Intended audience: Tenant backend. Tenant backend scheduled-job administration.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Manage jobs](/core-platform/scheduling/managing)", "slug": "/api/scheduled-jobs/get-job", "method": "POST", "path": "/api/v1/scheduler/get-job", "requestSchema": "platform_v1_services_scheduler_gateway_v1_GetJobRequest", "responseSchema": "platform_v1_services_scheduler_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant backend scheduled-job administration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Authenticate tenant/project job-management entitlement and target ownership; the current intended audience does not include delegated personal scheduling by an app user. Intended audience: Tenant backend. Tenant backend scheduled-job administration.
" } ] }, "runtime_enforcement": false }, { "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 tenant and project. Optionally filter by lifecycle state or target kind.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Manage jobs](/core-platform/scheduling/managing)", "slug": "/api/scheduled-jobs/list-jobs", "method": "POST", "path": "/api/v1/scheduler/list-jobs", "requestSchema": "platform_v1_services_scheduler_gateway_v1_ListJobsRequest", "responseSchema": "platform_v1_services_scheduler_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant backend scheduled-job administration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Authenticate tenant/project job-management entitlement and target ownership; the current intended audience does not include delegated personal scheduling by an app user. Intended audience: Tenant backend. Tenant backend scheduled-job administration.
" } ] }, "runtime_enforcement": false }, { "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 remain unchanged.\n\n### Timing changes\n\nThe scheduler applies timing edits before returning by cancelling and reinserting the scheduled entry. This cannot undo an HTTP callback already dispatched or a business action your receiver has accepted.\n\n[`nextTriggerAt`](/api/models/schema-1ld0l8rmvg#response-field-nexttriggerat) on the returned job is the scheduling snapshot after the update; it can change as work advances. Do not infer wall-clock firing precision or business completion from that timestamp.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Manage jobs](/core-platform/scheduling/managing)", "slug": "/api/scheduled-jobs/update-job", "method": "POST", "path": "/api/v1/scheduler/update-job", "requestSchema": "platform_v1_services_scheduler_gateway_v1_UpdateJobRequest", "responseSchema": "platform_v1_services_scheduler_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant backend scheduled-job administration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Authenticate tenant/project job-management entitlement and target ownership; the current intended audience does not include delegated personal scheduling by an app user. Intended audience: Tenant backend. Tenant backend scheduled-job administration.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Manage jobs](/core-platform/scheduling/managing)", "slug": "/api/scheduled-jobs/pause-job", "method": "POST", "path": "/api/v1/scheduler/pause-job", "requestSchema": "platform_v1_services_scheduler_gateway_v1_PauseJobRequest", "responseSchema": "platform_v1_services_scheduler_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant backend scheduled-job administration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Authenticate tenant/project job-management entitlement and target ownership; the current intended audience does not include delegated personal scheduling by an app user. Intended audience: Tenant backend. Tenant backend scheduled-job administration.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Manage jobs](/core-platform/scheduling/managing)", "slug": "/api/scheduled-jobs/resume-job", "method": "POST", "path": "/api/v1/scheduler/resume-job", "requestSchema": "platform_v1_services_scheduler_gateway_v1_ResumeJobRequest", "responseSchema": "platform_v1_services_scheduler_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant backend scheduled-job administration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Authenticate tenant/project job-management entitlement and target ownership; the current intended audience does not include delegated personal scheduling by an app user. Intended audience: Tenant backend. Tenant backend scheduled-job administration.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Manage jobs](/core-platform/scheduling/managing)", "slug": "/api/scheduled-jobs/delete-job", "method": "POST", "path": "/api/v1/scheduler/delete-job", "requestSchema": "platform_v1_services_scheduler_gateway_v1_DeleteJobRequest", "responseSchema": "platform_v1_services_scheduler_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant backend scheduled-job administration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Authenticate tenant/project job-management entitlement and target ownership; the current intended audience does not include delegated personal scheduling by an app user. Intended audience: Tenant backend. Tenant backend scheduled-job administration.
" } ] }, "runtime_enforcement": false }, { "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 the request context. Intended as a tenant lifecycle hook invoked during project teardown. The request body carries no fields — tenant and project are derived from ingress headers.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Manage jobs](/core-platform/scheduling/managing)", "slug": "/api/scheduled-jobs/delete-jobs-for-project", "method": "POST", "path": "/api/v1/scheduler/delete-jobs-for-project", "requestSchema": "platform_v1_services_scheduler_gateway_v1_DeleteJobsForProjectRequest", "responseSchema": "platform_v1_services_scheduler_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant backend scheduled-job administration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Authenticate tenant/project job-management entitlement and target ownership; the current intended audience does not include delegated personal scheduling by an app user. Intended audience: Tenant backend. Tenant backend scheduled-job administration.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Manage jobs](/core-platform/scheduling/managing)", "slug": "/api/scheduled-jobs/delete-jobs-for-owner", "method": "POST", "path": "/api/v1/scheduler/delete-jobs-for-owner", "requestSchema": "platform_v1_services_scheduler_gateway_v1_DeleteJobsForOwnerRequest", "responseSchema": "platform_v1_services_scheduler_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant backend scheduled-job administration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Authenticate tenant/project job-management entitlement and target ownership; the current intended audience does not include delegated personal scheduling by an app user. Intended audience: Tenant backend. Tenant backend scheduled-job administration.
" } ] }, "runtime_enforcement": false }, { "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 captures a single firing — its status, HTTP result, attempt number, and duration. Optionally filter by execution status.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Monitor executions and retries](/core-platform/scheduling/execution)", "slug": "/api/scheduled-jobs/list-executions", "method": "POST", "path": "/api/v1/scheduler/list-executions", "requestSchema": "platform_v1_services_scheduler_gateway_v1_ListExecutionsRequest", "responseSchema": "platform_v1_services_scheduler_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant backend scheduled-job administration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Authenticate tenant/project job-management entitlement and target ownership; the current intended audience does not include delegated personal scheduling by an app user. Intended audience: Tenant backend. Tenant backend scheduled-job administration.
" } ] }, "runtime_enforcement": false }, { "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 `orderBy` other than `timestamp.desc` is rejected with HTTP 400. One trace is one conversation turn.\n\n### Filtering by entity\n\n`conversationId`, `profileId`, `userId` and `sessionId` are applied at the source, not over the returned page. Repeated entity filters intersect: `conversationId` + `profileId` returns turns in that conversation produced by that profile, not the union.\n\n`cursorPage.totalItems` is the only total any cursor-paged operation returns, and it is omitted whenever a profile, config-hash or level filter is set — that total cannot be counted exactly — or the count is unavailable.\n\n`conversationId` accepts the bare thread id — it is qualified with your verified tenant server-side, so an id held by a product surface works without the caller reconstructing the tenant-prefixed form.\n\nThe `filters` array is the general filter-builder vocabulary. Entity columns there (`conversationId`, `profileId`, `configHash`, `sourceUserMessageId`) accept an exact `=` match or `any of` a set. A `level` row matches traces with at least one observation at that level. Latency, token and cost columns are aggregates over a trace and cannot be filtered here (use `list-observations`). A filter row the underlying store cannot express — an inexact operator on an entity column, an aggregate column, or an unsupported column — is rejected with HTTP 400 rather than applied to the returned page.\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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Find out why a customer’s reply was slow](/insights/evaluation/reading)", "slug": "/api/evals/list-traces", "method": "POST", "path": "/api/v1/evals/list-traces", "requestSchema": "platform_v1_services_eval_gateway_v1_ListTracesRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_ListTracesResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "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 qualified with your verified tenant. The assistant message or rating event carries 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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Find out why a customer’s reply was slow](/insights/evaluation/reading)", "slug": "/api/evals/get-trace", "method": "POST", "path": "/api/v1/evals/get-trace", "requestSchema": "platform_v1_services_eval_gateway_v1_GetTraceRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_GetTraceResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "key": "evals:listObservations", "operationId": "listObservations", "bundle": "evals.yaml", "title": "List observations", "description": "Lists the individual spans, generations and events inside traces.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Find out why a customer’s reply was slow](/insights/evaluation/reading)", "slug": "/api/evals/list-observations", "method": "POST", "path": "/api/v1/evals/list-observations", "requestSchema": "platform_v1_services_eval_gateway_v1_ListObservationsRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_ListObservationsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "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`, `traceTags`, `createdAt`, `environment` and `metadata`. Columns aggregated over a session — duration, trace count, tokens, scores, comments — cannot be filtered and are rejected with HTTP 400. There is no free-text search.\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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Find out why a customer’s reply was slow](/insights/evaluation/reading)", "slug": "/api/evals/list-sessions", "method": "POST", "path": "/api/v1/evals/list-sessions", "requestSchema": "platform_v1_services_eval_gateway_v1_ListSessionsRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_ListSessionsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Find out why a customer’s reply was slow](/insights/evaluation/reading)", "slug": "/api/evals/get-session", "method": "POST", "path": "/api/v1/evals/get-session", "requestSchema": "platform_v1_services_eval_gateway_v1_GetSessionRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_GetSessionResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "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 \"every rating on turns this agent profile produced\". Each is decided per score — on the score's own metadata, or on the trace it scores when the metadata does not say — and combining them is an intersection. `conversationId` accepts a bare thread id and qualifies it with your verified tenant.\n\n### Reading the result honestly\n\n**`filterNarrowed`** matters when you paginate. Some filters cannot be applied by the underlying store, so rows are removed after they are fetched: `conversationId`, `profileId`, `userId`, the platform `source` values the store does not distinguish, and the rows of the `filters` array. The response sets `filterNarrowed: true` only when at least one row was removed from the pages fetched for this response. It can remain false or be omitted even when these filters were evaluated. A page may be shorter than `pageSize` or empty while `cursorPage.nextCursor` still leads to more matches — keep following the cursor until it is omitted rather than stopping at a short page. A false or omitted flag is not a complete-history or consistent-snapshot guarantee. There is no total.\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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Find out why a customer’s reply was slow](/insights/evaluation/reading) · [Feedback and score attribution](/api/evals/scoring)", "slug": "/api/evals/list-scores", "method": "POST", "path": "/api/v1/evals/list-scores", "requestSchema": "platform_v1_services_eval_gateway_v1_ListScoresRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_ListScoresResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "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\nThe request examples below show a numeric score of 0.9 for a trace target and a configured helpfulness rating with an explanatory comment. Use your verified trace target and applicable score configuration; the example identifiers are illustrative.\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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Review and score turns](/insights/evaluation/review) · [Feedback and score attribution](/api/evals/scoring)", "slug": "/api/evals/record-score", "method": "POST", "path": "/api/v1/evals/record-score", "requestSchema": "platform_v1_services_eval_gateway_v1_RecordScoreRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_RecordScoreResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Review and score turns](/insights/evaluation/review)", "slug": "/api/evals/delete-score", "method": "POST", "path": "/api/v1/evals/delete-score", "requestSchema": "platform_v1_services_eval_gateway_v1_DeleteScoreRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_DeleteScoreResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "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 configs remain readable for historical interpretation but are not offered for new ratings.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Review and score turns](/insights/evaluation/review) · [Feedback and score attribution](/api/evals/scoring)", "slug": "/api/evals/list-score-configs", "method": "POST", "path": "/api/v1/evals/list-score-configs", "requestSchema": "platform_v1_services_eval_gateway_v1_ListScoreConfigsRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_ListScoreConfigsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Review and score turns](/insights/evaluation/review)", "slug": "/api/evals/create-score-config", "method": "POST", "path": "/api/v1/evals/create-score-config", "requestSchema": "platform_v1_services_eval_gateway_v1_CreateScoreConfigRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_CreateScoreConfigResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "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\".\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Review and score turns](/insights/evaluation/review) · [Feedback and score attribution](/api/evals/scoring)", "slug": "/api/evals/update-score-config", "method": "POST", "path": "/api/v1/evals/update-score-config", "requestSchema": "platform_v1_services_eval_gateway_v1_UpdateScoreConfigRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_UpdateScoreConfigResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Review and score turns](/insights/evaluation/review)", "slug": "/api/evals/create-comment", "method": "POST", "path": "/api/v1/evals/create-comment", "requestSchema": "platform_v1_services_eval_gateway_v1_CreateCommentRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_CreateCommentResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "key": "evals:listComments", "operationId": "listComments", "bundle": "evals.yaml", "title": "List comments", "description": "Lists the comments on one object.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Review and score turns](/insights/evaluation/review)", "slug": "/api/evals/list-comments", "method": "POST", "path": "/api/v1/evals/list-comments", "requestSchema": "platform_v1_services_eval_gateway_v1_ListCommentsRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_ListCommentsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "key": "evals:deleteComment", "operationId": "deleteComment", "bundle": "evals.yaml", "title": "Delete a comment", "description": "Suppresses the selected comment from platform reads. The provider retains the comment; a successful response does not mean it was deleted from the provider.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Review and score turns](/insights/evaluation/review)", "slug": "/api/evals/delete-comment", "method": "POST", "path": "/api/v1/evals/delete-comment", "requestSchema": "platform_v1_services_eval_gateway_v1_DeleteCommentRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_DeleteCommentResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "key": "evals:listDatasets", "operationId": "listDatasets", "bundle": "evals.yaml", "title": "List datasets", "description": "Lists the evaluation datasets defined for this tenant.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Replay datasets and runs](/insights/evaluation/datasets-and-runs)", "slug": "/api/evals/list-datasets", "method": "POST", "path": "/api/v1/evals/list-datasets", "requestSchema": "platform_v1_services_eval_gateway_v1_ListDatasetsRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_ListDatasetsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "key": "evals:createDataset", "operationId": "createDataset", "bundle": "evals.yaml", "title": "Create a dataset", "description": "Creates an evaluation dataset.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Replay datasets and runs](/insights/evaluation/datasets-and-runs)", "slug": "/api/evals/create-dataset", "method": "POST", "path": "/api/v1/evals/create-dataset", "requestSchema": "platform_v1_services_eval_gateway_v1_CreateDatasetRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_CreateDatasetResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Replay datasets and runs](/insights/evaluation/datasets-and-runs) · [Dataset identity and run provenance](/api/evals/datasets)", "slug": "/api/evals/add-dataset-item", "method": "POST", "path": "/api/v1/evals/add-dataset-item", "requestSchema": "platform_v1_services_eval_gateway_v1_AddDatasetItemRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_AddDatasetItemResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "key": "evals:listDatasetItems", "operationId": "listDatasetItems", "bundle": "evals.yaml", "title": "List dataset items", "description": "Lists items in a dataset.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Replay datasets and runs](/insights/evaluation/datasets-and-runs) · [Dataset identity and run provenance](/api/evals/datasets)", "slug": "/api/evals/list-dataset-items", "method": "POST", "path": "/api/v1/evals/list-dataset-items", "requestSchema": "platform_v1_services_eval_gateway_v1_ListDatasetItemsRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_ListDatasetItemsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "key": "evals:updateDatasetItem", "operationId": "updateDatasetItem", "bundle": "evals.yaml", "title": "Update a dataset item", "description": "Edits an item — typically to fill in `expectedOutputJson` after review.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Replay datasets and runs](/insights/evaluation/datasets-and-runs) · [Dataset identity and run provenance](/api/evals/datasets)", "slug": "/api/evals/update-dataset-item", "method": "POST", "path": "/api/v1/evals/update-dataset-item", "requestSchema": "platform_v1_services_eval_gateway_v1_UpdateDatasetItemRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_UpdateDatasetItemResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Replay datasets and runs](/insights/evaluation/datasets-and-runs)", "slug": "/api/evals/list-dataset-runs", "method": "POST", "path": "/api/v1/evals/list-dataset-runs", "requestSchema": "platform_v1_services_eval_gateway_v1_ListDatasetRunsRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_ListDatasetRunsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Replay datasets and runs](/insights/evaluation/datasets-and-runs)", "slug": "/api/evals/get-dataset-run", "method": "POST", "path": "/api/v1/evals/get-dataset-run", "requestSchema": "platform_v1_services_eval_gateway_v1_GetDatasetRunRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_GetDatasetRunResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "key": "evals:listAnnotationQueues", "operationId": "listAnnotationQueues", "bundle": "evals.yaml", "title": "List annotation queues", "description": "Lists the review queues defined for this tenant.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Review and score turns](/insights/evaluation/review)", "slug": "/api/evals/list-annotation-queues", "method": "POST", "path": "/api/v1/evals/list-annotation-queues", "requestSchema": "platform_v1_services_eval_gateway_v1_ListAnnotationQueuesRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_ListAnnotationQueuesResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Review and score turns](/insights/evaluation/review)", "slug": "/api/evals/create-annotation-queue", "method": "POST", "path": "/api/v1/evals/create-annotation-queue", "requestSchema": "platform_v1_services_eval_gateway_v1_CreateAnnotationQueueRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_CreateAnnotationQueueResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Review and score turns](/insights/evaluation/review)", "slug": "/api/evals/enqueue-for-annotation", "method": "POST", "path": "/api/v1/evals/enqueue-for-annotation", "requestSchema": "platform_v1_services_eval_gateway_v1_EnqueueForAnnotationRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_EnqueueForAnnotationResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "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/schema-ovc35nr9td#response-field-objectid) to [get-trace](/api/evals/get-trace). Other target kinds need their matching read operation.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Review and score turns](/insights/evaluation/review)", "slug": "/api/evals/list-annotation-queue-items", "method": "POST", "path": "/api/v1/evals/list-annotation-queue-items", "requestSchema": "platform_v1_services_eval_gateway_v1_ListAnnotationQueueItemsRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_ListAnnotationQueueItemsResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "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 [`completedBy`](/api/models/schema-ovc35nr9td#response-field-completedby), but the current API does not persist that attribution for later list reads. Do not use this response alone as a durable reviewer audit record.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Review and score turns](/insights/evaluation/review)", "slug": "/api/evals/complete-annotation-queue-item", "method": "POST", "path": "/api/v1/evals/complete-annotation-queue-item", "requestSchema": "platform_v1_services_eval_gateway_v1_CompleteAnnotationQueueItemRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_CompleteAnnotationQueueItemResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "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.\n\nCallers use platform API access and do not need an evaluation-provider credential or direct evaluation-provider URL. Authorisation depends on verified caller identity and scope, not on which client interface made the request.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Find out why a customer’s reply was slow](/insights/evaluation/reading)", "slug": "/api/evals/get-overview", "method": "POST", "path": "/api/v1/evals/get-overview", "requestSchema": "platform_v1_services_eval_gateway_v1_GetOverviewRequest", "responseSchema": "platform_v1_services_eval_gateway_v1_GetOverviewResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "OK", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Machine harness/tenant tooling evaluation and observability. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive tenant/project identity and enforce evaluation permissions; no caller-supplied tenant/subject/rater authority. For attributed writes, derive operator attribution from trusted request context, never from request-body rater or author identifiers. Where an operation requires a person identity, that identity must represent a verified operator. Intended audience: Tenant backend. Machine harness/tenant tooling evaluation and observability.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Keep push notifications attached to the signed-in user](/core-platform/notifications/push) · [Build a signed-in support chat that survives reconnects](/managed-agents/conversations/build-chat-assistant)", "slug": "/api/notifications/register-push-device", "method": "POST", "path": "/api/v1/notifications/register-push-device", "requestSchema": "notification_v1_services_gateway_v1_RegisterPushDeviceRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Keep push notifications attached to the signed-in user](/core-platform/notifications/push) · [Build a signed-in support chat that survives reconnects](/managed-agents/conversations/build-chat-assistant) · [Push registration and topic delivery](/api/notifications/delivery)", "slug": "/api/notifications/unregister-push-device", "method": "POST", "path": "/api/v1/notifications/unregister-push-device", "requestSchema": "notification_v1_services_gateway_v1_UnregisterPushDeviceRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Keep push notifications attached to the signed-in user](/core-platform/notifications/push)", "slug": "/api/notifications/get-registered-channels", "method": "POST", "path": "/api/v1/notifications/get-registered-channels", "requestSchema": "notification_v1_services_gateway_v1_GetRegisteredChannelsRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build an in-app inbox](/core-platform/notifications/inbox) · [Inbox state and actions](/api/notifications/inbox)", "slug": "/api/notifications/get-inbox-session", "method": "POST", "path": "/api/v1/notifications/get-inbox-session", "requestSchema": "notification_v1_services_gateway_v1_GetInboxSessionRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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. The 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. Acceptance does not confirm delivery or a read receipt: workflow configuration, recipient preferences and provider delivery can produce later failures or suppression. Check delivery status for the subsequent channel attempts.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Send notifications](/core-platform/notifications/sending) · [Welcome a new user with an in-app message](/core-platform/notifications/administration)", "slug": "/api/notifications/send-notification", "method": "POST", "path": "/api/v1/notifications/manage/send", "requestSchema": "notification_v1_services_gateway_v1_SendNotificationRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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 entry's [`acknowledged`](/api/models/schema-oisl2i7j7o#response-field-acknowledged) and errors rather than the HTTP status alone. Accepted triggers are not delivery receipts, and retrying an entire partially accepted batch can duplicate work.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Send notifications](/core-platform/notifications/sending)", "slug": "/api/notifications/send-bulk-notification", "method": "POST", "path": "/api/v1/notifications/manage/send-bulk", "requestSchema": "notification_v1_services_gateway_v1_SendBulkNotificationRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: Tenant backend. Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Send notifications](/core-platform/notifications/sending)", "slug": "/api/notifications/cancel-notification", "method": "POST", "path": "/api/v1/notifications/manage/cancel", "requestSchema": "notification_v1_services_gateway_v1_CancelNotificationRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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, applying the supplied selection criteria.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build an in-app inbox](/core-platform/notifications/inbox)", "slug": "/api/notifications/get-inbox-feed", "method": "POST", "path": "/api/v1/notifications/get-inbox-feed", "requestSchema": "notification_v1_services_gateway_v1_GetInboxFeedRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build an in-app inbox](/core-platform/notifications/inbox)", "slug": "/api/notifications/get-inbox-unseen-count", "method": "POST", "path": "/api/v1/notifications/get-inbox-unseen-count", "requestSchema": "notification_v1_services_gateway_v1_GetInboxUnseenCountRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build an in-app inbox](/core-platform/notifications/inbox)", "slug": "/api/notifications/mark-inbox-message-as", "method": "POST", "path": "/api/v1/notifications/mark-inbox-message", "requestSchema": "notification_v1_services_gateway_v1_MarkInboxMessageAsRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build an in-app inbox](/core-platform/notifications/inbox)", "slug": "/api/notifications/mark-all-inbox-messages-as", "method": "POST", "path": "/api/v1/notifications/mark-all-inbox-messages", "requestSchema": "notification_v1_services_gateway_v1_MarkAllInboxMessagesAsRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build an in-app inbox](/core-platform/notifications/inbox)", "slug": "/api/notifications/delete-inbox-message", "method": "POST", "path": "/api/v1/notifications/delete-inbox-message", "requestSchema": "notification_v1_services_gateway_v1_DeleteInboxMessageRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build an in-app inbox](/core-platform/notifications/inbox)", "slug": "/api/notifications/archive-inbox-message", "method": "POST", "path": "/api/v1/notifications/archive-inbox-message", "requestSchema": "notification_v1_services_gateway_v1_ArchiveInboxMessageRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build an in-app inbox](/core-platform/notifications/inbox)", "slug": "/api/notifications/unarchive-inbox-message", "method": "POST", "path": "/api/v1/notifications/unarchive-inbox-message", "requestSchema": "notification_v1_services_gateway_v1_UnarchiveInboxMessageRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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).\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build an in-app inbox](/core-platform/notifications/inbox) · [Inbox state and actions](/api/notifications/inbox)", "slug": "/api/notifications/archive-all-inbox-messages", "method": "POST", "path": "/api/v1/notifications/archive-all-inbox-messages", "requestSchema": "notification_v1_services_gateway_v1_ArchiveAllInboxMessagesRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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).\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build an in-app inbox](/core-platform/notifications/inbox)", "slug": "/api/notifications/archive-all-read-inbox-messages", "method": "POST", "path": "/api/v1/notifications/archive-all-read-inbox-messages", "requestSchema": "notification_v1_services_gateway_v1_ArchiveAllReadInboxMessagesRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build an in-app inbox](/core-platform/notifications/inbox)", "slug": "/api/notifications/complete-inbox-action", "method": "POST", "path": "/api/v1/notifications/complete-inbox-action", "requestSchema": "notification_v1_services_gateway_v1_CompleteInboxActionRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build an in-app inbox](/core-platform/notifications/inbox)", "slug": "/api/notifications/revert-inbox-action", "method": "POST", "path": "/api/v1/notifications/revert-inbox-action", "requestSchema": "notification_v1_services_gateway_v1_RevertInboxActionRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Broadcast with topics](/core-platform/notifications/topics) · [Push registration and topic delivery](/api/notifications/delivery)", "slug": "/api/notifications/create-topic", "method": "POST", "path": "/api/v1/notifications/manage/create-topic", "requestSchema": "notification_v1_services_gateway_v1_CreateTopicRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: Tenant backend. Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Broadcast with topics](/core-platform/notifications/topics) · [Push registration and topic delivery](/api/notifications/delivery)", "slug": "/api/notifications/delete-topic", "method": "POST", "path": "/api/v1/notifications/manage/delete-topic", "requestSchema": "notification_v1_services_gateway_v1_DeleteTopicRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: Tenant backend. Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Broadcast with topics](/core-platform/notifications/topics)", "slug": "/api/notifications/add-subscribers-to-topic", "method": "POST", "path": "/api/v1/notifications/manage/add-subscribers-to-topic", "requestSchema": "notification_v1_services_gateway_v1_AddSubscribersToTopicRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: Tenant backend. Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Broadcast with topics](/core-platform/notifications/topics)", "slug": "/api/notifications/remove-subscribers-from-topic", "method": "POST", "path": "/api/v1/notifications/manage/remove-subscribers-from-topic", "requestSchema": "notification_v1_services_gateway_v1_RemoveSubscribersFromTopicRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: Tenant backend. Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject.
" } ] }, "runtime_enforcement": false }, { "key": "notifications:listTopicSubscribers", "operationId": "listTopicSubscribers", "bundle": "notifications.yaml", "title": "List subscribers of a topic", "description": "Returns the first page of user IDs subscribed to the selected topic, bounded by page\\_size. The page field does not advance the result, and no continuation cursor is returned. A true has\\_more value does not provide a way to retrieve the next page through this operation.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Broadcast with topics](/core-platform/notifications/topics)", "slug": "/api/notifications/list-topic-subscribers", "method": "POST", "path": "/api/v1/notifications/manage/list-topic-subscribers", "requestSchema": "notification_v1_services_gateway_v1_ListTopicSubscribersRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: Tenant backend. Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Broadcast with topics](/core-platform/notifications/topics) · [Push registration and topic delivery](/api/notifications/delivery)", "slug": "/api/notifications/check-topic-subscription", "method": "POST", "path": "/api/v1/notifications/manage/check-topic-subscription", "requestSchema": "notification_v1_services_gateway_v1_CheckTopicSubscriptionRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: Tenant backend. Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Broadcast with topics](/core-platform/notifications/topics) · [Push registration and topic delivery](/api/notifications/delivery)", "slug": "/api/notifications/send-to-topic", "method": "POST", "path": "/api/v1/notifications/manage/send-to-topic", "requestSchema": "notification_v1_services_gateway_v1_SendToTopicRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: Tenant backend. Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject.
" } ] }, "runtime_enforcement": false }, { "key": "notifications:sendWithDigest", "operationId": "sendWithDigest", "bundle": "notifications.yaml", "title": "Send a notification with digest aggregation", "description": "Triggers a notification workflow that must already have a digest step configured. The workflow’s configured digest window determines whether and how events are batched before delivery; this operation does not create that digest configuration.\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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Send notifications](/core-platform/notifications/sending)", "slug": "/api/notifications/send-with-digest", "method": "POST", "path": "/api/v1/notifications/manage/send-with-digest", "requestSchema": "notification_v1_services_gateway_v1_SendWithDigestRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Send notifications](/core-platform/notifications/sending)", "slug": "/api/notifications/cancel-digest-event", "method": "POST", "path": "/api/v1/notifications/manage/cancel-digest-event", "requestSchema": "notification_v1_services_gateway_v1_CancelDigestEventRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Manage notification preferences](/core-platform/notifications/preferences)", "slug": "/api/notifications/get-preferences", "method": "POST", "path": "/api/v1/notifications/get-preferences", "requestSchema": "notification_v1_services_gateway_v1_GetPreferencesRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Manage notification preferences](/core-platform/notifications/preferences)", "slug": "/api/notifications/update-global-preference", "method": "POST", "path": "/api/v1/notifications/update-global-preference", "requestSchema": "notification_v1_services_gateway_v1_UpdateGlobalPreferenceRequest", "responseSchema": "google_protobuf_Empty", "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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Manage notification preferences](/core-platform/notifications/preferences)", "slug": "/api/notifications/update-workflow-preference", "method": "POST", "path": "/api/v1/notifications/update-workflow-preference", "requestSchema": "notification_v1_services_gateway_v1_UpdateWorkflowPreferenceRequestRequest", "responseSchema": "google_protobuf_Empty", "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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Manage notification preferences](/core-platform/notifications/preferences) · [Preferences and channel inheritance](/api/notifications/preferences)", "slug": "/api/notifications/bulk-update-preferences", "method": "POST", "path": "/api/v1/notifications/bulk-update-preferences", "requestSchema": "notification_v1_services_gateway_v1_BulkUpdatePreferencesRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration)", "slug": "/api/notifications/update-subscriber-data", "method": "POST", "path": "/api/v1/notifications/manage/update-subscriber-data", "requestSchema": "notification_v1_services_gateway_v1_UpdateSubscriberDataRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration)", "slug": "/api/notifications/get-subscriber", "method": "POST", "path": "/api/v1/notifications/manage/get-subscriber", "requestSchema": "notification_v1_services_gateway_v1_GetSubscriberRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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 provider. An absent subscriber is an idempotent success.\n\nInspect nested `status.acknowledged`. A missing [`status`](/api/notifications/delete-subscriber#response-field-status) is unknown: the current handler can return an empty HTTP 200 response on configuration, network or provider errors. Reconcile that outcome instead of declaring cleanup complete. Provider acknowledgment does not certify complete erasure of queued work, remote copies or platform records.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration)", "slug": "/api/notifications/delete-subscriber", "method": "POST", "path": "/api/v1/notifications/manage/delete-subscriber", "requestSchema": "notification_v1_services_gateway_v1_DeleteSubscriberRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration)", "slug": "/api/notifications/create-subscriber", "method": "POST", "path": "/api/v1/notifications/manage/create-subscriber", "requestSchema": "notification_v1_services_gateway_v1_CreateSubscriberRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: Tenant backend. Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.", "slug": "/api/notifications/list-subscribers", "method": "POST", "path": "/api/v1/notifications/manage/list-subscribers", "requestSchema": "notification_v1_services_gateway_v1_ListSubscribersRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: Tenant backend. Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration)", "slug": "/api/notifications/get-delivery-status", "method": "POST", "path": "/api/v1/notifications/manage/get-delivery-status", "requestSchema": "notification_v1_services_gateway_v1_GetDeliveryStatusRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "key": "notifications:getNotificationActivity", "operationId": "getNotificationActivity", "bundle": "notifications.yaml", "title": "Get notification activity log", "description": "Returns provider activity pages for diagnosing delivery across recipients. Provider activity can lag delivery and is not a complete authorization or business-outcome audit. Use a bounded time window to inspect failures, and keep successful recipients usable while you investigate.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration) · [Preferences and channel inheritance](/api/notifications/preferences)", "slug": "/api/notifications/get-notification-activity", "method": "POST", "path": "/api/v1/notifications/manage/get-notification-activity", "requestSchema": "notification_v1_services_gateway_v1_GetNotificationActivityRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated personal notification inbox and preferences. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: App user, Tenant backend. Authenticated personal notification inbox and preferences.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration)", "slug": "/api/notifications/configure-provider", "method": "POST", "path": "/api/v1/notifications/manage/configure-provider", "requestSchema": "notification_v1_services_gateway_v1_ConfigureProviderRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: Tenant backend. Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject.
" } ] }, "runtime_enforcement": false }, { "key": "notifications:getProviders", "operationId": "getProviders", "bundle": "notifications.yaml", "title": "List configured providers", "description": "Returns active configured notification providers and their integration identifiers. Inactive providers are omitted.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.", "slug": "/api/notifications/get-providers", "method": "POST", "path": "/api/v1/notifications/manage/get-providers", "requestSchema": "notification_v1_services_gateway_v1_GetProvidersRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: Tenant backend. Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration)", "slug": "/api/notifications/create-workflow", "method": "POST", "path": "/api/v1/notifications/manage/create-workflow", "requestSchema": "notification_v1_services_gateway_v1_CreateWorkflowRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: Tenant backend. Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject.
" } ] }, "runtime_enforcement": false }, { "key": "notifications:updateWorkflow", "operationId": "updateWorkflow", "bundle": "notifications.yaml", "title": "Update an existing notification workflow", "description": "Updates the identified workflow using the supplied definition.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration)", "slug": "/api/notifications/update-workflow", "method": "POST", "path": "/api/v1/notifications/manage/update-workflow", "requestSchema": "notification_v1_services_gateway_v1_UpdateWorkflowRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: Tenant backend. Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject.
" } ] }, "runtime_enforcement": false }, { "key": "notifications:getWorkflow", "operationId": "getWorkflow", "bundle": "notifications.yaml", "title": "Get a notification workflow", "description": "Returns the full workflow definition and metadata for the supplied workflow ID. A trigger identifier alone does not select the workflow.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration)", "slug": "/api/notifications/get-workflow", "method": "POST", "path": "/api/v1/notifications/manage/get-workflow", "requestSchema": "notification_v1_services_gateway_v1_GetWorkflowRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: Tenant backend. Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject.
" } ] }, "runtime_enforcement": false }, { "key": "notifications:listWorkflows", "operationId": "listWorkflows", "bundle": "notifications.yaml", "title": "List notification workflows", "description": "Returns a paginated list of all notification workflows with summary information.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration)", "slug": "/api/notifications/list-workflows", "method": "POST", "path": "/api/v1/notifications/manage/list-workflows", "requestSchema": "notification_v1_services_gateway_v1_ListWorkflowsRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: Tenant backend. Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration)", "slug": "/api/notifications/delete-workflow", "method": "POST", "path": "/api/v1/notifications/manage/delete-workflow", "requestSchema": "notification_v1_services_gateway_v1_DeleteWorkflowRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: Tenant backend. Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration)", "slug": "/api/notifications/get-pending-changes", "method": "POST", "path": "/api/v1/notifications/manage/get-pending-changes", "requestSchema": "notification_v1_services_gateway_v1_GetPendingChangesRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: Tenant backend. Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration)", "slug": "/api/notifications/promote-change", "method": "POST", "path": "/api/v1/notifications/manage/promote-change", "requestSchema": "notification_v1_services_gateway_v1_PromoteChangeRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: Tenant backend. Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Welcome a new user with an in-app message](/core-platform/notifications/administration)", "slug": "/api/notifications/promote-all-changes", "method": "POST", "path": "/api/v1/notifications/manage/promote-all-changes", "requestSchema": "notification_v1_services_gateway_v1_PromoteAllChangesRequest", "responseSchema": "notification_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require beneficiary ownership; restrict tenant administration exceptions to authorized tenant backends and keep supplied subscriber IDs from becoming trusted identity. Intended audience: Tenant backend. Tenant notification administration or multi-recipient action; backend authorization is required, not merely a person subject.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps)", "slug": "/api/connected-apps/pipedream-create-connect-token", "method": "POST", "path": "/api/v1/integrations/pipedream/create-connect-token", "requestSchema": "integrations_v1_services_gateway_v1_PipedreamCreateConnectTokenRequest", "responseSchema": "integrations_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person integration self-service or authorized backend delegation. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person integration self-service or authorized backend delegation. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive the subject rather than accept an external-user identity, verify delegated action/account ownership, and maintain the platform integration boundary. Intended audience: App user, Tenant backend. Authenticated person integration self-service or authorized backend delegation.
" } ] }, "runtime_enforcement": false }, { "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 build an app picker.\n\nThis is public catalog data. It does not tell you what the caller has already connected; use [`list-accounts`](/api/connected-apps/pipedream-list-accounts-for-current-user) for that.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized shared platform action.\n\nUse this in a guide: [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps)", "slug": "/api/connected-apps/pipedream-list-apps", "method": "POST", "path": "/api/v1/integrations/pipedream/list-apps", "requestSchema": "integrations_v1_services_gateway_v1_PipedreamListAppsRequest", "responseSchema": "integrations_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Nobody", "data_scope": "Global", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated discovery of shared integration reference data; account-bound dynamic results require separate owner checks. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated discovery of shared integration reference data; account-bound dynamic results require separate owner checks. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized shared platform action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive the subject rather than accept an external-user identity, verify delegated action/account ownership, and maintain the platform integration boundary. Intended audience: App user, Tenant backend. Authenticated discovery of shared integration reference data; account-bound dynamic results require separate owner checks.
" } ] }, "runtime_enforcement": false }, { "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 in this API (`github`, `slack`, `google_calendar`). Use it to render an app detail page without paging the whole catalog.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized shared platform action.\n\nUse this in a guide: [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps)", "slug": "/api/connected-apps/pipedream-retrieve-app", "method": "POST", "path": "/api/v1/integrations/pipedream/retrieve-app", "requestSchema": "integrations_v1_services_gateway_v1_PipedreamRetrieveAppRequest", "responseSchema": "integrations_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Nobody", "data_scope": "Global", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated discovery of shared integration reference data; account-bound dynamic results require separate owner checks. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated discovery of shared integration reference data; account-bound dynamic results require separate owner checks. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized shared platform action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive the subject rather than accept an external-user identity, verify delegated action/account ownership, and maintain the platform integration boundary. Intended audience: App user, Tenant backend. Authenticated discovery of shared integration reference data; account-bound dynamic results require separate owner checks.
" } ] }, "runtime_enforcement": false }, { "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\"). Feed the returned `id` values into `categoryIds` on [`list-apps`](/api/connected-apps/pipedream-list-apps) to filter a picker by category.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized shared platform action.\n\nUse this in a guide: [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps)", "slug": "/api/connected-apps/pipedream-list-app-categories", "method": "POST", "path": "/api/v1/integrations/pipedream/list-app-categories", "requestSchema": "integrations_v1_services_gateway_v1_PipedreamListAppCategoriesRequest", "responseSchema": "integrations_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Nobody", "data_scope": "Global", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated discovery of shared integration reference data; account-bound dynamic results require separate owner checks. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated discovery of shared integration reference data; account-bound dynamic results require separate owner checks. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized shared platform action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive the subject rather than accept an external-user identity, verify delegated action/account ownership, and maintain the platform integration boundary. Intended audience: App user, Tenant backend. Authenticated discovery of shared integration reference data; account-bound dynamic results require separate owner checks.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps)", "slug": "/api/connected-apps/pipedream-list-accounts-for-current-user", "method": "POST", "path": "/api/v1/integrations/pipedream/list-accounts", "requestSchema": "integrations_v1_services_gateway_v1_PipedreamListAccountsForCurrentUserRequest", "responseSchema": "integrations_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person integration self-service or authorized backend delegation. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person integration self-service or authorized backend delegation. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive the subject rather than accept an external-user identity, verify delegated action/account ownership, and maintain the platform integration boundary. Intended audience: App user, Tenant backend. Authenticated person integration self-service or authorized backend delegation.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps)", "slug": "/api/connected-apps/pipedream-delete-account-for-current-user", "method": "POST", "path": "/api/v1/integrations/pipedream/delete-account", "requestSchema": "integrations_v1_services_gateway_v1_PipedreamDeleteAccountForCurrentUserRequest", "responseSchema": "integrations_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person integration self-service or authorized backend delegation. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person integration self-service or authorized backend delegation. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive the subject rather than accept an external-user identity, verify delegated action/account ownership, and maintain the platform integration boundary. Intended audience: App user, Tenant backend. Authenticated person integration self-service or authorized backend delegation.
" } ] }, "runtime_enforcement": false }, { "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 user and associated connections. Use it as one step of offboarding, not as proof of erasure across every provider and backup. Reconnection creates new connection state and requires fresh user authorization.\n\n[`accountsDeleted`](/api/connected-apps/pipedream-delete-external-user-for-current-user#response-field-accountsdeleted) is counted immediately before deletion and can differ under concurrent changes; it is not a per-account deletion receipt. Preserve your application's record of cleanup and unresolved external actions.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps)", "slug": "/api/connected-apps/pipedream-delete-external-user-for-current-user", "method": "POST", "path": "/api/v1/integrations/pipedream/delete-external-user", "requestSchema": "integrations_v1_services_gateway_v1_PipedreamDeleteExternalUserForCurrentUserRequest", "responseSchema": "integrations_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person integration self-service or authorized backend delegation. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person integration self-service or authorized backend delegation. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive the subject rather than accept an external-user identity, verify delegated action/account ownership, and maintain the platform integration boundary. Intended audience: App user, Tenant backend. Authenticated person integration self-service or authorized backend delegation.
" } ] }, "runtime_enforcement": false }, { "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 belong to the effective user and the destination is subject to the provider's allowed-domain rules. Those checks do not replace permission for the requested action. Each upstream app defines its own payload.\n\n### Upstream response handling\n\nRead the returned upstream [`status`](/api/connected-apps/pipedream-proxy-for-current-user#response-field-status) before treating the operation as successful: Travila can return HTTP 200 while the app's response contains a 404. Upstream headers and the [`body`](/api/connected-apps/pipedream-proxy-for-current-user#response-field-body) are returned as data, including on non-success status codes. Decode the body according to its content type; headers and bodies can contain third-party sensitive data.\n\nRedirects are returned, not followed. Treat `Location` as untrusted: it need not be a signed or credential-free download URL. Validate the destination before opening it and never forward platform or account credentials to it.\n\nThe provider request timeout is 30 seconds. Page large results or use an appropriate provider download flow to stay within the response-body limit. A timeout can leave the external action's outcome unknown; check that action before retrying.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps)", "slug": "/api/connected-apps/pipedream-proxy-for-current-user", "method": "POST", "path": "/api/v1/integrations/pipedream/proxy", "requestSchema": "integrations_v1_services_gateway_v1_PipedreamProxyForCurrentUserRequest", "responseSchema": "integrations_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person integration self-service or authorized backend delegation. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person integration self-service or authorized backend delegation. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive the subject rather than accept an external-user identity, verify delegated action/account ownership, and maintain the platform integration boundary. Intended audience: App user, Tenant backend. Authenticated person integration self-service or authorized backend delegation.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Tenant request context, Tenant-scoped webhook ownership.\n\nUse this in a guide: [Event catalog](/api/events) · [Automate recurring agent work](/core-platform/scheduling/build-scheduled-agents) · [Receive a completed order summary in your backend](/integrations/webhooks/endpoints)", "slug": "/api/webhooks/create-webhook-endpoint", "method": "POST", "path": "/api/v1/webhooks/create-endpoint", "requestSchema": "integrations_v1_services_webhookgateway_v1_CreateWebhookEndpointRequest", "responseSchema": "integrations_v1_services_webhookgateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Inherit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended audience: an authenticated tenant backend administering its own tenant webhooks, without switching to a beneficiary identity. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Tenant request context", "mode": "Enforcing", "meaning": "Requires a nonblank tenant context. Requests recognized by the gateway as public ingress derive tenant and optional user from ingress identity headers and ignore body context. Headerless calls may supply tenant, subject and caller context, with caller normalization; header absence itself does not authenticate an internal caller. A user is optional. Roles are logging/audit metadata and RBAC is not enforced.
" }, { "condition_name": "Tenant-scoped webhook ownership", "mode": "Enforcing", "meaning": "WebhookService scopes these endpoint, subscription and delivery operations to the compound owner formed from the accepted tenant and fixed default project. Creation stamps or binds ownership, lists restrict to that owner, and addressed existing resources are checked through endpoint owner metadata or owner-scoped registry lookup. Delivery lists scope to owned live or retained deleted endpoint IDs; delivery retry checks endpoint owner metadata. This is tenant scoping relative to the accepted context, not authenticated authority for headerless supplied tenants, project-level grants or RBAC.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Tenant request context, Tenant-scoped webhook ownership.\n\nUse this in a guide: [Recover a missing backend update](/integrations/webhooks/deliveries) · [Receive a completed order summary in your backend](/integrations/webhooks/endpoints)", "slug": "/api/webhooks/list-webhook-endpoints", "method": "POST", "path": "/api/v1/webhooks/list-endpoints", "requestSchema": "integrations_v1_services_webhookgateway_v1_ListWebhookEndpointsRequest", "responseSchema": "integrations_v1_services_webhookgateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Inherit", "retry_safe": true, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended audience: an authenticated tenant backend administering its own tenant webhooks, without switching to a beneficiary identity. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Tenant request context", "mode": "Enforcing", "meaning": "Requires a nonblank tenant context. Requests recognized by the gateway as public ingress derive tenant and optional user from ingress identity headers and ignore body context. Headerless calls may supply tenant, subject and caller context, with caller normalization; header absence itself does not authenticate an internal caller. A user is optional. Roles are logging/audit metadata and RBAC is not enforced.
" }, { "condition_name": "Tenant-scoped webhook ownership", "mode": "Enforcing", "meaning": "WebhookService scopes these endpoint, subscription and delivery operations to the compound owner formed from the accepted tenant and fixed default project. Creation stamps or binds ownership, lists restrict to that owner, and addressed existing resources are checked through endpoint owner metadata or owner-scoped registry lookup. Delivery lists scope to owned live or retained deleted endpoint IDs; delivery retry checks endpoint owner metadata. This is tenant scoping relative to the accepted context, not authenticated authority for headerless supplied tenants, project-level grants or RBAC.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Tenant request context, Tenant-scoped webhook ownership.\n\nUse this in a guide: [Recover a missing backend update](/integrations/webhooks/deliveries) · [Receive a completed order summary in your backend](/integrations/webhooks/endpoints)", "slug": "/api/webhooks/update-webhook-endpoint", "method": "POST", "path": "/api/v1/webhooks/update-endpoint", "requestSchema": "integrations_v1_services_webhookgateway_v1_UpdateWebhookEndpointRequest", "responseSchema": "integrations_v1_services_webhookgateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Inherit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended audience: an authenticated tenant backend administering its own tenant webhooks, without switching to a beneficiary identity. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Tenant request context", "mode": "Enforcing", "meaning": "Requires a nonblank tenant context. Requests recognized by the gateway as public ingress derive tenant and optional user from ingress identity headers and ignore body context. Headerless calls may supply tenant, subject and caller context, with caller normalization; header absence itself does not authenticate an internal caller. A user is optional. Roles are logging/audit metadata and RBAC is not enforced.
" }, { "condition_name": "Tenant-scoped webhook ownership", "mode": "Enforcing", "meaning": "WebhookService scopes these endpoint, subscription and delivery operations to the compound owner formed from the accepted tenant and fixed default project. Creation stamps or binds ownership, lists restrict to that owner, and addressed existing resources are checked through endpoint owner metadata or owner-scoped registry lookup. Delivery lists scope to owned live or retained deleted endpoint IDs; delivery retry checks endpoint owner metadata. This is tenant scoping relative to the accepted context, not authenticated authority for headerless supplied tenants, project-level grants or RBAC.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Tenant request context, Tenant-scoped webhook ownership.\n\nUse this in a guide: [Receive a completed order summary in your backend](/integrations/webhooks/endpoints)", "slug": "/api/webhooks/delete-webhook-endpoint", "method": "POST", "path": "/api/v1/webhooks/delete-endpoint", "requestSchema": "integrations_v1_services_webhookgateway_v1_DeleteWebhookEndpointRequest", "responseSchema": "integrations_v1_services_webhookgateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Inherit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended audience: an authenticated tenant backend administering its own tenant webhooks, without switching to a beneficiary identity. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Tenant request context", "mode": "Enforcing", "meaning": "Requires a nonblank tenant context. Requests recognized by the gateway as public ingress derive tenant and optional user from ingress identity headers and ignore body context. Headerless calls may supply tenant, subject and caller context, with caller normalization; header absence itself does not authenticate an internal caller. A user is optional. Roles are logging/audit metadata and RBAC is not enforced.
" }, { "condition_name": "Tenant-scoped webhook ownership", "mode": "Enforcing", "meaning": "WebhookService scopes these endpoint, subscription and delivery operations to the compound owner formed from the accepted tenant and fixed default project. Creation stamps or binds ownership, lists restrict to that owner, and addressed existing resources are checked through endpoint owner metadata or owner-scoped registry lookup. Delivery lists scope to owned live or retained deleted endpoint IDs; delivery retry checks endpoint owner metadata. This is tenant scoping relative to the accepted context, not authenticated authority for headerless supplied tenants, project-level grants or RBAC.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Tenant request context, Tenant-scoped webhook ownership.\n\nUse this in a guide: [Event catalog](/api/events) · [Receive a completed order summary in your backend](/integrations/webhooks/endpoints)", "slug": "/api/webhooks/create-webhook-subscription", "method": "POST", "path": "/api/v1/webhooks/create-subscription", "requestSchema": "integrations_v1_services_webhookgateway_v1_CreateWebhookSubscriptionRequest", "responseSchema": "integrations_v1_services_webhookgateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Inherit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended audience: an authenticated tenant backend administering its own tenant webhooks, without switching to a beneficiary identity. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Tenant request context", "mode": "Enforcing", "meaning": "Requires a nonblank tenant context. Requests recognized by the gateway as public ingress derive tenant and optional user from ingress identity headers and ignore body context. Headerless calls may supply tenant, subject and caller context, with caller normalization; header absence itself does not authenticate an internal caller. A user is optional. Roles are logging/audit metadata and RBAC is not enforced.
" }, { "condition_name": "Tenant-scoped webhook ownership", "mode": "Enforcing", "meaning": "WebhookService scopes these endpoint, subscription and delivery operations to the compound owner formed from the accepted tenant and fixed default project. Creation stamps or binds ownership, lists restrict to that owner, and addressed existing resources are checked through endpoint owner metadata or owner-scoped registry lookup. Delivery lists scope to owned live or retained deleted endpoint IDs; delivery retry checks endpoint owner metadata. This is tenant scoping relative to the accepted context, not authenticated authority for headerless supplied tenants, project-level grants or RBAC.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Tenant request context, Tenant-scoped webhook ownership.\n\nUse this in a guide: [Recover a missing backend update](/integrations/webhooks/deliveries) · [Receive a completed order summary in your backend](/integrations/webhooks/endpoints)", "slug": "/api/webhooks/list-webhook-subscriptions", "method": "POST", "path": "/api/v1/webhooks/list-subscriptions", "requestSchema": "integrations_v1_services_webhookgateway_v1_ListWebhookSubscriptionsRequest", "responseSchema": "integrations_v1_services_webhookgateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Inherit", "retry_safe": true, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended audience: an authenticated tenant backend administering its own tenant webhooks, without switching to a beneficiary identity. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Tenant request context", "mode": "Enforcing", "meaning": "Requires a nonblank tenant context. Requests recognized by the gateway as public ingress derive tenant and optional user from ingress identity headers and ignore body context. Headerless calls may supply tenant, subject and caller context, with caller normalization; header absence itself does not authenticate an internal caller. A user is optional. Roles are logging/audit metadata and RBAC is not enforced.
" }, { "condition_name": "Tenant-scoped webhook ownership", "mode": "Enforcing", "meaning": "WebhookService scopes these endpoint, subscription and delivery operations to the compound owner formed from the accepted tenant and fixed default project. Creation stamps or binds ownership, lists restrict to that owner, and addressed existing resources are checked through endpoint owner metadata or owner-scoped registry lookup. Delivery lists scope to owned live or retained deleted endpoint IDs; delivery retry checks endpoint owner metadata. This is tenant scoping relative to the accepted context, not authenticated authority for headerless supplied tenants, project-level grants or RBAC.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Tenant request context, Tenant-scoped webhook ownership.", "slug": "/api/webhooks/delete-webhook-subscription", "method": "POST", "path": "/api/v1/webhooks/delete-subscription", "requestSchema": "integrations_v1_services_webhookgateway_v1_DeleteWebhookSubscriptionRequest", "responseSchema": "integrations_v1_services_webhookgateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Inherit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended audience: an authenticated tenant backend administering its own tenant webhooks, without switching to a beneficiary identity. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Tenant request context", "mode": "Enforcing", "meaning": "Requires a nonblank tenant context. Requests recognized by the gateway as public ingress derive tenant and optional user from ingress identity headers and ignore body context. Headerless calls may supply tenant, subject and caller context, with caller normalization; header absence itself does not authenticate an internal caller. A user is optional. Roles are logging/audit metadata and RBAC is not enforced.
" }, { "condition_name": "Tenant-scoped webhook ownership", "mode": "Enforcing", "meaning": "WebhookService scopes these endpoint, subscription and delivery operations to the compound owner formed from the accepted tenant and fixed default project. Creation stamps or binds ownership, lists restrict to that owner, and addressed existing resources are checked through endpoint owner metadata or owner-scoped registry lookup. Delivery lists scope to owned live or retained deleted endpoint IDs; delivery retry checks endpoint owner metadata. This is tenant scoping relative to the accepted context, not authenticated authority for headerless supplied tenants, project-level grants or RBAC.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Tenant request context, Tenant-scoped webhook ownership.\n\nUse this in a guide: [Recover a missing backend update](/integrations/webhooks/deliveries)", "slug": "/api/webhooks/list-webhook-deliveries", "method": "POST", "path": "/api/v1/webhooks/list-deliveries", "requestSchema": "integrations_v1_services_webhookgateway_v1_ListWebhookDeliveriesRequest", "responseSchema": "integrations_v1_services_webhookgateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Inherit", "retry_safe": true, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended audience: an authenticated tenant backend administering its own tenant webhooks, without switching to a beneficiary identity. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Tenant request context", "mode": "Enforcing", "meaning": "Requires a nonblank tenant context. Requests recognized by the gateway as public ingress derive tenant and optional user from ingress identity headers and ignore body context. Headerless calls may supply tenant, subject and caller context, with caller normalization; header absence itself does not authenticate an internal caller. A user is optional. Roles are logging/audit metadata and RBAC is not enforced.
" }, { "condition_name": "Tenant-scoped webhook ownership", "mode": "Enforcing", "meaning": "WebhookService scopes these endpoint, subscription and delivery operations to the compound owner formed from the accepted tenant and fixed default project. Creation stamps or binds ownership, lists restrict to that owner, and addressed existing resources are checked through endpoint owner metadata or owner-scoped registry lookup. Delivery lists scope to owned live or retained deleted endpoint IDs; delivery retry checks endpoint owner metadata. This is tenant scoping relative to the accepted context, not authenticated authority for headerless supplied tenants, project-level grants or RBAC.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Tenant request context, Tenant-scoped webhook ownership.\n\nUse this in a guide: [Recover a missing backend update](/integrations/webhooks/deliveries)", "slug": "/api/webhooks/retry-webhook-delivery", "method": "POST", "path": "/api/v1/webhooks/retry-delivery", "requestSchema": "integrations_v1_services_webhookgateway_v1_RetryWebhookDeliveryRequest", "responseSchema": "integrations_v1_services_webhookgateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant", "condition_mode": "Inherit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended audience: an authenticated tenant backend administering its own tenant webhooks, without switching to a beneficiary identity. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Tenant request context", "mode": "Enforcing", "meaning": "Requires a nonblank tenant context. Requests recognized by the gateway as public ingress derive tenant and optional user from ingress identity headers and ignore body context. Headerless calls may supply tenant, subject and caller context, with caller normalization; header absence itself does not authenticate an internal caller. A user is optional. Roles are logging/audit metadata and RBAC is not enforced.
" }, { "condition_name": "Tenant-scoped webhook ownership", "mode": "Enforcing", "meaning": "WebhookService scopes these endpoint, subscription and delivery operations to the compound owner formed from the accepted tenant and fixed default project. Creation stamps or binds ownership, lists restrict to that owner, and addressed existing resources are checked through endpoint owner metadata or owner-scoped registry lookup. Delivery lists scope to owned live or retained deleted endpoint IDs; delivery retry checks endpoint owner metadata. This is tenant scoping relative to the accepted context, not authenticated authority for headerless supplied tenants, project-level grants or RBAC.
" } ] }, "runtime_enforcement": false }, { "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 with `ALREADY_EXISTS`; use [update](/api/agent-profiles/update-agent-profile) to replace an existing profile. The store assigns the initial immutable version. The system prompt must be a valid template and every variable spec needs a unique name; otherwise create fails with `400`.\n\nEnabled profiles are immediately selectable. Disabled profiles are omitted from the selection library, and a direct send naming one fails with `ACTIVE_PROFILE_DISABLED`. Queued messages currently take a different fallback path; see [unusable profiles](/managed-agents/conversations/configuration#when-the-active-profile-cannot-be-used).\n\nUse this in a guide: [Build a reusable assistant profile](/managed-agents/profiles-prompts) · [Keep a model on the providers you choose](/managed-agents/model-controls/provider-pinning)", "slug": "/api/agent-profiles/create-agent-profile", "method": "POST", "path": "/api/v1/agent-profiles/create", "requestSchema": "llm_v1_services_agent_profile_v1_CreateAgentProfileRequest", "responseSchema": "llm_v1_services_agent_profile_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Backend-owned tenant-project agent configuration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Model selection access", "mode": "Enforcing", "meaning": "Requested models must be eligible for the platform and tenant. Empty model selections are allowed.
" } ] }, "runtime_enforcement": false }, { "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 version that never existed returns `NOT_FOUND`.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build a reusable assistant profile](/managed-agents/profiles-prompts)", "slug": "/api/agent-profiles/get-agent-profile", "method": "POST", "path": "/api/v1/agent-profiles/get", "requestSchema": "llm_v1_services_agent_profile_v1_GetAgentProfileRequest", "responseSchema": "llm_v1_services_agent_profile_v1_GetAgentProfileResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Profile returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Backend-owned tenant-project agent configuration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive trusted tenant/project and configuration entitlement; use a tenant backend without a user subject; agent tool calls are outside this intended access. Intended audience: Tenant backend. Backend-owned tenant-project agent configuration.
" } ] }, "runtime_enforcement": false }, { "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. For a lightweight selection view, use [library](/api/agent-profiles/get-agent-profile-library), which omits runtime configuration.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build a reusable assistant profile](/managed-agents/profiles-prompts)", "slug": "/api/agent-profiles/list-agent-profiles", "method": "POST", "path": "/api/v1/agent-profiles/list", "requestSchema": "llm_v1_services_agent_profile_v1_ListAgentProfilesRequest", "responseSchema": "llm_v1_services_agent_profile_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Backend-owned tenant-project agent configuration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive trusted tenant/project and configuration entitlement; use a tenant backend without a user subject; agent tool calls are outside this intended access. Intended audience: Tenant backend. Backend-owned tenant-project agent configuration.
" } ] }, "runtime_enforcement": false }, { "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 profile ID remains fixed and the store assigns the version.\n\n**Which fields change**\n\nWithout an [`updateMask`](/api/agent-profiles/update-agent-profile#request-field-updatemask), only the fields the supplied [`profile`](/api/agent-profiles/update-agent-profile#request-field-profile) sets change, and inside `generationConfig` only the sub-fields it sets. Nothing left out is cleared, so clearing a field needs a mask. A mask naming fields changes exactly those, clearing a named field the profile leaves unset; to replace the whole profile, name every field. An update that would leave `name` or `whenToUse` empty is refused with `400`, as is one writing a system prompt that is not a valid template or variable specs without unique names.\n\nUse this in a guide: [Build a reusable assistant profile](/managed-agents/profiles-prompts) · [Keep a model on the providers you choose](/managed-agents/model-controls/provider-pinning) · [Reuse and update shared assistant instructions](/managed-agents/profiles-prompts/prompt-fragments)", "slug": "/api/agent-profiles/update-agent-profile", "method": "POST", "path": "/api/v1/agent-profiles/update", "requestSchema": "llm_v1_services_agent_profile_v1_UpdateAgentProfileRequest", "responseSchema": "llm_v1_services_agent_profile_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Backend-owned tenant-project agent configuration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Model selection access", "mode": "Enforcing", "meaning": "Requested models must be eligible for the platform and tenant. Empty model selections are allowed.
" } ] }, "runtime_enforcement": false }, { "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 still reference it. Resolve dependent conversations before deletion.\n\n* Direct sends on conversations still naming it in [`activeProfileId`](/api/conversations/create-thread#request-field-activeprofileid) fail with `ACTIVE_PROFILE_NOT_FOUND`. Select an enabled replacement or restore the profile. A disabled replacement fails with `ACTIVE_PROFILE_DISABLED`. Queued messages can fall back to defaults and log the problem; see [unusable profiles](/managed-agents/conversations/configuration#when-the-active-profile-cannot-be-used).\n* Historical version records remain. Their retention does not prove that every dependent turn remains reproducible.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build a reusable assistant profile](/managed-agents/profiles-prompts)", "slug": "/api/agent-profiles/delete-agent-profile", "method": "POST", "path": "/api/v1/agent-profiles/delete", "requestSchema": "llm_v1_services_agent_profile_v1_DeleteAgentProfileRequest", "responseSchema": "llm_v1_services_agent_profile_v1_DeleteAgentProfileResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Profile deleted", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Backend-owned tenant-project agent configuration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive trusted tenant/project and configuration entitlement; use a tenant backend without a user subject; agent tool calls are outside this intended access. Intended audience: Tenant backend. Backend-owned tenant-project agent configuration.
" } ] }, "runtime_enforcement": false }, { "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 selection metadata omits runtime configuration; use [get](/api/agent-profiles/get-agent-profile) to inspect or edit a full profile. This discovery projection neither proves that an autonomous router is active nor guarantees a measured cost or latency improvement.\n\nFor a native conversation, pass the chosen profile ID through `activeProfileId` on thread creation or `setActiveProfileId` when sending a message; Travila loads its configuration. The returned `defaultProfileId` is not applied automatically when `activeProfileId` is empty. Your client must explicitly select its intended profile.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build a reusable assistant profile](/managed-agents/profiles-prompts)", "slug": "/api/agent-profiles/get-agent-profile-library", "method": "POST", "path": "/api/v1/agent-profiles/library", "requestSchema": "llm_v1_services_agent_profile_v1_GetAgentProfileLibraryRequest", "responseSchema": "llm_v1_services_agent_profile_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Backend-owned tenant-project agent configuration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive trusted tenant/project and configuration entitlement; use a tenant backend without a user subject; agent tool calls are outside this intended access. Intended audience: Tenant backend. Backend-owned tenant-project agent configuration.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build a reusable assistant profile](/managed-agents/profiles-prompts)", "slug": "/api/agent-profiles/list-agent-profile-versions", "method": "POST", "path": "/api/v1/agent-profiles/versions", "requestSchema": "llm_v1_services_agent_profile_v1_ListAgentProfileVersionsRequest", "responseSchema": "llm_v1_services_agent_profile_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Backend-owned tenant-project agent configuration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive trusted tenant/project and configuration entitlement; use a tenant backend without a user subject; agent tool calls are outside this intended access. Intended audience: Tenant backend. Backend-owned tenant-project agent configuration.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Reuse and update shared assistant instructions](/managed-agents/profiles-prompts/prompt-fragments) · [Profile selection and prompt versions](/api/agent-profiles/selection-and-versioning)", "slug": "/api/agent-profiles/get-prompt-fragment-set", "method": "POST", "path": "/api/v1/prompt-fragments/get-set", "requestSchema": "llm_v1_services_agent_profile_v1_GetPromptFragmentSetRequest", "responseSchema": "llm_v1_services_agent_profile_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Backend-owned tenant-project agent configuration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive trusted tenant/project and configuration entitlement; use a tenant backend without a user subject; agent tool calls are outside this intended access. Intended audience: Tenant backend. Backend-owned tenant-project agent configuration.
" } ] }, "runtime_enforcement": false }, { "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 unique within that project. Profiles that include the fragment share the stored text, so a later edit affects every referencing profile.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Reuse and update shared assistant instructions](/managed-agents/profiles-prompts/prompt-fragments)", "slug": "/api/agent-profiles/create-prompt-fragment", "method": "POST", "path": "/api/v1/prompt-fragments/create", "requestSchema": "llm_v1_services_agent_profile_v1_CreatePromptFragmentRequest", "responseSchema": "llm_v1_services_agent_profile_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Backend-owned tenant-project agent configuration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive trusted tenant/project and configuration entitlement; use a tenant backend without a user subject; agent tool calls are outside this intended access. Intended audience: Tenant backend. Backend-owned tenant-project agent configuration.
" } ] }, "runtime_enforcement": false }, { "key": "agent-profiles:getPromptFragment", "operationId": "getPromptFragment", "bundle": "agent-profiles.yaml", "title": "Get a prompt fragment", "description": "Returns one fragment by id.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Reuse and update shared assistant instructions](/managed-agents/profiles-prompts/prompt-fragments)", "slug": "/api/agent-profiles/get-prompt-fragment", "method": "POST", "path": "/api/v1/prompt-fragments/get", "requestSchema": "llm_v1_services_agent_profile_v1_GetPromptFragmentRequest", "responseSchema": "llm_v1_services_agent_profile_v1_GetPromptFragmentResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Fragment returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Backend-owned tenant-project agent configuration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive trusted tenant/project and configuration entitlement; use a tenant backend without a user subject; agent tool calls are outside this intended access. Intended audience: Tenant backend. Backend-owned tenant-project agent configuration.
" } ] }, "runtime_enforcement": false }, { "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 fragment-set version.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Reuse and update shared assistant instructions](/managed-agents/profiles-prompts/prompt-fragments)", "slug": "/api/agent-profiles/list-prompt-fragments", "method": "POST", "path": "/api/v1/prompt-fragments/list", "requestSchema": "llm_v1_services_agent_profile_v1_ListPromptFragmentsRequest", "responseSchema": "llm_v1_services_agent_profile_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Backend-owned tenant-project agent configuration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive trusted tenant/project and configuration entitlement; use a tenant backend without a user subject; agent tool calls are outside this intended access. Intended audience: Tenant backend. Backend-owned tenant-project agent configuration.
" } ] }, "runtime_enforcement": false }, { "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), using 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 increments the project-wide fragment-set version. There is no per-profile rollout.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Reuse and update shared assistant instructions](/managed-agents/profiles-prompts/prompt-fragments)", "slug": "/api/agent-profiles/update-prompt-fragment", "method": "POST", "path": "/api/v1/prompt-fragments/update", "requestSchema": "llm_v1_services_agent_profile_v1_UpdatePromptFragmentRequest", "responseSchema": "llm_v1_services_agent_profile_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Backend-owned tenant-project agent configuration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive trusted tenant/project and configuration entitlement; use a tenant backend without a user subject; agent tool calls are outside this intended access. Intended audience: Tenant backend. Backend-owned tenant-project agent configuration.
" } ] }, "runtime_enforcement": false }, { "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 other reachable-template errors; its caller can then return the original prompt.\n\n**Deleting does not rewrite the profiles that include it**\n\nA missing fragment can leave the system prompt unrendered, so literal `{{template \"safety\" .}}` text reaches the model. Generation may continue with that raw template; this is not a validated or safe fallback, and a successful response does not prove that the intended instructions were rendered. Other failures can still stop the turn.\n\nCheck dependencies before removal: page through all profiles and inspect their [`generationConfig.systemPrompt`](/api/models/schema-1h82h7ri5p#request-field-systemprompt) values, then check nested fragment includes too. Checking one page or only direct includes can miss a dependent profile.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Reuse and update shared assistant instructions](/managed-agents/profiles-prompts/prompt-fragments)", "slug": "/api/agent-profiles/delete-prompt-fragment", "method": "POST", "path": "/api/v1/prompt-fragments/delete", "requestSchema": "llm_v1_services_agent_profile_v1_DeletePromptFragmentRequest", "responseSchema": "llm_v1_services_agent_profile_v1_DeletePromptFragmentResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Fragment deleted", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Backend-owned tenant-project agent configuration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive trusted tenant/project and configuration entitlement; use a tenant backend without a user subject; agent tool calls are outside this intended access. Intended audience: Tenant backend. Backend-owned tenant-project agent configuration.
" } ] }, "runtime_enforcement": false }, { "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. Conversion happens at import time: prompts are rewritten to the platform template syntax and variable specifications are derived from usage. The platform never interprets the source DSL when serving a turn.\n\nExisting rows cause the import to stop at the first conflict with `ALREADY_EXISTS`, unless overwrite is enabled. In overwrite mode, existing profiles and fragments are replaced. Writes apply fragments before profiles and are not atomic across rows: a later failure can leave earlier writes in place. Re-read the library and reconcile it before retrying.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build a reusable assistant profile](/managed-agents/profiles-prompts)", "slug": "/api/agent-profiles/import-agent-profiles", "method": "POST", "path": "/api/v1/agent-profiles/import", "requestSchema": "llm_v1_services_agent_profile_v1_ImportAgentProfilesRequest", "responseSchema": "llm_v1_services_agent_profile_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended use: Backend-owned tenant-project agent configuration. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive trusted tenant/project and configuration entitlement; use a tenant backend without a user subject; agent tool calls are outside this intended access. Intended audience: Tenant backend. Backend-owned tenant-project agent configuration.
" } ] }, "runtime_enforcement": false }, { "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 the 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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build an agent preferences screen](/core-platform/identity-access/end-users)", "slug": "/api/end-users/update-location", "method": "POST", "path": "/api/v1/enduser/update-location", "requestSchema": "platform_v1_services_enduser_gateway_v1_UpdateLocationRequest", "responseSchema": "platform_v1_services_enduser_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: End-user self-service for the verified user only. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive identity from ingress and reject writes/reads for other users; the current scope uses the default project. Intended audience: App user. End-user self-service for the verified user only.
" } ] }, "runtime_enforcement": false }, { "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 locale supplied by the identity provider.\n\nSend an **empty string** to clear the override and fall back to the identity-provider locale.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build an agent preferences screen](/core-platform/identity-access/end-users)", "slug": "/api/end-users/update-locale", "method": "POST", "path": "/api/v1/enduser/update-locale", "requestSchema": "platform_v1_services_enduser_gateway_v1_UpdateLocaleRequest", "responseSchema": "platform_v1_services_enduser_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: End-user self-service for the verified user only. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive identity from ingress and reject writes/reads for other users; the current scope uses the default project. Intended audience: App user. End-user self-service for the verified user only.
" } ] }, "runtime_enforcement": false }, { "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 left unset by the selected per-send, profile or conversation configuration; already set values remain unchanged. Explicitly present sampling values, including zero, preserve their presence. Model/provider support determines which accepted controls affect a response.\n\nOnly user-settable controls are accepted. A recognized operational setting or a model outside the platform allowlist fails the whole request; settings are not silently removed to make a config acceptable. Read the saved profile after an update rather than assuming every submitted setting took effect.\n\nUse this in a guide: [Build an agent preferences screen](/core-platform/identity-access/end-users)", "slug": "/api/end-users/update-default-generation-config", "method": "POST", "path": "/api/v1/enduser/update-generation-config", "requestSchema": "platform_v1_services_enduser_gateway_v1_UpdateDefaultGenerationConfigRequest", "responseSchema": "platform_v1_services_enduser_v1_UpdateDefaultGenerationConfigResponse", "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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: End-user self-service for the verified user only. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Model selection access", "mode": "Enforcing", "meaning": "Requested models must be eligible for the platform and tenant. Empty model selections are allowed.
" } ] }, "runtime_enforcement": false }, { "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, send it with an empty-string value.\n\nThe request examples below show setting metadata values and deleting `dismissedWelcome` with an empty string. If you send `{\"preferredView\":\"compact\",\"dismissedWelcome\":\"\"}` as the metadata map, `preferredView` is overwritten, `dismissedWelcome` is deleted, and an omitted key such as `referralCode` is left untouched.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build an agent preferences screen](/core-platform/identity-access/end-users)", "slug": "/api/end-users/update-metadata", "method": "POST", "path": "/api/v1/enduser/update-metadata", "requestSchema": "platform_v1_services_enduser_gateway_v1_UpdateMetadataRequest", "responseSchema": "platform_v1_services_enduser_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: End-user self-service for the verified user only. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive identity from ingress and reject writes/reads for other users; the current scope uses the default project. Intended audience: App user. End-user self-service for the verified user only.
" } ] }, "runtime_enforcement": false }, { "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 identity provider, profile settings the user has set, and lifecycle timestamps.\n\n**A user with no profile is not a 404**\n\nIf no row exists yet, the call still succeeds and returns an empty [`endUser`](/api/end-users/get-end-user#response-field-enduser) object. Treat \"no profile yet\" and \"profile with no overrides\" identically — do not branch on the difference when choosing settings. Treat the missing profile as an absent record; default-valued fields alone do not prove that an account exists or that deletion completed.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build an agent preferences screen](/core-platform/identity-access/end-users)", "slug": "/api/end-users/get-end-user", "method": "POST", "path": "/api/v1/enduser/get", "requestSchema": "platform_v1_services_enduser_gateway_v1_GetEndUserRequest", "responseSchema": "platform_v1_services_enduser_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: End-user self-service for the verified user only. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Derive identity from ingress and reject writes/reads for other users; the current scope uses the default project. Intended audience: App user. End-user self-service for the verified user only.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized tenant project secret administration.\n\nUse this in a guide: [Connect a private tool without putting its credential in prompts](/core-platform/secrets) · [Answer questions about a website using your own Firecrawl account](/integrations/tools-connections/custom-mcp-servers) · [Secret values and credential references](/api/secrets/credentials)", "slug": "/api/secrets/put-secret", "method": "POST", "path": "/api/v1/secrets/put", "requestSchema": "platform_v1_services_secretmanager_v1_PutSecretRequest", "responseSchema": "platform_v1_services_secretmanager_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended audience: an authenticated tenant backend administering project secrets. Any user identity is retained for audit and does not switch the operation to person-owned credentials.
" } ], "access_conditions": [ { "condition_name": "Authorized tenant project secret administration", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: authenticate the tenant backend, derive tenant/project only from trusted context, authorize this secret-management action in that project, and expose metadata only. Tenant/project headers are read from the request context; this alone does not establish the full authorization boundary.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized tenant project secret administration.\n\nUse this in a guide: [Answer questions about a website using your own Firecrawl account](/integrations/tools-connections/custom-mcp-servers) · [Secret values and credential references](/api/secrets/credentials)", "slug": "/api/secrets/get-secret-metadata", "method": "POST", "path": "/api/v1/secrets/get-metadata", "requestSchema": "platform_v1_services_secretmanager_v1_GetSecretMetadataRequest", "responseSchema": "platform_v1_services_secretmanager_v1_GetSecretMetadataResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Metadata returned", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": true, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended audience: an authenticated tenant backend administering project secrets. Any user identity is retained for audit and does not switch the operation to person-owned credentials.
" } ], "access_conditions": [ { "condition_name": "Authorized tenant project secret administration", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: authenticate the tenant backend, derive tenant/project only from trusted context, authorize this secret-management action in that project, and expose metadata only. Tenant/project headers are read from the request context; this alone does not establish the full authorization boundary.
" } ] }, "runtime_enforcement": false }, { "key": "secrets:listSecrets", "operationId": "listSecrets", "bundle": "secrets.yaml", "title": "List secrets", "description": "Returns metadata for every secret in the project, paginated. Values are not included, and there is no parameter that would include them.\n\nSend `{}` for the first page at the server's default size.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized tenant project secret administration.\n\nUse this in a guide: [Secret values and credential references](/api/secrets/credentials)", "slug": "/api/secrets/list-secrets", "method": "POST", "path": "/api/v1/secrets/list", "requestSchema": "platform_v1_services_secretmanager_v1_ListSecretsRequest", "responseSchema": "platform_v1_services_secretmanager_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": true, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended audience: an authenticated tenant backend administering project secrets. Any user identity is retained for audit and does not switch the operation to person-owned credentials.
" } ], "access_conditions": [ { "condition_name": "Authorized tenant project secret administration", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: authenticate the tenant backend, derive tenant/project only from trusted context, authorize this secret-management action in that project, and expose metadata only. Tenant/project headers are read from the request context; this alone does not establish the full authorization boundary.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized tenant project secret administration.\n\nUse this in a guide: [Connect a private tool without putting its credential in prompts](/core-platform/secrets) · [Answer questions about a website using your own Firecrawl account](/integrations/tools-connections/custom-mcp-servers) · [Secret values and credential references](/api/secrets/credentials)", "slug": "/api/secrets/delete-secret", "method": "POST", "path": "/api/v1/secrets/delete", "requestSchema": "platform_v1_services_secretmanager_v1_DeleteSecretRequest", "responseSchema": "platform_v1_services_secretmanager_v1_DeleteSecretResponse", "mediaType": "application/json", "responseStatus": "200", "responseDescription": "Delete processed", "requestBodyRequired": true, "errors": {}, "security": [ { "apiKeyAuth": [] } ], "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Tenant", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "Tenant backend", "meaning": "Intended audience: an authenticated tenant backend administering project secrets. Any user identity is retained for audit and does not switch the operation to person-owned credentials.
" } ], "access_conditions": [ { "condition_name": "Authorized tenant project secret administration", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: authenticate the tenant backend, derive tenant/project only from trusted context, authorize this secret-management action in that project, and expose metadata only. Tenant/project headers are read from the request context; this alone does not establish the full authorization boundary.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing.\n\nUse this in a guide: [Organize a customer’s project documents](/core-platform/files-data/folders)", "slug": "/api/storage/create-folder", "method": "POST", "path": "/api/v1/storage/create-folder", "requestSchema": "storage_v1_services_gateway_v1_CreateFolderRequest", "responseSchema": "storage_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Inherit", "retry_safe": true, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended audience: an authenticated person using their own storage. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended audience: an authorized tenant backend acting for a verified person beneficiary. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Accepted storage owner context", "mode": "Enforcing", "meaning": "Every gateway handler builds owner context. A request recognized by nonblank x-auth-method, x-user-id or x-tenant-id header derives identity only from required user and tenant headers and ignores body context. Headerless calls may supply tenant and Subject, with CallerKey used when Subject is absent; otherwise required header derivation is attempted. Header absence does not authenticate an internal caller. These are existing manual branches, not a new trusted-only boundary or a platform-composite adapter.
" }, { "condition_name": "Storage owner actor routing", "mode": "Enforcing", "meaning": "Every operation addresses the StorageManager actor using that accepted context owner. Public-header identity becomes tenant:default:user. Headerless supplied Subject or CallerKey is tenant-prefixed and passed through the existing unvalidated default-project insertion helper, including its colon-containing-key behavior. The addressed actor state, file lookups and normalized paths supply the current owner boundary; the actor performs no independent caller authorization. Tenant scope here describes the accepted tenant namespace with fixed default project, not authenticated authority for supplied identity, independent project grants or validated/injective segment encoding.
" } ] }, "runtime_enforcement": false }, { "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 does not require an empty folder. This option cannot safely test whether the project still contains documents.\n\nWith `recursive: true`, it also attempts descendant file and folder deletion. A failure can follow earlier object deletions, so inspect the resulting state before recovery.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing.\n\nUse this in a guide: [Organize a customer’s project documents](/core-platform/files-data/folders)", "slug": "/api/storage/delete-folder", "method": "POST", "path": "/api/v1/storage/delete-folder", "requestSchema": "storage_v1_services_gateway_v1_DeleteFolderRequest", "responseSchema": "storage_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Inherit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended audience: an authenticated person using their own storage. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended audience: an authorized tenant backend acting for a verified person beneficiary. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Accepted storage owner context", "mode": "Enforcing", "meaning": "Every gateway handler builds owner context. A request recognized by nonblank x-auth-method, x-user-id or x-tenant-id header derives identity only from required user and tenant headers and ignores body context. Headerless calls may supply tenant and Subject, with CallerKey used when Subject is absent; otherwise required header derivation is attempted. Header absence does not authenticate an internal caller. These are existing manual branches, not a new trusted-only boundary or a platform-composite adapter.
" }, { "condition_name": "Storage owner actor routing", "mode": "Enforcing", "meaning": "Every operation addresses the StorageManager actor using that accepted context owner. Public-header identity becomes tenant:default:user. Headerless supplied Subject or CallerKey is tenant-prefixed and passed through the existing unvalidated default-project insertion helper, including its colon-containing-key behavior. The addressed actor state, file lookups and normalized paths supply the current owner boundary; the actor performs no independent caller authorization. Tenant scope here describes the accepted tenant namespace with fixed default project, not authenticated authority for supplied identity, independent project grants or validated/injective segment encoding.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing.\n\nUse this in a guide: [Build a searchable document library](/core-platform/files-data/managing)", "slug": "/api/storage/list-files", "method": "POST", "path": "/api/v1/storage/list-files", "requestSchema": "storage_v1_services_gateway_v1_ListFilesRequest", "responseSchema": "storage_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Inherit", "retry_safe": true, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended audience: an authenticated person using their own storage. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended audience: an authorized tenant backend acting for a verified person beneficiary. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Accepted storage owner context", "mode": "Enforcing", "meaning": "Every gateway handler builds owner context. A request recognized by nonblank x-auth-method, x-user-id or x-tenant-id header derives identity only from required user and tenant headers and ignores body context. Headerless calls may supply tenant and Subject, with CallerKey used when Subject is absent; otherwise required header derivation is attempted. Header absence does not authenticate an internal caller. These are existing manual branches, not a new trusted-only boundary or a platform-composite adapter.
" }, { "condition_name": "Storage owner actor routing", "mode": "Enforcing", "meaning": "Every operation addresses the StorageManager actor using that accepted context owner. Public-header identity becomes tenant:default:user. Headerless supplied Subject or CallerKey is tenant-prefixed and passed through the existing unvalidated default-project insertion helper, including its colon-containing-key behavior. The addressed actor state, file lookups and normalized paths supply the current owner boundary; the actor performs no independent caller authorization. Tenant scope here describes the accepted tenant namespace with fixed default project, not authenticated authority for supplied identity, independent project grants or validated/injective segment encoding.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing.\n\nUse this in a guide: [Add file attachments to a support request](/core-platform/files-data/files)", "slug": "/api/storage/upload-file", "method": "POST", "path": "/api/v1/storage/upload-file", "requestSchema": "storage_v1_services_gateway_v1_UploadFileRequest", "responseSchema": "storage_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Deprecated", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Inherit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended audience: an authenticated person using their own storage. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended audience: an authorized tenant backend acting for a verified person beneficiary. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Accepted storage owner context", "mode": "Enforcing", "meaning": "Every gateway handler builds owner context. A request recognized by nonblank x-auth-method, x-user-id or x-tenant-id header derives identity only from required user and tenant headers and ignores body context. Headerless calls may supply tenant and Subject, with CallerKey used when Subject is absent; otherwise required header derivation is attempted. Header absence does not authenticate an internal caller. These are existing manual branches, not a new trusted-only boundary or a platform-composite adapter.
" }, { "condition_name": "Storage owner actor routing", "mode": "Enforcing", "meaning": "Every operation addresses the StorageManager actor using that accepted context owner. Public-header identity becomes tenant:default:user. Headerless supplied Subject or CallerKey is tenant-prefixed and passed through the existing unvalidated default-project insertion helper, including its colon-containing-key behavior. The addressed actor state, file lookups and normalized paths supply the current owner boundary; the actor performs no independent caller authorization. Tenant scope here describes the accepted tenant namespace with fixed default project, not authenticated authority for supplied identity, independent project grants or validated/injective segment encoding.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing.\n\nUse this in a guide: [Build a searchable document library](/core-platform/files-data/managing)", "slug": "/api/storage/delete-file", "method": "POST", "path": "/api/v1/storage/delete-file", "requestSchema": "storage_v1_services_gateway_v1_DeleteFileRequest", "responseSchema": "storage_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Inherit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended audience: an authenticated person using their own storage. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended audience: an authorized tenant backend acting for a verified person beneficiary. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Accepted storage owner context", "mode": "Enforcing", "meaning": "Every gateway handler builds owner context. A request recognized by nonblank x-auth-method, x-user-id or x-tenant-id header derives identity only from required user and tenant headers and ignores body context. Headerless calls may supply tenant and Subject, with CallerKey used when Subject is absent; otherwise required header derivation is attempted. Header absence does not authenticate an internal caller. These are existing manual branches, not a new trusted-only boundary or a platform-composite adapter.
" }, { "condition_name": "Storage owner actor routing", "mode": "Enforcing", "meaning": "Every operation addresses the StorageManager actor using that accepted context owner. Public-header identity becomes tenant:default:user. Headerless supplied Subject or CallerKey is tenant-prefixed and passed through the existing unvalidated default-project insertion helper, including its colon-containing-key behavior. The addressed actor state, file lookups and normalized paths supply the current owner boundary; the actor performs no independent caller authorization. Tenant scope here describes the accepted tenant namespace with fixed default project, not authenticated authority for supplied identity, independent project grants or validated/injective segment encoding.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing.\n\nUse this in a guide: [Build a searchable document library](/core-platform/files-data/managing)", "slug": "/api/storage/move-file", "method": "POST", "path": "/api/v1/storage/move-file", "requestSchema": "storage_v1_services_gateway_v1_MoveFileRequest", "responseSchema": "storage_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Inherit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended audience: an authenticated person using their own storage. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended audience: an authorized tenant backend acting for a verified person beneficiary. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Accepted storage owner context", "mode": "Enforcing", "meaning": "Every gateway handler builds owner context. A request recognized by nonblank x-auth-method, x-user-id or x-tenant-id header derives identity only from required user and tenant headers and ignores body context. Headerless calls may supply tenant and Subject, with CallerKey used when Subject is absent; otherwise required header derivation is attempted. Header absence does not authenticate an internal caller. These are existing manual branches, not a new trusted-only boundary or a platform-composite adapter.
" }, { "condition_name": "Storage owner actor routing", "mode": "Enforcing", "meaning": "Every operation addresses the StorageManager actor using that accepted context owner. Public-header identity becomes tenant:default:user. Headerless supplied Subject or CallerKey is tenant-prefixed and passed through the existing unvalidated default-project insertion helper, including its colon-containing-key behavior. The addressed actor state, file lookups and normalized paths supply the current owner boundary; the actor performs no independent caller authorization. Tenant scope here describes the accepted tenant namespace with fixed default project, not authenticated authority for supplied identity, independent project grants or validated/injective segment encoding.
" } ] }, "runtime_enforcement": false }, { "key": "storage:getFileMetadata", "operationId": "getFileMetadata", "bundle": "storage.yaml", "title": "Get file metadata", "description": "Retrieves a file's tracked metadata without downloading its content.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing.\n\nUse this in a guide: [Build a searchable document library](/core-platform/files-data/managing)", "slug": "/api/storage/get-file-metadata", "method": "POST", "path": "/api/v1/storage/get-file-metadata", "requestSchema": "storage_v1_services_gateway_v1_GetFileMetadataRequest", "responseSchema": "storage_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Inherit", "retry_safe": true, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended audience: an authenticated person using their own storage. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended audience: an authorized tenant backend acting for a verified person beneficiary. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Accepted storage owner context", "mode": "Enforcing", "meaning": "Every gateway handler builds owner context. A request recognized by nonblank x-auth-method, x-user-id or x-tenant-id header derives identity only from required user and tenant headers and ignores body context. Headerless calls may supply tenant and Subject, with CallerKey used when Subject is absent; otherwise required header derivation is attempted. Header absence does not authenticate an internal caller. These are existing manual branches, not a new trusted-only boundary or a platform-composite adapter.
" }, { "condition_name": "Storage owner actor routing", "mode": "Enforcing", "meaning": "Every operation addresses the StorageManager actor using that accepted context owner. Public-header identity becomes tenant:default:user. Headerless supplied Subject or CallerKey is tenant-prefixed and passed through the existing unvalidated default-project insertion helper, including its colon-containing-key behavior. The addressed actor state, file lookups and normalized paths supply the current owner boundary; the actor performs no independent caller authorization. Tenant scope here describes the accepted tenant namespace with fixed default project, not authenticated authority for supplied identity, independent project grants or validated/injective segment encoding.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing.\n\nUse this in a guide: [Build a searchable document library](/core-platform/files-data/managing)", "slug": "/api/storage/update-file-metadata", "method": "POST", "path": "/api/v1/storage/update-file-metadata", "requestSchema": "storage_v1_services_gateway_v1_UpdateFileMetadataRequest", "responseSchema": "storage_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Inherit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended audience: an authenticated person using their own storage. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended audience: an authorized tenant backend acting for a verified person beneficiary. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Accepted storage owner context", "mode": "Enforcing", "meaning": "Every gateway handler builds owner context. A request recognized by nonblank x-auth-method, x-user-id or x-tenant-id header derives identity only from required user and tenant headers and ignores body context. Headerless calls may supply tenant and Subject, with CallerKey used when Subject is absent; otherwise required header derivation is attempted. Header absence does not authenticate an internal caller. These are existing manual branches, not a new trusted-only boundary or a platform-composite adapter.
" }, { "condition_name": "Storage owner actor routing", "mode": "Enforcing", "meaning": "Every operation addresses the StorageManager actor using that accepted context owner. Public-header identity becomes tenant:default:user. Headerless supplied Subject or CallerKey is tenant-prefixed and passed through the existing unvalidated default-project insertion helper, including its colon-containing-key behavior. The addressed actor state, file lookups and normalized paths supply the current owner boundary; the actor performs no independent caller authorization. Tenant scope here describes the accepted tenant namespace with fixed default project, not authenticated authority for supplied identity, independent project grants or validated/injective segment encoding.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing.\n\nUse this in a guide: [Build a searchable document library](/core-platform/files-data/managing)", "slug": "/api/storage/get-storage-quota", "method": "POST", "path": "/api/v1/storage/get-storage-quota", "requestSchema": "storage_v1_services_gateway_v1_GetStorageQuotaRequest", "responseSchema": "storage_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Inherit", "retry_safe": true, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended audience: an authenticated person using their own storage. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended audience: an authorized tenant backend acting for a verified person beneficiary. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Accepted storage owner context", "mode": "Enforcing", "meaning": "Every gateway handler builds owner context. A request recognized by nonblank x-auth-method, x-user-id or x-tenant-id header derives identity only from required user and tenant headers and ignores body context. Headerless calls may supply tenant and Subject, with CallerKey used when Subject is absent; otherwise required header derivation is attempted. Header absence does not authenticate an internal caller. These are existing manual branches, not a new trusted-only boundary or a platform-composite adapter.
" }, { "condition_name": "Storage owner actor routing", "mode": "Enforcing", "meaning": "Every operation addresses the StorageManager actor using that accepted context owner. Public-header identity becomes tenant:default:user. Headerless supplied Subject or CallerKey is tenant-prefixed and passed through the existing unvalidated default-project insertion helper, including its colon-containing-key behavior. The addressed actor state, file lookups and normalized paths supply the current owner boundary; the actor performs no independent caller authorization. Tenant scope here describes the accepted tenant namespace with fixed default project, not authenticated authority for supplied identity, independent project grants or validated/injective segment encoding.
" } ] }, "runtime_enforcement": false }, { "key": "storage:searchFiles", "operationId": "searchFiles", "bundle": "storage.yaml", "title": "Search files", "description": "Searches the effective user's tracked files using a case-insensitive filename substring or a case-insensitive complete tag. File contents, such as text inside a PDF, are not searched.\n\nSupported `FileFilter` fields narrow candidates before the query is applied, and all listed tags must be present. The date filters [`uploadedAfter`](/api/models/schema-oq26kmqtvq#request-field-uploadedafter) and [`uploadedBefore`](/api/models/schema-oq26kmqtvq#request-field-uploadedbefore) are accepted but currently not enforced; do not offer a date range as an effective filter.\n\n[`maxResults`](/api/storage/search-files#request-field-maxresults) caps a single response; search does not paginate. If results are too broad, let the customer refine the name, tag or folder rather than promising a complete result set.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing.\n\nUse this in a guide: [Build a searchable document library](/core-platform/files-data/managing)", "slug": "/api/storage/search-files", "method": "POST", "path": "/api/v1/storage/search-files", "requestSchema": "storage_v1_services_gateway_v1_SearchFilesRequest", "responseSchema": "storage_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Inherit", "retry_safe": true, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended audience: an authenticated person using their own storage. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended audience: an authorized tenant backend acting for a verified person beneficiary. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Accepted storage owner context", "mode": "Enforcing", "meaning": "Every gateway handler builds owner context. A request recognized by nonblank x-auth-method, x-user-id or x-tenant-id header derives identity only from required user and tenant headers and ignores body context. Headerless calls may supply tenant and Subject, with CallerKey used when Subject is absent; otherwise required header derivation is attempted. Header absence does not authenticate an internal caller. These are existing manual branches, not a new trusted-only boundary or a platform-composite adapter.
" }, { "condition_name": "Storage owner actor routing", "mode": "Enforcing", "meaning": "Every operation addresses the StorageManager actor using that accepted context owner. Public-header identity becomes tenant:default:user. Headerless supplied Subject or CallerKey is tenant-prefixed and passed through the existing unvalidated default-project insertion helper, including its colon-containing-key behavior. The addressed actor state, file lookups and normalized paths supply the current owner boundary; the actor performs no independent caller authorization. Tenant scope here describes the accepted tenant namespace with fixed default project, not authenticated authority for supplied identity, independent project grants or validated/injective segment encoding.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing.\n\nUse this in a guide: [Add file attachments to a support request](/core-platform/files-data/files) · [Organize a customer’s project documents](/core-platform/files-data/folders) · [Summarize a customer’s uploaded report](/managed-agents/conversations/attachments) · [Build a signed-in support chat that survives reconnects](/managed-agents/conversations/build-chat-assistant)", "slug": "/api/storage/generate-upload-url", "method": "POST", "path": "/api/v1/storage/generate-upload-url", "requestSchema": "storage_v1_services_gateway_v1_GenerateUploadUrlRequest", "responseSchema": "storage_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Inherit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended audience: an authenticated person using their own storage. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended audience: an authorized tenant backend acting for a verified person beneficiary. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Accepted storage owner context", "mode": "Enforcing", "meaning": "Every gateway handler builds owner context. A request recognized by nonblank x-auth-method, x-user-id or x-tenant-id header derives identity only from required user and tenant headers and ignores body context. Headerless calls may supply tenant and Subject, with CallerKey used when Subject is absent; otherwise required header derivation is attempted. Header absence does not authenticate an internal caller. These are existing manual branches, not a new trusted-only boundary or a platform-composite adapter.
" }, { "condition_name": "Storage owner actor routing", "mode": "Enforcing", "meaning": "Every operation addresses the StorageManager actor using that accepted context owner. Public-header identity becomes tenant:default:user. Headerless supplied Subject or CallerKey is tenant-prefixed and passed through the existing unvalidated default-project insertion helper, including its colon-containing-key behavior. The addressed actor state, file lookups and normalized paths supply the current owner boundary; the actor performs no independent caller authorization. Tenant scope here describes the accepted tenant namespace with fixed default project, not authenticated authority for supplied identity, independent project grants or validated/injective segment encoding.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing.\n\nUse this in a guide: [Add file attachments to a support request](/core-platform/files-data/files) · [Organize a customer’s project documents](/core-platform/files-data/folders) · [Upload registration and URL expiry](/api/storage/uploads)", "slug": "/api/storage/register-uploaded-file", "method": "POST", "path": "/api/v1/storage/register-uploaded-file", "requestSchema": "storage_v1_services_gateway_v1_RegisterUploadedFileRequest", "responseSchema": "storage_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Inherit", "retry_safe": true, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended audience: an authenticated person using their own storage. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended audience: an authorized tenant backend acting for a verified person beneficiary. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Accepted storage owner context", "mode": "Enforcing", "meaning": "Every gateway handler builds owner context. A request recognized by nonblank x-auth-method, x-user-id or x-tenant-id header derives identity only from required user and tenant headers and ignores body context. Headerless calls may supply tenant and Subject, with CallerKey used when Subject is absent; otherwise required header derivation is attempted. Header absence does not authenticate an internal caller. These are existing manual branches, not a new trusted-only boundary or a platform-composite adapter.
" }, { "condition_name": "Storage owner actor routing", "mode": "Enforcing", "meaning": "Every operation addresses the StorageManager actor using that accepted context owner. Public-header identity becomes tenant:default:user. Headerless supplied Subject or CallerKey is tenant-prefixed and passed through the existing unvalidated default-project insertion helper, including its colon-containing-key behavior. The addressed actor state, file lookups and normalized paths supply the current owner boundary; the actor performs no independent caller authorization. Tenant scope here describes the accepted tenant namespace with fixed default project, not authenticated authority for supplied identity, independent project grants or validated/injective segment encoding.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing.\n\nUse this in a guide: [Add file attachments to a support request](/core-platform/files-data/files)", "slug": "/api/storage/generate-download-url", "method": "POST", "path": "/api/v1/storage/generate-download-url", "requestSchema": "storage_v1_services_gateway_v1_GenerateDownloadUrlRequest", "responseSchema": "storage_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Inherit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended audience: an authenticated person using their own storage. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended audience: an authorized tenant backend acting for a verified person beneficiary. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Accepted storage owner context", "mode": "Enforcing", "meaning": "Every gateway handler builds owner context. A request recognized by nonblank x-auth-method, x-user-id or x-tenant-id header derives identity only from required user and tenant headers and ignores body context. Headerless calls may supply tenant and Subject, with CallerKey used when Subject is absent; otherwise required header derivation is attempted. Header absence does not authenticate an internal caller. These are existing manual branches, not a new trusted-only boundary or a platform-composite adapter.
" }, { "condition_name": "Storage owner actor routing", "mode": "Enforcing", "meaning": "Every operation addresses the StorageManager actor using that accepted context owner. Public-header identity becomes tenant:default:user. Headerless supplied Subject or CallerKey is tenant-prefixed and passed through the existing unvalidated default-project insertion helper, including its colon-containing-key behavior. The addressed actor state, file lookups and normalized paths supply the current owner boundary; the actor performs no independent caller authorization. Tenant scope here describes the accepted tenant namespace with fixed default project, not authenticated authority for supplied identity, independent project grants or validated/injective segment encoding.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing.\n\nUse this in a guide: [Add file attachments to a support request](/core-platform/files-data/files)", "slug": "/api/storage/batch-generate-download-urls", "method": "POST", "path": "/api/v1/storage/batch-generate-download-urls", "requestSchema": "storage_v1_services_gateway_v1_BatchGenerateDownloadUrlsRequest", "responseSchema": "storage_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Inherit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended audience: an authenticated person using their own storage. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended audience: an authorized tenant backend acting for a verified person beneficiary. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Accepted storage owner context", "mode": "Enforcing", "meaning": "Every gateway handler builds owner context. A request recognized by nonblank x-auth-method, x-user-id or x-tenant-id header derives identity only from required user and tenant headers and ignores body context. Headerless calls may supply tenant and Subject, with CallerKey used when Subject is absent; otherwise required header derivation is attempted. Header absence does not authenticate an internal caller. These are existing manual branches, not a new trusted-only boundary or a platform-composite adapter.
" }, { "condition_name": "Storage owner actor routing", "mode": "Enforcing", "meaning": "Every operation addresses the StorageManager actor using that accepted context owner. Public-header identity becomes tenant:default:user. Headerless supplied Subject or CallerKey is tenant-prefixed and passed through the existing unvalidated default-project insertion helper, including its colon-containing-key behavior. The addressed actor state, file lookups and normalized paths supply the current owner boundary; the actor performs no independent caller authorization. Tenant scope here describes the accepted tenant namespace with fixed default project, not authenticated authority for supplied identity, independent project grants or validated/injective segment encoding.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing.\n\nUse this in a guide: [Build a searchable document library](/core-platform/files-data/managing)", "slug": "/api/storage/get-state", "method": "POST", "path": "/api/v1/storage/get-state", "requestSchema": "storage_v1_services_gateway_v1_GetStateRequest", "responseSchema": "storage_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant", "condition_mode": "Inherit", "retry_safe": true, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended audience: an authenticated person using their own storage. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended audience: an authorized tenant backend acting for a verified person beneficiary. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Accepted storage owner context", "mode": "Enforcing", "meaning": "Every gateway handler builds owner context. A request recognized by nonblank x-auth-method, x-user-id or x-tenant-id header derives identity only from required user and tenant headers and ignores body context. Headerless calls may supply tenant and Subject, with CallerKey used when Subject is absent; otherwise required header derivation is attempted. Header absence does not authenticate an internal caller. These are existing manual branches, not a new trusted-only boundary or a platform-composite adapter.
" }, { "condition_name": "Storage owner actor routing", "mode": "Enforcing", "meaning": "Every operation addresses the StorageManager actor using that accepted context owner. Public-header identity becomes tenant:default:user. Headerless supplied Subject or CallerKey is tenant-prefixed and passed through the existing unvalidated default-project insertion helper, including its colon-containing-key behavior. The addressed actor state, file lookups and normalized paths supply the current owner boundary; the actor performs no independent caller authorization. Tenant scope here describes the accepted tenant namespace with fixed default project, not authenticated authority for supplied identity, independent project grants or validated/injective segment encoding.
" } ] }, "runtime_enforcement": false }, { "key": "conversations:createThread", "operationId": "createThread", "bundle": "conversations.yaml", "title": "Create a new conversation thread", "description": "Creates a conversation thread for the authenticated user.\n\nUse this in a guide: [Build a support conversation the user can return to](/managed-agents/conversations) · [Let a customer navigate your app through chat](/managed-agents/delegation-approvals/build-agent-with-tools) · [Build a reusable assistant profile](/managed-agents/profiles-prompts) · [Build a research, bulk-summary or structured-summary flow](/managed-agents/model-controls/examples) · [Route an image question to a capable model](/managed-agents/model-controls/filtering) · [Keep a model on the providers you choose](/managed-agents/model-controls/provider-pinning) · [Build a signed-in support chat that survives reconnects](/managed-agents/conversations/build-chat-assistant) · [Configure a support conversation that stays predictable](/managed-agents/conversations/configuration) · [Complete your first support-chat turn](/managed-agents/conversations/quickstart) · [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps) · [Profile selection and prompt versions](/api/agent-profiles/selection-and-versioning)", "slug": "/api/conversations/create-thread", "method": "POST", "path": "/api/v1/llm/create-thread", "requestSchema": "llm_v1_services_gateway_v1_CreateThreadRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Model selection access", "mode": "Enforcing", "meaning": "Requested models must be eligible for the platform and tenant. Empty model selections are allowed.
" } ] }, "runtime_enforcement": false }, { "key": "conversations:listThreads", "operationId": "listThreads", "bundle": "conversations.yaml", "title": "List conversation threads", "description": "Returns a paginated list of conversation threads for the authenticated user, ordered by `lastMessageAt` descending, then `threadId` descending for ties. Changes to `updatedAt` alone do not change the list position.\n\nPass `nextPageToken` as `pageToken` to continue after the last returned thread in that order. Pages read the current conversation projection; they do not share a point-in-time snapshot. Concurrent message activity can move a thread ahead of a continuation token, so a multi-page traversal can miss threads that move while it is in progress.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build a support conversation the user can return to](/managed-agents/conversations) · [Connect signed-in users to their conversations](/core-platform/identity-access/authentication) · [Build a signed-in support chat that survives reconnects](/managed-agents/conversations/build-chat-assistant) · [Complete your first support-chat turn](/managed-agents/conversations/quickstart)", "slug": "/api/conversations/list-threads", "method": "POST", "path": "/api/v1/llm/list-threads", "requestSchema": "llm_v1_services_gateway_v1_ListThreadsRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "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.\n\nUse this in a guide: [API Reference](/api) · [Build a support conversation the user can return to](/managed-agents/conversations) · [Let a customer navigate your app through chat](/managed-agents/delegation-approvals/build-agent-with-tools) · [Approve a tool action and finish the conversation](/managed-agents/delegation-approvals/using-tools) · [Build a reusable assistant profile](/managed-agents/profiles-prompts) · [Recover when no model can serve the request](/managed-agents/model-controls/errors) · [Build a research, bulk-summary or structured-summary flow](/managed-agents/model-controls/examples) · [Route an image question to a capable model](/managed-agents/model-controls/filtering) · [Keep a model on the providers you choose](/managed-agents/model-controls/provider-pinning) · [Add an optional reasoning panel to a chat reply](/managed-agents/model-controls/reasoning) · [Configuration precedence and plugins](/api/model-controls/configuration) · [Model routing and selection](/api/model-controls/routing) · [Control access with scopes](/core-platform/identity-access/scopes-permissions) · [Build an assistant that researches the web](/integrations/tools-connections) · [MCP server selection](/api/tools/selection) · [Summarize a customer’s uploaded report](/managed-agents/conversations/attachments) · [Build a signed-in support chat that survives reconnects](/managed-agents/conversations/build-chat-assistant) · [Explain the setting the customer is looking at](/managed-agents/conversations/client-context) · [Configure a support conversation that stays predictable](/managed-agents/conversations/configuration) · [Get a customer’s reply and recover an interrupted send](/managed-agents/conversations/generation) · [Complete your first support-chat turn](/managed-agents/conversations/quickstart) · [Restore a chat after the connection drops](/managed-agents/conversations/streaming/subscribing) · [Answer questions about a website using your own Firecrawl account](/integrations/tools-connections/custom-mcp-servers) · [Messages and runs](/api/conversations/messages-and-runs) · [Profile selection and prompt versions](/api/agent-profiles/selection-and-versioning)", "slug": "/api/conversations/send-message", "method": "POST", "path": "/api/v1/llm/send-message", "requestSchema": "llm_v1_services_gateway_v1_SendMessageRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Generation entitlement and model selection", "mode": "Enforcing", "meaning": "Generation is subject to entitlement checks. Requested models must be eligible for the platform and tenant. Empty model selections are allowed.
" } ] }, "runtime_enforcement": false }, { "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 this call. Use it to record a system note, an external event or other context that later generations should see without triggering a reply.\n\nRead `conversation-state` to confirm the event: append assigns the next monotonic sequence immediately and publishes a message event. `ROLE_USER` opens a new user turn; other roles join the most recent user turn. Choose the role for how the event should appear in history, without changing the fact it records.\n\nAppend bypasses the interrupt policy and pending queue. It can run while another turn is active, but that turn may already have assembled its provider request. This call does not stop already running work or guarantee zero account-level cost: storage and future model input can still cost money.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Get a customer’s reply and recover an interrupted send](/managed-agents/conversations/generation) · [Context and compaction](/api/conversations/context-and-compaction)", "slug": "/api/conversations/append-message", "method": "POST", "path": "/api/v1/llm/append-message", "requestSchema": "llm_v1_services_gateway_v1_AppendMessageRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "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 per rater per message; re-rating replaces only the caller's previous entry.\n\nSerialize re-rating and withdrawal actions and reconcile stored state: uniqueness does not guarantee ordering against a delayed request or analytics event.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Collect message feedback](/insights/evaluation/message-feedback) · [Feedback and score attribution](/api/evals/scoring)", "slug": "/api/conversations/rate-message", "method": "POST", "path": "/api/v1/llm/rate-message", "requestSchema": "llm_v1_services_gateway_v1_RateMessageRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "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 is derived server-side from the verified request headers.\n\nThis is idempotent: withdrawing a rating that was never left is a success, not an error — the response returns `removed: false` in that case.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Collect message feedback](/insights/evaluation/message-feedback) · [Feedback and score attribution](/api/evals/scoring)", "slug": "/api/conversations/delete-message-rating", "method": "POST", "path": "/api/v1/llm/delete-message-rating", "requestSchema": "llm_v1_services_gateway_v1_DeleteMessageRatingRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "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 inline when available. Use it when you need the assistant reply in the HTTP response, such as structured output or a classification.\n\nInspect [`status`](/api/conversations/send-message-sync#response-field-status) even on HTTP 200: a queued message, a pause for client tools or the bounded wait ending can return before the run finishes. A transport timeout or unknown status does not authorize resending the message; reconcile the accepted run.\n\nSee [Messages and run outcomes](/api/conversations/messages-and-runs) for status interpretation and recovery.\n\nUse this in a guide: [Let a customer navigate your app through chat](/managed-agents/delegation-approvals/build-agent-with-tools) · [Check a chat integration before customers use it](/developer-experience/local-tooling/testing) · [Replay datasets and runs](/insights/evaluation/datasets-and-runs) · [Turn a task description into a validated summary object](/managed-agents/model-controls/structured-output) · [Build an assistant that researches the web](/integrations/tools-connections) · [Get a customer’s reply and recover an interrupted send](/managed-agents/conversations/generation) · [Tool policy resolution and lifecycle](/api/tool-execution/policies) · [Automate recurring agent work](/core-platform/scheduling/build-scheduled-agents) · [Signed callbacks and receiver acknowledgement](/api/scheduled-jobs/callbacks) · [Show one correct chat history as updates arrive](/managed-agents/conversations/streaming/payloads) · [Messages and runs](/api/conversations/messages-and-runs)", "slug": "/api/conversations/send-message-sync", "method": "POST", "path": "/api/v1/llm/send-message-sync", "requestSchema": "llm_v1_services_gateway_v1_SendMessageSyncRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Generation entitlement and model selection", "mode": "Enforcing", "meaning": "Generation is subject to entitlement checks. Requested models must be eligible for the platform and tenant. Empty model selections are allowed.
" } ] }, "runtime_enforcement": false }, { "key": "conversations:updateSettings", "operationId": "updateSettings", "bundle": "conversations.yaml", "title": "Update conversation settings", "description": "Updates the conversation's behavior settings.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build an assistant that researches the web](/integrations/tools-connections) · [MCP server selection](/api/tools/selection) · [Configure a support conversation that stays predictable](/managed-agents/conversations/configuration) · [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps)", "slug": "/api/conversations/update-settings", "method": "POST", "path": "/api/v1/llm/update-settings", "requestSchema": "llm_v1_services_gateway_v1_UpdateSettingsRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Configure a support conversation that stays predictable](/managed-agents/conversations/configuration) · [Profile selection and prompt versions](/api/agent-profiles/selection-and-versioning)", "slug": "/api/conversations/update-prompt-variables", "method": "POST", "path": "/api/v1/llm/update-prompt-variables", "requestSchema": "llm_v1_services_gateway_v1_UpdatePromptVariablesRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "key": "conversations:updateDefaultGenerationConfig", "operationId": "updateDefaultGenerationConfig", "bundle": "conversations.yaml", "title": "Update default generation config", "description": "Updates the conversation’s default generation configuration for later messages. An active profile supplies the base configuration when selected; populated per-request overrides take precedence. Conversation memory settings fill settings omitted by an active profile.\n\nUse this in a guide: [Use remembered preferences in a returning user’s conversation](/managed-agents/memory-knowledge) · [Configure a support conversation that stays predictable](/managed-agents/conversations/configuration) · [Profile selection and prompt versions](/api/agent-profiles/selection-and-versioning)", "slug": "/api/conversations/update-default-generation-config", "method": "POST", "path": "/api/v1/llm/update-default-generation-config", "requestSchema": "llm_v1_services_gateway_v1_UpdateDefaultGenerationConfigRequest", "responseSchema": "llm_v1_services_gateway_v1_UpdateDefaultGenerationConfigResponse", "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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Model selection access", "mode": "Enforcing", "meaning": "Requested models must be eligible for the platform and tenant. Empty model selections are allowed.
" } ] }, "runtime_enforcement": false }, { "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 selection and outcome handling.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Resume a long conversation with a compacted history](/managed-agents/conversations/context-management) · [Context and compaction](/api/conversations/context-and-compaction)", "slug": "/api/conversations/update-context-management-settings", "method": "POST", "path": "/api/v1/llm/update-context-management-settings", "requestSchema": "llm_v1_services_gateway_v1_UpdateContextManagementSettingsRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "key": "conversations:compactConversation", "operationId": "compactConversation", "bundle": "conversations.yaml", "title": "Compact a conversation", "description": "Triggers context compaction, summarizing older conversation messages. The trigger estimate can differ from the next request's actual size, especially after changing prompts or tools. Leave room below the model limit and handle context-limit errors.\n\nWhen configured for asynchronous compaction, this call returns a pending result immediately. Use the returned `compactionId` to inspect the completed record in `conversation-state`'s `compactions` array. Compaction can still delay other messages in the conversation; asynchronous acceptance does not guarantee uninterrupted concurrent messaging.\n\nSee [Context and compaction](/api/conversations/context-and-compaction) for strategy selection and outcome handling.\n\nUse this in a guide: [Resume a long conversation with a compacted history](/managed-agents/conversations/context-management)", "slug": "/api/conversations/compact-conversation", "method": "POST", "path": "/api/v1/llm/compact-conversation", "requestSchema": "llm_v1_services_gateway_v1_CompactConversationRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Generation entitlement", "mode": "Shadow", "meaning": "Checks generation entitlement for the compaction request and logs the result without denying the request through this condition.
" } ] }, "runtime_enforcement": false }, { "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` returns `404`.\n\nWhen polling, the absence of an active run does not prove that an accepted or queued request completed. Reconcile the original `runId` and its outcome before retrying an accepted send.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build a support conversation the user can return to](/managed-agents/conversations) · [Build an assistant that researches the web](/integrations/tools-connections) · [Build a signed-in support chat that survives reconnects](/managed-agents/conversations/build-chat-assistant) · [Resume a long conversation with a compacted history](/managed-agents/conversations/context-management) · [Get a customer’s reply and recover an interrupted send](/managed-agents/conversations/generation) · [Complete your first support-chat turn](/managed-agents/conversations/quickstart) · [Show one correct chat history as updates arrive](/managed-agents/conversations/streaming/payloads) · [Restore a chat after the connection drops](/managed-agents/conversations/streaming/subscribing) · [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps) · [Messages and runs](/api/conversations/messages-and-runs)", "slug": "/api/conversations/get-conversation-state", "method": "POST", "path": "/api/v1/llm/conversation-state", "requestSchema": "llm_v1_services_gateway_v1_GetConversationStateRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "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. Confirm room connection and agent readiness through provider events. A returned session alone does not establish that the agent joined or that transcripts were stored in conversation history.\n\nAt session end, handle room expiry and the client's local capture separately; a local disconnect alone does not establish remote cleanup.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Add a spoken conversation to your app (Preview)](/managed-agents/voice-media)", "slug": "/api/conversations/create-daily-session", "method": "POST", "path": "/api/v1/llm/create-daily-session", "requestSchema": "llm_v1_services_gateway_v1_CreateDailySessionRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "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. The request fails when that credential is missing. The client uses this token to call the STT API directly so the backend key never reaches the client.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Add a spoken conversation to your app (Preview)](/managed-agents/voice-media)", "slug": "/api/conversations/mint-stt-token", "method": "POST", "path": "/api/v1/llm/stt-token", "requestSchema": "llm_v1_services_gateway_v1_MintSttTokenRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Approve a tool action and finish the conversation](/managed-agents/delegation-approvals/using-tools) · [Event catalog](/api/events)", "slug": "/api/conversations/list-pending-approvals", "method": "POST", "path": "/api/v1/llm/list-pending-approvals", "requestSchema": "llm_v1_services_gateway_v1_ListPendingApprovalsRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Approve a tool action and finish the conversation](/managed-agents/delegation-approvals/using-tools) · [Event catalog](/api/events)", "slug": "/api/conversations/submit-tool-approvals", "method": "POST", "path": "/api/v1/llm/submit-tool-approvals", "requestSchema": "llm_v1_services_gateway_v1_SubmitToolApprovalsRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "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 generation segment. While the conversation still identifies a run, workflow validation 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. Reconcile stored run and tool state before treating HTTP success as confirmation that the results were applied.\n\nA run can request further batches. Read pending client tools, execute each new batch and submit its results until the run reaches a terminal outcome. An unknown status requires reconciliation with a bounded wait, not an assumption of success. See [Messages and run outcomes](/api/conversations/messages-and-runs) for outcome handling and the synchronous client-tool loop.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.", "slug": "/api/conversations/submit-client-tool-results", "method": "POST", "path": "/api/v1/llm/submit-client-tool-results", "requestSchema": "llm_v1_services_gateway_v1_SubmitClientToolResultsRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "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 batch or finishes. This continues the loop started by `send-message-sync`. While the conversation still identifies a run, workflow validation rejects unmatched calls with `400` and already-resolved calls with `410`.\n\nIf no active run is recorded, this call can return success immediately without applying any results. Reconcile stored run and tool state before treating HTTP success as confirmation that the results were applied.\n\nEcho the `clientToolCursor` from the response that armed the calls. A stale cursor re-delivers a batch rather than skipping one. When another batch arrives, execute it and submit again with its new cursor until the run reaches a terminal outcome. Reconcile an unknown status with a bounded wait; do not assume success.\n\nAn empty `results` array returns `400`: submitting nothing resolves nothing. Use `list-pending-client-tools` to inspect pending work or recover after a dropped connection. Do not resend the original user message, which would start another run. Use `submit-client-tool-results` when you do not want to hold the connection.\n\nSee [Messages and run outcomes](/api/conversations/messages-and-runs) for status interpretation and recovery.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Let a customer navigate your app through chat](/managed-agents/delegation-approvals/build-agent-with-tools) · [Check a chat integration before customers use it](/developer-experience/local-tooling/testing) · [Get a customer’s reply and recover an interrupted send](/managed-agents/conversations/generation)", "slug": "/api/conversations/submit-client-tool-results-sync", "method": "POST", "path": "/api/v1/llm/submit-client-tool-results-sync", "requestSchema": "llm_v1_services_gateway_v1_SubmitClientToolResultsSyncRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Let a customer navigate your app through chat](/managed-agents/delegation-approvals/build-agent-with-tools)", "slug": "/api/conversations/list-pending-client-tools", "method": "POST", "path": "/api/v1/llm/list-pending-client-tools", "requestSchema": "llm_v1_services_gateway_v1_ListPendingClientToolsRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "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 resolved calls retained there. An empty response means the call was not found in that current run; it does not prove the call never executed.\n\nMatch the call ID and inspect both status and result. If its answer window expired, the result reports `client tool timeout`. Inspect both the status and reason before deciding whether any work remains; expiration does not establish whether an action dispatched to the client took effect.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Let a customer navigate your app through chat](/managed-agents/delegation-approvals/build-agent-with-tools) · [Build an assistant that researches the web](/integrations/tools-connections) · [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps) · [Answer questions about a website using your own Firecrawl account](/integrations/tools-connections/custom-mcp-servers)", "slug": "/api/conversations/get-tool-call", "method": "POST", "path": "/api/v1/llm/get-tool-call", "requestSchema": "llm_v1_services_gateway_v1_GetToolCallRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "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. A catalog entry appearing in this list is not a setting that attaches its tools to your conversation.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Let a customer navigate your app through chat](/managed-agents/delegation-approvals/build-agent-with-tools) · [Build an assistant that researches the web](/integrations/tools-connections)", "slug": "/api/conversations/mcp-list-available-servers", "method": "POST", "path": "/api/v1/llm/mcp-list-available-servers", "requestSchema": "llm_v1_services_gateway_v1_MCPListAvailableServersRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project and Global", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: The catalog includes records from its bound private scope and shared global catalog entries. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: The catalog includes records from its bound private scope and shared global catalog entries. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Tenant/project-only access would require restricting results to owned records or providing a separately scoped global-discovery interface. Current results have mixed scope. Intended audience: App user, Tenant backend. The catalog includes records from its bound private scope and shared global catalog entries.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.", "slug": "/api/conversations/mcp-get-server-info", "method": "POST", "path": "/api/v1/llm/mcp-get-server-info", "requestSchema": "llm_v1_services_gateway_v1_MCPGetServerInfoRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project and Global", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: The catalog includes records from its bound private scope and shared global catalog entries. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: The catalog includes records from its bound private scope and shared global catalog entries. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Tenant/project-only access would require restricting results to owned records or providing a separately scoped global-discovery interface. Current results have mixed scope. Intended audience: App user, Tenant backend. The catalog includes records from its bound private scope and shared global catalog entries.
" } ] }, "runtime_enforcement": false }, { "key": "conversations:mcpListTools", "operationId": "mcpListTools", "bundle": "conversations.yaml", "title": "List available MCP tools", "description": "Returns tools discovered across the selected MCP servers.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build an assistant that researches the web](/integrations/tools-connections) · [Let your assistant answer questions about a customer’s calendar](/integrations/tools-connections/connected-apps) · [Answer questions about a website using your own Firecrawl account](/integrations/tools-connections/custom-mcp-servers)", "slug": "/api/conversations/mcp-list-tools", "method": "POST", "path": "/api/v1/llm/mcp-list-tools", "requestSchema": "llm_v1_services_gateway_v1_MCPListToolsRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project and Global", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: The catalog includes records from its bound private scope and shared global catalog entries. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: The catalog includes records from its bound private scope and shared global catalog entries. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Tenant/project-only access would require restricting results to owned records or providing a separately scoped global-discovery interface. Current results have mixed scope. Intended audience: App user, Tenant backend. The catalog includes records from its bound private scope and shared global catalog entries.
" } ] }, "runtime_enforcement": false }, { "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 without starting a generation run.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Check a chat integration before customers use it](/developer-experience/local-tooling/testing) · [Build an assistant that researches the web](/integrations/tools-connections)", "slug": "/api/conversations/mcp-call-tool", "method": "POST", "path": "/api/v1/llm/mcp-call-tool", "requestSchema": "llm_v1_services_gateway_v1_MCPCallToolRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build an assistant that researches the web](/integrations/tools-connections)", "slug": "/api/conversations/mcp-list-resources", "method": "POST", "path": "/api/v1/llm/mcp-list-resources", "requestSchema": "llm_v1_services_gateway_v1_MCPListResourcesRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build an assistant that researches the web](/integrations/tools-connections)", "slug": "/api/conversations/mcp-read-resource", "method": "POST", "path": "/api/v1/llm/mcp-read-resource", "requestSchema": "llm_v1_services_gateway_v1_MCPReadResourceRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build an assistant that researches the web](/integrations/tools-connections)", "slug": "/api/conversations/mcp-list-prompts", "method": "POST", "path": "/api/v1/llm/mcp-list-prompts", "requestSchema": "llm_v1_services_gateway_v1_MCPListPromptsRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Build an assistant that researches the web](/integrations/tools-connections)", "slug": "/api/conversations/mcp-get-prompt", "method": "POST", "path": "/api/v1/llm/mcp-get-prompt", "requestSchema": "llm_v1_services_gateway_v1_MCPGetPromptRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "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 and relationships depend on the configured provider. An empty result can represent a handled provider failure and does not prove that no memories exist. Search does not provide pagination or a complete inventory.\n\nUse an authorized backend key with X-On-Behalf-Of and users\\:impersonate scope, or a publishable key with a user JWT. A configured user JWT can also authenticate directly. An effective user and tenant are required; raw identity headers do not grant authority. See the [memory cookbook](/managed-agents/memory-knowledge).\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Use remembered preferences in a returning user’s conversation](/managed-agents/memory-knowledge)", "slug": "/api/conversations/search-memories", "method": "POST", "path": "/api/v1/llm/search-memories", "requestSchema": "llm_v1_services_gateway_v1_SearchMemoriesRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "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 cursor or category filter. A capped response does not prove that the user has seen every stored record or provide a complete all-records traversal guarantee.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Use remembered preferences in a returning user’s conversation](/managed-agents/memory-knowledge)", "slug": "/api/conversations/list-memories", "method": "POST", "path": "/api/v1/llm/list-memories", "requestSchema": "llm_v1_services_gateway_v1_ListMemoriesRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Use remembered preferences in a returning user’s conversation](/managed-agents/memory-knowledge)", "slug": "/api/conversations/get-memory", "method": "POST", "path": "/api/v1/llm/get-memory", "requestSchema": "llm_v1_services_gateway_v1_GetMemoryRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "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.\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Use remembered preferences in a returning user’s conversation](/managed-agents/memory-knowledge)", "slug": "/api/conversations/update-memory", "method": "POST", "path": "/api/v1/llm/update-memory", "requestSchema": "llm_v1_services_gateway_v1_UpdateMemoryRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false }, { "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).\n\nThe following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.\n\nUse this in a guide: [Use remembered preferences in a returning user’s conversation](/managed-agents/memory-knowledge)", "slug": "/api/conversations/delete-memory", "method": "POST", "path": "/api/v1/llm/delete-memory", "requestSchema": "llm_v1_services_gateway_v1_DeleteMemoryRequest", "responseSchema": "llm_v1_services_gateway_v1_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" }, "onBehalfOf": { "type": "apiKey", "in": "header", "name": "X-On-Behalf-Of" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "stability": "Preview", "declared_access": { "acts_for": "Person", "data_scope": "Tenant project", "condition_mode": "Explicit", "retry_safe": false, "exposures": [ "Public API" ], "audiences": [ { "audience": "App user", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" }, { "audience": "Tenant backend", "meaning": "Intended use: Authenticated person conversations, memory and tool use. Do not rely on this audience declaration as an enforced authentication or authorization boundary.
" } ], "access_conditions": [ { "condition_name": "Authorized scoped domain action", "mode": "Enforcing", "meaning": "Intended access requirements; current enforcement is not established: Require trusted person and tenant-project identity, validate object ownership and delegation, and preserve current policy/approval constraints. Identity supplied in the request body is not a trusted identity source. Intended audience: App user, Tenant backend. Authenticated person conversations, memory and tool use.
" } ] }, "runtime_enforcement": false } ], "roots": [ { "doctype": "API Event", "name": "9i3l70sln0", "lineage_root": "u1s768tpmf", "payload_symbol": "llm.v1.common.v1.LLMMessagePublishedEvent", "delivery_intent_enforced": false, "definition": { "title": "LLMMessagePublishedEvent", "payload_revision": "8s8gtmk21l", "delivery_guarantee": "", "publication_mode": "", "ordering": "", "retention_seconds": null, "live_write_intent": "Append", "stability": "", "meaning": "Domain event published when a new assistant/tool message is produced.
", "notes": "In the live conversation view, messages append to the message history. Message sequence identifies each entry; repeated delivery updates the same entry.
\nEvent-specific delivery guarantees, ordering, retention and lifecycle status are unspecified.
", "retention_intent": null, "ordering_key_meaning": null, "live_destination_meaning": "Conversation message view, with each message addressed by its sequence.
", "live_child_key_meaning": "Message sequence identifies the entry; repeated delivery updates that same entry.
", "deprecation_reason": null, "producers": [], "subscribers": [], "audiences": [ { "audience": "Live view", "meaning": "Current conversation client projection.
" }, { "audience": "Tenant webhook", "meaning": "Sent to subscribed tenant webhook endpoints.
" } ] }, "documentation": { "meaning": "Domain event published when a new assistant/tool message is produced.\nUse this in a guide: [Event catalog](/api/events) · [Automate recurring agent work](/core-platform/scheduling/build-scheduled-agents)\n", "notes": "In the live conversation view, messages append to the message history. Message sequence identifies each entry; repeated delivery updates the same entry.\n\nEvent-specific delivery guarantees, ordering, retention and lifecycle status are unspecified.", "retention_intent": "", "ordering_key_meaning": "", "live_destination_meaning": "Conversation message view, with each message addressed by its sequence.", "live_child_key_meaning": "Message sequence identifies the entry; repeated delivery updates that same entry.", "deprecation_reason": "", "payload": { "title": "LLMMessagePublishedEvent", "slug": "/api/models/schema-po1qsocerv" }, "producers": [], "subscribers": [], "audiences": [ { "audience": "Live view", "meaning": "Current conversation client projection." }, { "audience": "Tenant webhook", "meaning": "Sent to subscribed tenant webhook endpoints." } ] } }, { "doctype": "API Event", "name": "84ptg9ajvv", "lineage_root": "u1u0sjgmch", "payload_symbol": "llm.v1.common.v1.LLMGenerationCompletedEvent", "delivery_intent_enforced": false, "definition": { "title": "LLMGenerationCompletedEvent", "payload_revision": "7opl755dn8", "delivery_guarantee": "", "publication_mode": "", "ordering": "", "retention_seconds": null, "live_write_intent": "Replace", "stability": "", "meaning": "Event emitted when a generation run reaches a terminal state. The event context identifies the associated conversation.
", "notes": "In the live view, this event replaces the status view for the individual generation run within its conversation.
\nEvent-specific delivery guarantees, ordering, retention and lifecycle status are unspecified.
", "retention_intent": null, "ordering_key_meaning": null, "live_destination_meaning": "Status view for the individual generation run within its conversation.
", "live_child_key_meaning": null, "deprecation_reason": null, "producers": [], "subscribers": [], "audiences": [ { "audience": "Live view", "meaning": "Current conversation client projection.
" }, { "audience": "Tenant webhook", "meaning": "Sent to subscribed tenant webhook endpoints.
" } ] }, "documentation": { "meaning": "Event emitted when a generation run reaches a terminal state. The event context identifies the associated conversation.\nUse this in a guide: [Integrations](/integrations) · [API Reference](/api) · [Event catalog](/api/events) · [Update your backend when an assistant finishes](/integrations/webhooks)\n", "notes": "In the live view, this event replaces the status view for the individual generation run within its conversation.\n\nEvent-specific delivery guarantees, ordering, retention and lifecycle status are unspecified.", "retention_intent": "", "ordering_key_meaning": "", "live_destination_meaning": "Status view for the individual generation run within its conversation.", "live_child_key_meaning": "", "deprecation_reason": "", "payload": { "title": "LLMGenerationCompletedEvent", "slug": "/api/models/schema-pntuu08p80" }, "producers": [], "subscribers": [], "audiences": [ { "audience": "Live view", "meaning": "Current conversation client projection." }, { "audience": "Tenant webhook", "meaning": "Sent to subscribed tenant webhook endpoints." } ] } }, { "doctype": "API Event", "name": "84rgqjjrl0", "lineage_root": "u20phhssrl", "payload_symbol": "llm.v1.common.v1.LLMGenerationStartedEvent", "delivery_intent_enforced": false, "definition": { "title": "LLMGenerationStartedEvent", "payload_revision": "7os6ju8g5c", "delivery_guarantee": "", "publication_mode": "", "ordering": "", "retention_seconds": null, "live_write_intent": "Replace", "stability": "", "meaning": "Event emitted when a generation run starts. The event context identifies the associated conversation.
", "notes": "In the live view, this event replaces the status view for the individual generation run within its conversation.
\nEvent-specific delivery guarantees, ordering, retention and lifecycle status are unspecified.
", "retention_intent": null, "ordering_key_meaning": null, "live_destination_meaning": "Status view for the individual generation run within its conversation.
", "live_child_key_meaning": null, "deprecation_reason": null, "producers": [], "subscribers": [], "audiences": [ { "audience": "Live view", "meaning": "Current conversation client projection.
" }, { "audience": "Tenant webhook", "meaning": "Sent to subscribed tenant webhook endpoints.
" } ] }, "documentation": { "meaning": "Event emitted when a generation run starts. The event context identifies the associated conversation.\nUse this in a guide: [Event catalog](/api/events)\n", "notes": "In the live view, this event replaces the status view for the individual generation run within its conversation.\n\nEvent-specific delivery guarantees, ordering, retention and lifecycle status are unspecified.", "retention_intent": "", "ordering_key_meaning": "", "live_destination_meaning": "Status view for the individual generation run within its conversation.", "live_child_key_meaning": "", "deprecation_reason": "", "payload": { "title": "LLMGenerationStartedEvent", "slug": "/api/models/schema-pnv14jb39g" }, "producers": [], "subscribers": [], "audiences": [ { "audience": "Live view", "meaning": "Current conversation client projection." }, { "audience": "Tenant webhook", "meaning": "Sent to subscribed tenant webhook endpoints." } ] } }, { "doctype": "API Event", "name": "6vto7rka3s", "lineage_root": "u22bdqd1kd", "payload_symbol": "llm.v1.common.v1.ToolCallStartedEvent", "delivery_intent_enforced": false, "definition": { "title": "ToolCallStartedEvent", "payload_revision": "62v9me6kv5", "delivery_guarantee": "", "publication_mode": "", "ordering": "", "retention_seconds": null, "live_write_intent": "Replace", "stability": "", "meaning": "Event for a tool call that has begun execution or is waiting for human approval. Check the event name and tool-call status to distinguish these cases; the event context identifies the conversation.
", "notes": "In the live view, this event replaces the current tool activity view for the conversation. The payload can represent execution starting or a request for human approval; use the event name and tool-call status to distinguish these cases.
\nEvent-specific delivery guarantees, ordering, retention and lifecycle status are unspecified.
", "retention_intent": null, "ordering_key_meaning": null, "live_destination_meaning": "Current tool activity view for the conversation.
", "live_child_key_meaning": null, "deprecation_reason": null, "producers": [], "subscribers": [], "audiences": [ { "audience": "Live view", "meaning": "Current conversation client projection.
" }, { "audience": "Tenant webhook", "meaning": "Sent to subscribed tenant webhook endpoints.
" } ] }, "documentation": { "meaning": "Event for a tool call that has begun execution or is waiting for human approval. Check the event name and tool-call status to distinguish these cases; the event context identifies the conversation.\nUse this in a guide: [Event catalog](/api/events) · [Tool policy resolution and lifecycle](/api/tool-execution/policies)\n", "notes": "In the live view, this event replaces the current tool activity view for the conversation. The payload can represent execution starting or a request for human approval; use the event name and tool-call status to distinguish these cases.\n\nEvent-specific delivery guarantees, ordering, retention and lifecycle status are unspecified.", "retention_intent": "", "ordering_key_meaning": "", "live_destination_meaning": "Current tool activity view for the conversation.", "live_child_key_meaning": "", "deprecation_reason": "", "payload": { "title": "ToolCallStartedEvent", "slug": "/api/models/schema-po5rioe4il" }, "producers": [], "subscribers": [], "audiences": [ { "audience": "Live view", "meaning": "Current conversation client projection." }, { "audience": "Tenant webhook", "meaning": "Sent to subscribed tenant webhook endpoints." } ] } }, { "doctype": "API Event", "name": "6vrs2kmfd4", "lineage_root": "u249vf7739", "payload_symbol": "llm.v1.common.v1.ToolCallCompletedEvent", "delivery_intent_enforced": false, "definition": { "title": "ToolCallCompletedEvent", "payload_revision": "62stl45kr4", "delivery_guarantee": "", "publication_mode": "", "ordering": "", "retention_seconds": null, "live_write_intent": "Replace", "stability": "", "meaning": "Event emitted when a tool call reaches COMPLETED, FAILED, CANCELLED or TIMED_OUT, including calls that required human approval.
", "notes": "In the live view, this event replaces the current tool activity view for the conversation.
\nEvent-specific delivery guarantees, ordering, retention and lifecycle status are unspecified.
", "retention_intent": null, "ordering_key_meaning": null, "live_destination_meaning": "Current tool activity view for the conversation.
", "live_child_key_meaning": null, "deprecation_reason": null, "producers": [], "subscribers": [], "audiences": [ { "audience": "Live view", "meaning": "Current conversation client projection.
" }, { "audience": "Tenant webhook", "meaning": "Sent to subscribed tenant webhook endpoints.
" } ] }, "documentation": { "meaning": "Event emitted when a tool call reaches COMPLETED, FAILED, CANCELLED or TIMED\\_OUT, including calls that required human approval.\nUse this in a guide: [Event catalog](/api/events)\n", "notes": "In the live view, this event replaces the current tool activity view for the conversation.\n\nEvent-specific delivery guarantees, ordering, retention and lifecycle status are unspecified.", "retention_intent": "", "ordering_key_meaning": "", "live_destination_meaning": "Current tool activity view for the conversation.", "live_child_key_meaning": "", "deprecation_reason": "", "payload": { "title": "ToolCallCompletedEvent", "slug": "/api/models/schema-po3pkfshjg" }, "producers": [], "subscribers": [], "audiences": [ { "audience": "Live view", "meaning": "Current conversation client projection." }, { "audience": "Tenant webhook", "meaning": "Sent to subscribed tenant webhook endpoints." } ] } }, { "doctype": "API Enum", "name": "6tv1pafpa2", "lineage_root": "q8qp045fpk", "source_symbol": "llm.v1.common.v1.Provider", "key": "API Enum/6tv1pafpa2", "kind": "API Enum", "title": "Provider", "slug": "/api/models/enum-q8qp045fpk", "serialization": "json-names" }, { "doctype": "API Enum", "name": "6u1ita10u0", "lineage_root": "q97i14qn23", "source_symbol": "llm.v1.common.v1.ToolCategory", "key": "API Enum/6u1ita10u0", "kind": "API Enum", "title": "ToolCategory", "slug": "/api/models/enum-q97i14qn23", "serialization": "json-names" }, { "doctype": "API Enum", "name": "6u3eomk7tb", "lineage_root": "q9e32qbsm3", "source_symbol": "llm.v1.common.v1.VectorMetric", "key": "API Enum/6u3eomk7tb", "kind": "API Enum", "title": "VectorMetric", "slug": "/api/models/enum-q9e32qbsm3", "serialization": "json-names" }, { "doctype": "API Schema", "name": "6up6drbioc", "lineage_root": "pq9d837o76", "source_symbol": "auth.v1.common.v1.AuthorizationModel", "key": "API Schema/6up6drbioc", "kind": "API Schema", "title": "AuthorizationModel", "slug": "/api/models/schema-pq9d837o76", "serialization": "json-names" }, { "doctype": "API Schema", "name": "6urseekt57", "lineage_root": "pqh3ei5p5l", "source_symbol": "auth.v1.common.v1.Store", "key": "API Schema/6urseekt57", "kind": "API Schema", "title": "Store", "slug": "/api/models/schema-pqh3ei5p5l", "serialization": "json-names" }, { "doctype": "API Schema", "name": "62ajd5h7r5", "lineage_root": "pqjdejpl2g", "source_symbol": "auth.v1.common.v1.TupleKey", "key": "API Schema/62ajd5h7r5", "kind": "API Schema", "title": "TupleKey", "slug": "/api/models/schema-pqjdejpl2g", "serialization": "json-names" }, { "doctype": "API Schema", "name": "62c40oktj2", "lineage_root": "pql723cqr4", "source_symbol": "auth.v1.common.v1.UserSet", "key": "API Schema/62c40oktj2", "kind": "API Schema", "title": "UserSet", "slug": "/api/models/schema-pql723cqr4", "serialization": "json-names" }, { "doctype": "API Schema", "name": "6282cia2fj", "lineage_root": "1fc03re4nc", "source_symbol": "google.protobuf.StringValue", "key": "API Schema/6282cia2fj", "kind": "API Schema", "title": "StringValue", "slug": "/api/models/schema-1fc03re4nc", "serialization": "json-names" }, { "doctype": "API Schema", "name": "9frhv4euve", "lineage_root": "q69v86pv94", "source_symbol": "llm.v1.actors.conversation.v1.ReceiveMessageRequest", "key": "API Schema/9frhv4euve", "kind": "API Schema", "title": "ReceiveMessageRequest", "slug": "/api/models/schema-q69v86pv94", "serialization": "json-names" }, { "doctype": "API Schema", "name": "626klhca0u", "lineage_root": "q7hl8fcm9r", "source_symbol": "llm.v1.common.v1.ConversationBranch", "key": "API Schema/626klhca0u", "kind": "API Schema", "title": "ConversationBranch", "slug": "/api/models/schema-q7hl8fcm9r", "serialization": "json-names" }, { "doctype": "API Schema", "name": "6v7cprckcj", "lineage_root": "q81ihe4v3e", "source_symbol": "llm.v1.common.v1.EmbeddingConfig", "key": "API Schema/6v7cprckcj", "kind": "API Schema", "title": "EmbeddingConfig", "slug": "/api/models/schema-q81ihe4v3e", "serialization": "json-names" }, { "doctype": "API Schema", "name": "62d20s50a7", "lineage_root": "q8egnnm4a3", "source_symbol": "llm.v1.common.v1.MCPServerConfig", "key": "API Schema/62d20s50a7", "kind": "API Schema", "title": "MCPServerConfig", "slug": "/api/models/schema-q8egnnm4a3", "serialization": "json-names" }, { "doctype": "API Schema", "name": "6vbcrt8mlp", "lineage_root": "q8s584s888", "source_symbol": "llm.v1.common.v1.ScoredVector", "key": "API Schema/6vbcrt8mlp", "kind": "API Schema", "title": "ScoredVector", "slug": "/api/models/schema-q8s584s888", "serialization": "json-names" }, { "doctype": "API Schema", "name": "t0tqko5pgb", "lineage_root": "q92tfl8qp2", "source_symbol": "llm.v1.common.v1.TextDocument", "key": "API Schema/t0tqko5pgb", "kind": "API Schema", "title": "TextDocument", "slug": "/api/models/schema-q92tfl8qp2", "serialization": "json-names" }, { "doctype": "API Schema", "name": "6vhb5mpe0m", "lineage_root": "q9cp251mpk", "source_symbol": "llm.v1.common.v1.Vector", "key": "API Schema/6vhb5mpe0m", "kind": "API Schema", "title": "Vector", "slug": "/api/models/schema-q9cp251mpk", "serialization": "json-names" }, { "doctype": "API Schema", "name": "6vk7rqoi5v", "lineage_root": "qbff0c5l2f", "source_symbol": "llm.v1.services.eval.v1.DatasetRunItem", "key": "API Schema/6vk7rqoi5v", "kind": "API Schema", "title": "DatasetRunItem", "slug": "/api/models/schema-qbff0c5l2f", "serialization": "json-names" }, { "doctype": "API Schema", "name": "e0ru3nm27c", "lineage_root": "qbs1n8ja02", "source_symbol": "llm.v1.services.eval.v1.EvalCommentSuppressionState", "key": "API Schema/e0ru3nm27c", "kind": "API Schema", "title": "EvalCommentSuppressionState", "slug": "/api/models/schema-qbs1n8ja02", "serialization": "json-names" }, { "doctype": "API Schema", "name": "9ftjkkjhfa", "lineage_root": "qj0o2cvv4e", "source_symbol": "llm.v1.workflows.generation.v1.ClientToolDispatch", "key": "API Schema/9ftjkkjhfa", "kind": "API Schema", "title": "ClientToolDispatch", "slug": "/api/models/schema-qj0o2cvv4e", "serialization": "json-names" }, { "doctype": "API Schema", "name": "i828te0das", "lineage_root": "s6i1d2bv7o", "source_symbol": "platform.v1.services.scheduler.v1.ScheduledTriggerEnvelope", "key": "API Schema/i828te0das", "kind": "API Schema", "title": "ScheduledTriggerEnvelope", "slug": "/api/models/schema-s6i1d2bv7o", "serialization": "json-names" } ], "schemas": { "llm_v1_services_mcp_v1_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 configuration to register.", "x-presence": "message", "allOf": [ { "$ref": "#/components/schemas/llm_v1_services_mcp_v1_CustomMCPServerInput" } ], "x-protovalidate": { "required": true }, "x-validation-scope": "request" } }, "x-request-required": [ "server" ], "required": [ "server" ] }, "llm_v1_services_mcp_v1_CustomMCPServerInput": { "type": "object", "description": "A project-scoped, HTTP-only MCP server definition, keyed (tenant\\_id, project\\_id, server\\_id). Its wire ID is \"custom:\\{server\\_id}\".\n\nCredentials must be stored as secret references; inline tokens must not be persisted in this server definition.\n\nauth\\_type selects the required credential fields. Authenticated modes require auth\\_secret\\_ref; NONE requires it to be empty. HEADER requires auth\\_header\\_name and QUERY requires auth\\_query\\_param; those names must be empty for every other mode. Inconsistent combinations are rejected before storage. Inline credentials are not accepted.\n\n### Input constraints\n\n### server\\_id\n\nThe server\\_id must contain one through 63 characters. Its first character must be a lowercase ASCII letter or digit. Every remaining character must be a lowercase ASCII letter, digit, or hyphen.\n\n### auth\\_header\\_name\n\nThe auth\\_header\\_name may be empty text. Otherwise it must contain one through 128 characters, each an ASCII letter, digit, or one of these literal punctuation characters: ! # $ % & ' \\* + . ^ \\_ \\` | \\~ -. No other character is accepted.\n\n### auth\\_query\\_param\n\nThe auth\\_query\\_param may be empty text. Otherwise it must contain one through 128 characters, each an ASCII letter, digit, period, underscore, tilde, or hyphen. No other character is accepted.\n\n### request\\_timeout\n\nThe request\\_timeout duration must be no greater than 120 seconds.", "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. The egress guard also rejects prohibited destinations such as metadata, loopback, private-network and in-cluster addresses. HTTPS alone does not satisfy these destination checks.", "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.\n\nAuthorization: Bearer \\