> ## Documentation Index > Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a paused canonical automation > Creates a complete automation aggregate in the paused state after validating the pinned agent version, environment, and every trigger source. ## OpenAPI ````yaml /recursion/openapi.yaml post /managed-agents/v1/automations openapi: 3.1.0 info: title: Managed Agents API version: 0.14.0 description: >- The Recursion Managed Agents REST API. Authenticate with a Recursion API key as a bearer token. An organization-scoped key acts in its own organization and needs nothing else; a tenant-scoped key must also send `x-organization-id` with an organization id or `default`. Field names follow each operation's published schema. servers: - url: https://api.recursion.labelbox.com security: - bearerAuth: [] paths: /managed-agents/v1/automations: post: tags: - Automations summary: Create a paused canonical automation description: >- Creates a complete automation aggregate in the paused state after validating the pinned agent version, environment, and every trigger source. operationId: managedAgentsCreateAutomation parameters: - description: >- Replay-protection key in an organization-wide namespace shared by keyed mutations. It must contain 1 to 256 visible ASCII characters and be sent as exactly one header value. Request identity is the exact HTTP method, escaped path, raw query, and raw body bytes. For the legacy automation-run route only, the historical fingerprint ignores top-level JSON formatting and object-key order and removes the retired top-level idempotency_key field. The same request replays the original successful response; any different request returns 409 idempotency_conflict, and an active matching request returns 409 idempotency_in_progress. Completed receipts are retained for approximately 24 hours, pending claims may be reclaimed after approximately 1 hour, and no deduplication is guaranteed after expiry. in: header name: Idempotency-Key required: true schema: description: >- Replay-protection key in an organization-wide namespace shared by keyed mutations. It must contain 1 to 256 visible ASCII characters and be sent as exactly one header value. Request identity is the exact HTTP method, escaped path, raw query, and raw body bytes. For the legacy automation-run route only, the historical fingerprint ignores top-level JSON formatting and object-key order and removes the retired top-level idempotency_key field. The same request replays the original successful response; any different request returns 409 idempotency_conflict, and an active matching request returns 409 idempotency_in_progress. Completed receipts are retained for approximately 24 hours, pending claims may be reclaimed after approximately 1 hour, and no deduplication is guaranteed after expiry. maxLength: 256 minLength: 1 pattern: ^[!-~]+$ type: string - $ref: '#/components/parameters/RecursionTenantId' - $ref: '#/components/parameters/RecursionOrganizationId' requestBody: content: application/json: schema: $ref: '#/components/schemas/AutomationDefinitionCreateRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/AutomationDefinitionResponse' description: Full round-trippable canonical automation aggregate. headers: ETag: description: Strong validator for this resource revision. schema: type: string style: simple Idempotency-Replayed: description: True when this response replays an earlier completed request. schema: type: boolean style: simple Location: description: Relative URL of the created resource. schema: type: string style: simple recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '400': description: Bad Request. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidJson' - $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' discriminator: propertyName: code mapping: invalid_json: '#/components/schemas/ManagedAgentsApiErrorInvalidJson' invalid_request: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' x-recursion-error-codes: - invalid_json - invalid_request headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnauthorized' x-recursion-error-codes: - unauthorized headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden' x-recursion-error-codes: - forbidden headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '404': description: Not Found. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorNotFound' x-recursion-error-codes: - not_found headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '409': headers: Retry-After: description: >- When present, delay in seconds or an HTTP-date after which the caller may retry; absence supplies no retry advice. schema: type: string style: simple recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: Conflict. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorAutomationTriggerIdInUse - $ref: '#/components/schemas/ManagedAgentsApiErrorConflict' - $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyConflict - $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyInProgress discriminator: propertyName: code mapping: automation_trigger_id_in_use: >- #/components/schemas/ManagedAgentsApiErrorAutomationTriggerIdInUse conflict: '#/components/schemas/ManagedAgentsApiErrorConflict' idempotency_conflict: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyConflict idempotency_in_progress: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyInProgress x-recursion-error-codes: - automation_trigger_id_in_use - conflict - idempotency_conflict - idempotency_in_progress '413': description: Payload Too Large. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorPayloadTooLarge' x-recursion-error-codes: - payload_too_large headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '415': description: Unsupported Media Type. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnsupportedMediaType' x-recursion-error-codes: - unsupported_media_type headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '422': description: Unprocessable Entity. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorAutomationEventSourceInvalid - $ref: >- #/components/schemas/ManagedAgentsApiErrorAutomationReferenceInvalid discriminator: propertyName: code mapping: automation_event_source_invalid: >- #/components/schemas/ManagedAgentsApiErrorAutomationEventSourceInvalid automation_reference_invalid: >- #/components/schemas/ManagedAgentsApiErrorAutomationReferenceInvalid x-recursion-error-codes: - automation_event_source_invalid - automation_reference_invalid headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '429': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: Too Many Requests. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorRateLimitExceeded' x-recursion-error-codes: - rate_limit_exceeded '500': description: Internal Server Error. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorInternalError' x-recursion-error-codes: - internal_error headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '502': description: A dependent service returned an invalid response. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorDependencyFailure' x-recursion-error-codes: - bad_gateway headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '503': description: Service Unavailable. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorAutomationsUnconfigured - $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable discriminator: propertyName: code mapping: automations_unconfigured: >- #/components/schemas/ManagedAgentsApiErrorAutomationsUnconfigured idempotency_unavailable: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyUnavailable managed_agents_unavailable: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable service_unavailable: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable x-recursion-error-codes: - automations_unconfigured - idempotency_unavailable - managed_agents_unavailable - service_unavailable headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '504': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: A dependent service timed out. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorDependencyTimeout' x-recursion-error-codes: - gateway_timeout components: parameters: RecursionTenantId: name: x-tenant-id in: header required: false description: >- Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is `default`. schema: type: string minLength: 1 RecursionOrganizationId: name: x-organization-id in: header required: false description: >- Organization in which to act. Required for a tenant-scoped API key. Optional for an organization-scoped key, where it must name that same organization. The value may be an organization id or `default`. schema: type: string minLength: 1 schemas: AutomationDefinitionCreateRequest: additionalProperties: false description: Writable shape for creating a canonical automation. properties: agentId: description: Managed agent selected by this automation. format: uuid type: string agentVersionId: description: Immutable agent version pinned for all admitted runs. format: uuid type: string displayName: description: Human-readable automation name. maxLength: 256 minLength: 1 type: string environmentId: description: Execution environment selected for admitted sessions. format: uuid type: string initialPrompt: $ref: '#/components/schemas/AutomationLiteralPrompt' description: Prompt definition frozen onto admitted runs. metadata: additionalProperties: type: string description: >- Caller-owned string labels stored with the automation and returned on reads, such as a marker naming the system that manages it. Never copied to runs or sessions. At most 32 entries; keys use letters, digits, '_', '.', and '-' up to 64 characters; values are 1-512 characters without control characters. Omit for none. maxProperties: 32 type: object x-recursion-omission: strategy: absent runDefaults: $ref: '#/components/schemas/CanonicalAutomationCreateRunDefaults' description: Run defaults frozen onto admitted runs. triggers: description: Complete trigger set for this automation aggregate. items: $ref: '#/components/schemas/CanonicalAutomationTriggerRequest' maxItems: 20 type: array required: - displayName - agentId - agentVersionId - environmentId - initialPrompt - triggers type: object AutomationDefinitionResponse: additionalProperties: false description: Full round-trippable canonical automation aggregate. properties: agentId: description: Managed agent selected by this automation. format: uuid type: string agentVersionId: description: Immutable agent version pinned for all admitted runs. format: uuid type: string automationId: description: Stable canonical automation identifier. format: uuid readOnly: true type: string createdAt: description: Time the automation was created. format: date-time readOnly: true type: string displayName: description: Human-readable automation name. type: string environmentId: description: Execution environment selected for admitted sessions. format: uuid type: string initialPrompt: $ref: '#/components/schemas/AutomationLiteralPrompt' description: Prompt definition frozen onto admitted runs. metadata: additionalProperties: type: string description: >- Caller-owned string labels stored with the automation. Absent when none were set. type: object revision: description: Monotonic aggregate revision represented by the response ETag. format: int64 minimum: 1 readOnly: true type: integer maximum: 9007199254740991 runDefaults: $ref: '#/components/schemas/CanonicalAutomationRunDefaults' description: Run defaults frozen onto admitted runs. status: description: Lifecycle state. New automations start paused. enum: - paused - active readOnly: true type: string triggers: description: Complete ordered trigger set. items: $ref: '#/components/schemas/CanonicalAutomationTrigger' type: array updatedAt: description: Time the aggregate was last changed. format: date-time readOnly: true type: string required: - automationId - displayName - agentId - agentVersionId - environmentId - initialPrompt - runDefaults - triggers - status - revision - createdAt - updatedAt type: object ManagedAgentsApiErrorInvalidJson: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - invalid_json message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorInvalidRequest: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - invalid_request message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorUnauthorized: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - unauthorized message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorForbidden: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - forbidden message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorNotFound: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - not_found message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorAutomationTriggerIdInUse: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - automation_trigger_id_in_use message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorConflict: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - conflict message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorIdempotencyConflict: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - idempotency_conflict message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorIdempotencyInProgress: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - idempotency_in_progress message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorPayloadTooLarge: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - payload_too_large message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorUnsupportedMediaType: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - unsupported_media_type message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorAutomationEventSourceInvalid: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - automation_event_source_invalid message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorAutomationReferenceInvalid: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - automation_reference_invalid message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorRateLimitExceeded: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - rate_limit_exceeded message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorInternalError: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - internal_error message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorDependencyFailure: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - bad_gateway message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorAutomationsUnconfigured: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - automations_unconfigured message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorIdempotencyUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - idempotency_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorManagedAgentsUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - managed_agents_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorServiceUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - service_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorDependencyTimeout: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - gateway_timeout message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. AutomationLiteralPrompt: additionalProperties: false description: Literal initial prompt frozen onto each admitted automation run. properties: text: description: Initial instruction supplied to every admitted run. maxLength: 65536 minLength: 1 type: string type: description: Literal prompt text with no interpolation. enum: - literal type: string required: - type - text type: object CanonicalAutomationCreateRunDefaults: additionalProperties: false description: >- Session metadata, credential grants, files and memory applied to every trigger and manual admission. Omit for none: metadata null, agent grants inherited. properties: credentialRefs: description: >- Exact credential selection within vaultIds. Requires explicit vaultIds. Omit to grant all items in the selected vaults. items: $ref: '#/components/schemas/AutomationDefinitionCredentialRef' maxItems: 500 type: array x-recursion-omission: strategy: absent metadata: additionalProperties: type: string description: >- String metadata copied to every admitted session. Omit or send null for none. type: - object - 'null' x-recursion-omission: strategy: absent resources: description: Files resolved and mounted when each session starts. items: $ref: '#/components/schemas/AutomationDefinitionResource' maxItems: 500 type: array x-recursion-omission: strategy: absent vaultIds: description: >- Vaults available to each session. Omit to inherit the pinned agent defaults; an empty list grants no vault access. items: type: string maxItems: 50 type: array uniqueItems: true x-recursion-omission: strategy: absent type: object x-recursion-omission: strategy: absent CanonicalAutomationTriggerRequest: description: >- One trigger of a canonical automation: a schedule, a Slack event, a GitHub event, or a custom webhook. oneOf: - $ref: '#/components/schemas/HttpapiAutomationScheduleTriggerRequest' - $ref: '#/components/schemas/AutomationSlackTriggerRequest' - $ref: '#/components/schemas/AutomationGitHubTriggerRequest' - $ref: '#/components/schemas/HttpapiAutomationWebhookTriggerRequest' type: object unevaluatedProperties: false CanonicalAutomationRunDefaults: additionalProperties: false description: >- Session metadata, credential grants, files and memory applied to every trigger and manual admission. properties: credentialRefs: description: >- Exact credential selection within vaultIds. Requires explicit vaultIds. Omit to grant all items in the selected vaults. items: $ref: '#/components/schemas/AutomationDefinitionCredentialRef' maxItems: 500 type: array metadata: additionalProperties: type: string description: String metadata copied to every admitted session. type: - object - 'null' resources: description: Files resolved and mounted when each session starts. items: $ref: '#/components/schemas/AutomationDefinitionResource' maxItems: 500 type: array vaultIds: description: >- Vaults available to each session. Omit to inherit the pinned agent defaults; an empty list grants no vault access. items: type: string maxItems: 50 type: array uniqueItems: true required: - metadata type: object CanonicalAutomationTrigger: description: >- One trigger of a canonical automation: a schedule, a Slack event, a GitHub event, or a custom webhook. oneOf: - $ref: '#/components/schemas/HttpapiAutomationScheduleTrigger' - $ref: '#/components/schemas/AutomationSlackTrigger' - $ref: '#/components/schemas/AutomationGitHubTrigger' - $ref: '#/components/schemas/HttpapiAutomationWebhookTrigger' type: object unevaluatedProperties: false ManagedAgentsApiErrorDetails: type: object properties: field: description: >- Request field or header responsible for the error, when one can be identified. type: string issues: description: >- Boundary-validation failures as path-prefixed human-readable messages. type: array items: type: string requestId: description: Request correlation identifier for support and log lookup. type: string retryable: description: >- Server advice about failure transience. `true` means transient, `false` means non-transient, and absence gives no advice. Automatic replay is allowed only when this field is not `false` and the operation-specific retry and idempotency contract permits replay. type: boolean additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. AutomationDefinitionCredentialRef: additionalProperties: false description: An exact credential grant within a selected vault. properties: credentialId: description: Credential to grant to the session. minLength: 1 type: string vaultId: description: Selected vault containing the credential. minLength: 1 type: string required: - vaultId - credentialId type: object AutomationDefinitionResource: additionalProperties: false description: >- A file from this organization, mounted at an explicit path for each automation session. properties: fileId: description: File to attach from this organization. minLength: 1 type: string mountPath: description: Absolute mount path beneath the session files directory. minLength: 1 type: string required: - fileId - mountPath type: object HttpapiAutomationScheduleTriggerRequest: additionalProperties: false description: Closed schedule-trigger configuration. properties: enabled: description: Whether this trigger may admit runs while the automation is active. type: boolean schedule: $ref: '#/components/schemas/AutomationScheduleConfigRequest' description: Schedule timing and overlap policy. triggerId: description: Caller-generated stable trigger identifier. format: uuid type: string type: description: Schedule trigger discriminant. enum: - schedule type: string required: - triggerId - type - schedule - enabled type: object AutomationSlackTriggerRequest: additionalProperties: false description: Closed Slack Events API trigger configuration. properties: allowSharedChannels: default: false description: >- Explicitly allow events from Slack Connect channels shared with other organizations. Defaults to false. type: boolean botEvents: $ref: '#/components/schemas/AutomationSlackBotEvents' description: Explicit external-bot policy. continuation: default: new_session description: >- When resume_thread, a later matching post in the same Slack thread is delivered to the thread's existing session instead of starting a new one. Defaults to new_session. Every Slack trigger of one automation must use the same value. enum: - new_session - resume_thread type: string enabled: description: Whether this trigger may admit runs while the automation is active. type: boolean eventSourceId: description: Compatible Slack Events API source. format: uuid type: string events: description: >- Slack event types that may match this trigger. Only newly posted messages match; edits and deletions never start runs. items: enum: - message - app_mention type: string maxItems: 2 minItems: 1 type: array uniqueItems: true filters: $ref: '#/components/schemas/AutomationSlackFiltersRequest' description: >- Optional conditions on the message. Omit to match every routed event. x-recursion-omission: strategy: absent firstResponse: default: none description: >- When platform, the platform posts an acknowledgement, a reaction and a live status line in the thread while the agent works. Defaults to none. Every Slack trigger of one automation must use the same value. enum: - none - platform type: string routing: $ref: '#/components/schemas/AutomationSlackRouting' description: Workspace and channel constraints. triggerId: description: Caller-generated stable trigger identifier. format: uuid type: string type: description: Slack trigger discriminant. enum: - slack type: string required: - triggerId - type - eventSourceId - events - routing - botEvents - enabled type: object AutomationGitHubTriggerRequest: additionalProperties: false description: Closed GitHub webhook trigger configuration. properties: enabled: description: Whether this trigger may admit runs while the automation is active. type: boolean eventSourceId: description: Compatible GitHub webhook source. format: uuid type: string events: description: GitHub webhook event names that may match this trigger. items: enum: - pull_request - pull_request_review - issue_comment - issues - workflow_run - push type: string maxItems: 32 minItems: 1 type: array uniqueItems: true filters: $ref: '#/components/schemas/AutomationGitHubFiltersRequest' description: >- Optional conditions on the delivery body. Omit to match on event name alone. x-recursion-omission: strategy: absent triggerId: description: Caller-generated stable trigger identifier. format: uuid type: string type: description: GitHub trigger discriminant. enum: - github type: string required: - triggerId - type - eventSourceId - events - enabled type: object HttpapiAutomationWebhookTriggerRequest: additionalProperties: false description: Closed custom-webhook trigger configuration. properties: enabled: description: Whether this trigger may admit runs while the automation is active. type: boolean eventSourceId: description: Compatible custom webhook source. format: uuid type: string filters: $ref: '#/components/schemas/AutomationWebhookFiltersRequest' description: >- Optional body conditions. Omit to match every delivery from the source. x-recursion-omission: strategy: absent triggerId: description: Caller-generated stable trigger identifier. format: uuid type: string type: description: Custom-webhook trigger discriminant. enum: - webhook type: string required: - triggerId - type - eventSourceId - enabled type: object HttpapiAutomationScheduleTrigger: additionalProperties: false description: Closed schedule-trigger configuration. properties: enabled: description: Whether this trigger may admit runs while the automation is active. type: boolean schedule: $ref: '#/components/schemas/AutomationScheduleConfig' description: Schedule timing and overlap policy. triggerId: description: Caller-generated stable trigger identifier. format: uuid type: string type: description: Schedule trigger discriminant. enum: - schedule type: string required: - triggerId - type - schedule - enabled type: object AutomationSlackTrigger: additionalProperties: false description: Closed Slack Events API trigger configuration. properties: allowSharedChannels: default: false description: >- Explicitly allow events from Slack Connect channels shared with other organizations. Defaults to false. type: boolean botEvents: $ref: '#/components/schemas/AutomationSlackBotEvents' description: Explicit external-bot policy. continuation: default: new_session description: >- When resume_thread, a later matching post in the same Slack thread is delivered to the thread's existing session instead of starting a new one. Defaults to new_session. Every Slack trigger of one automation must use the same value. enum: - new_session - resume_thread type: string enabled: description: Whether this trigger may admit runs while the automation is active. type: boolean eventSourceId: description: Compatible Slack Events API source. format: uuid type: string events: description: >- Slack event types that may match this trigger. Only newly posted messages match; edits and deletions never start runs. items: enum: - message - app_mention type: string maxItems: 2 minItems: 1 type: array uniqueItems: true filters: $ref: '#/components/schemas/AutomationSlackFilters' description: >- Optional conditions on the message. Omit to match every routed event. firstResponse: default: none description: >- When platform, the platform posts an acknowledgement, a reaction and a live status line in the thread while the agent works. Defaults to none. Every Slack trigger of one automation must use the same value. enum: - none - platform type: string routing: $ref: '#/components/schemas/AutomationSlackRouting' description: Workspace and channel constraints. triggerId: description: Caller-generated stable trigger identifier. format: uuid type: string type: description: Slack trigger discriminant. enum: - slack type: string required: - triggerId - type - eventSourceId - events - routing - botEvents - enabled type: object AutomationGitHubTrigger: additionalProperties: false description: Closed GitHub webhook trigger configuration. properties: enabled: description: Whether this trigger may admit runs while the automation is active. type: boolean eventSourceId: description: Compatible GitHub webhook source. format: uuid type: string events: description: GitHub webhook event names that may match this trigger. items: type: string maxItems: 32 minItems: 1 type: array uniqueItems: true filters: $ref: '#/components/schemas/AutomationGitHubFilters' description: >- Optional conditions on the delivery body. Omit to match on event name alone. triggerId: description: Caller-generated stable trigger identifier. format: uuid type: string type: description: GitHub trigger discriminant. enum: - github type: string required: - triggerId - type - eventSourceId - events - enabled type: object HttpapiAutomationWebhookTrigger: additionalProperties: false description: Closed custom-webhook trigger configuration. properties: enabled: description: Whether this trigger may admit runs while the automation is active. type: boolean eventSourceId: description: Compatible custom webhook source. format: uuid type: string filters: $ref: '#/components/schemas/AutomationWebhookFilters' description: >- Optional body conditions. Omit to match every delivery from the source. triggerId: description: Caller-generated stable trigger identifier. format: uuid type: string type: description: Custom-webhook trigger discriminant. enum: - webhook type: string required: - triggerId - type - eventSourceId - enabled type: object PlatformSafeJsonValue: description: >- A JSON value whose integer members stay within the exact ECMAScript safe-integer range at every nesting level. oneOf: - type: 'null' - type: boolean - type: string - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: number not: type: integer - type: array items: $ref: '#/components/schemas/PlatformSafeJsonValue' - additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' type: object AutomationScheduleConfigRequest: additionalProperties: false description: Complete canonical schedule configuration. properties: catchupWindowSeconds: default: 900 description: >- Maximum age of a missed occurrence eligible for catch-up. Defaults to 900. maximum: 31622400 minimum: 10 type: - 'null' - integer cron: description: Five-field POSIX cron expression. maxLength: 256 minLength: 1 type: string endAt: description: Optional inclusive schedule end. format: date-time type: - 'null' - string x-recursion-omission: strategy: absent jitterSeconds: default: 10 description: >- Maximum deterministic occurrence jitter in seconds. Defaults to 10; zero disables jitter. maximum: 540 minimum: 0 type: - 'null' - integer overlapPolicy: default: skip description: >- Behavior when an earlier occurrence is still running. Defaults to skip. enum: - skip - buffer_one - buffer_all - allow_all - cancel_other type: string startAt: description: Optional inclusive schedule start. format: date-time type: - 'null' - string x-recursion-omission: strategy: absent timezone: description: IANA timezone used to interpret the cron expression. maxLength: 256 minLength: 1 type: string required: - cron - timezone type: object AutomationSlackBotEvents: additionalProperties: false description: Trigger-local handling for messages authored by external Slack apps. properties: mode: description: Whether events authored by a provably different Slack app may match. enum: - ignore - allow_external type: string required: - mode type: object AutomationSlackFiltersRequest: additionalProperties: false description: Optional conditions on the Slack message author, text, and threading. properties: fromUserIds: description: >- Authors whose messages may match, as listed by the connection's member catalog: a person's user id (U or W) or an app's bot id (B). Empty accepts anyone. A listed bot id lets that app's messages match even when botEvents.mode is ignore. items: maxLength: 256 minLength: 1 pattern: ^[UWB][A-Z0-9]{2,63}$ type: string maxItems: 100 type: array uniqueItems: true x-recursion-omission: strategy: absent ignoreThreadReplies: description: Reject replies inside a thread; only top-level messages match. type: boolean x-recursion-omission: strategy: absent textContains: description: >- The message must contain at least one of these phrases, ignoring case. items: maxLength: 256 minLength: 1 type: string maxItems: 20 type: array uniqueItems: true x-recursion-omission: strategy: absent textExcludes: description: The message must contain none of these phrases, ignoring case. items: maxLength: 256 minLength: 1 type: string maxItems: 20 type: array uniqueItems: true x-recursion-omission: strategy: absent textMatches: description: An RE2 regular expression the message must match, ignoring case. maxLength: 256 type: string x-recursion-omission: strategy: absent type: object x-recursion-omission: strategy: absent AutomationSlackRouting: additionalProperties: false description: Workspace and channel routing constraints for a Slack trigger. properties: channelIds: description: >- Slack channel ids accepted by this trigger; an empty list accepts every channel. items: type: string maxItems: 100 type: array uniqueItems: true workspaceIds: description: >- Slack workspace ids accepted by this trigger; an empty list accepts every workspace received by the source. items: type: string maxItems: 50 type: array uniqueItems: true required: - workspaceIds - channelIds type: object AutomationGitHubFiltersRequest: additionalProperties: false description: >- Optional conditions on the verified GitHub delivery body. Every present condition must match; empty lists accept any value. properties: actions: description: >- GitHub delivery action values that may match, such as opened, labeled, submitted, or completed. Empty accepts every action. items: maxLength: 256 minLength: 1 type: string maxItems: 16 type: array uniqueItems: true x-recursion-omission: strategy: absent addedLabels: description: 'For labeled deliveries: the added label must be one of these.' items: maxLength: 256 minLength: 1 type: string maxItems: 50 type: array uniqueItems: true x-recursion-omission: strategy: absent baseBranches: description: >- Pull request base branch globs. An asterisk matches any characters, including slashes; a question mark matches one character. items: maxLength: 256 minLength: 1 type: string maxItems: 20 type: array uniqueItems: true x-recursion-omission: strategy: absent branches: description: >- Branch globs for the pushed branch, the workflow run head branch, or the pull request head branch, with the same syntax as baseBranches. items: maxLength: 256 minLength: 1 type: string maxItems: 20 type: array uniqueItems: true x-recursion-omission: strategy: absent commentOn: description: >- For issue_comment deliveries: whether the comment is on a pull request or on an issue. enum: - pull_request - issue type: string x-recursion-omission: strategy: absent conclusions: description: >- For completed workflow runs: conclusions such as failure, success, or cancelled. Empty accepts any conclusion. items: maxLength: 256 minLength: 1 type: string maxItems: 8 type: array uniqueItems: true x-recursion-omission: strategy: absent excludeDrafts: description: Reject draft pull requests. type: boolean x-recursion-omission: strategy: absent ignoreBots: description: Reject deliveries whose sender is a GitHub bot account. type: boolean x-recursion-omission: strategy: absent labelsAny: description: >- Match only when the pull request or issue carries at least one of these labels. items: maxLength: 256 minLength: 1 type: string maxItems: 50 type: array uniqueItems: true x-recursion-omission: strategy: absent labelsNone: description: Reject when the pull request or issue carries any of these labels. items: maxLength: 256 minLength: 1 type: string maxItems: 50 type: array uniqueItems: true x-recursion-omission: strategy: absent merged: description: >- For closed pull requests: true matches merged, false matches closed without merging. type: boolean x-recursion-omission: strategy: absent repositories: description: >- Repository full names (owner/name), compared case-insensitively. Empty accepts every repository. items: maxLength: 256 minLength: 1 type: string maxItems: 100 type: array uniqueItems: true x-recursion-omission: strategy: absent reviewStates: description: >- For submitted reviews: approved, changes_requested, or commented. Empty accepts any review. items: maxLength: 256 minLength: 1 type: string maxItems: 3 type: array uniqueItems: true x-recursion-omission: strategy: absent senders: description: >- GitHub logins of the account that caused the delivery. Empty accepts anyone. items: maxLength: 256 minLength: 1 type: string maxItems: 100 type: array uniqueItems: true x-recursion-omission: strategy: absent textContains: description: >- The comment or review body, or else the pull request or issue title and body, must contain at least one of these phrases, ignoring case. items: maxLength: 256 minLength: 1 type: string maxItems: 20 type: array uniqueItems: true x-recursion-omission: strategy: absent textExcludes: description: >- The comment or review body, or else the pull request or issue title and body, must contain none of these phrases, ignoring case. items: maxLength: 256 minLength: 1 type: string maxItems: 20 type: array uniqueItems: true x-recursion-omission: strategy: absent textMatches: description: >- An RE2 regular expression the comment or review body, or else the pull request or issue title and body, must match, ignoring case. maxLength: 256 type: string x-recursion-omission: strategy: absent type: object x-recursion-omission: strategy: absent AutomationWebhookFiltersRequest: additionalProperties: false description: Optional conditions on the custom webhook body. properties: fieldEquals: description: Conditions that must all hold. items: $ref: '#/components/schemas/AutomationWebhookFieldCondition' maxItems: 20 minItems: 1 type: array required: - fieldEquals type: object x-recursion-omission: strategy: absent AutomationScheduleConfig: additionalProperties: false description: Complete canonical schedule configuration. properties: catchupWindowSeconds: default: 900 description: >- Maximum age of a missed occurrence eligible for catch-up. Defaults to 900. maximum: 31622400 minimum: 10 type: - 'null' - integer cron: description: Five-field POSIX cron expression. maxLength: 256 minLength: 1 type: string endAt: description: Optional inclusive schedule end. format: date-time type: - 'null' - string jitterSeconds: default: 10 description: >- Maximum deterministic occurrence jitter in seconds. Defaults to 10; zero disables jitter. maximum: 540 minimum: 0 type: - 'null' - integer overlapPolicy: default: skip description: >- Behavior when an earlier occurrence is still running. Defaults to skip. enum: - skip - buffer_one - buffer_all - allow_all - cancel_other type: string startAt: description: Optional inclusive schedule start. format: date-time type: - 'null' - string timezone: description: IANA timezone used to interpret the cron expression. maxLength: 256 minLength: 1 type: string required: - cron - timezone type: object AutomationSlackFilters: additionalProperties: false description: Optional conditions on the Slack message author, text, and threading. properties: fromUserIds: description: >- Authors whose messages may match, as listed by the connection's member catalog: a person's user id (U or W) or an app's bot id (B). Empty accepts anyone. A listed bot id lets that app's messages match even when botEvents.mode is ignore. items: maxLength: 256 minLength: 1 pattern: ^[UWB][A-Z0-9]{2,63}$ type: string maxItems: 100 type: array uniqueItems: true ignoreThreadReplies: description: Reject replies inside a thread; only top-level messages match. type: boolean textContains: description: >- The message must contain at least one of these phrases, ignoring case. items: maxLength: 256 minLength: 1 type: string maxItems: 20 type: array uniqueItems: true textExcludes: description: The message must contain none of these phrases, ignoring case. items: maxLength: 256 minLength: 1 type: string maxItems: 20 type: array uniqueItems: true textMatches: description: An RE2 regular expression the message must match, ignoring case. maxLength: 256 type: string type: object AutomationGitHubFilters: additionalProperties: false description: >- Optional conditions on the verified GitHub delivery body. Every present condition must match; empty lists accept any value. properties: actions: description: >- GitHub delivery action values that may match, such as opened, labeled, submitted, or completed. Empty accepts every action. items: maxLength: 256 minLength: 1 type: string maxItems: 16 type: array uniqueItems: true addedLabels: description: 'For labeled deliveries: the added label must be one of these.' items: maxLength: 256 minLength: 1 type: string maxItems: 50 type: array uniqueItems: true baseBranches: description: >- Pull request base branch globs. An asterisk matches any characters, including slashes; a question mark matches one character. items: maxLength: 256 minLength: 1 type: string maxItems: 20 type: array uniqueItems: true branches: description: >- Branch globs for the pushed branch, the workflow run head branch, or the pull request head branch, with the same syntax as baseBranches. items: maxLength: 256 minLength: 1 type: string maxItems: 20 type: array uniqueItems: true commentOn: description: >- For issue_comment deliveries: whether the comment is on a pull request or on an issue. enum: - pull_request - issue type: string conclusions: description: >- For completed workflow runs: conclusions such as failure, success, or cancelled. Empty accepts any conclusion. items: maxLength: 256 minLength: 1 type: string maxItems: 8 type: array uniqueItems: true excludeDrafts: description: Reject draft pull requests. type: boolean ignoreBots: description: Reject deliveries whose sender is a GitHub bot account. type: boolean labelsAny: description: >- Match only when the pull request or issue carries at least one of these labels. items: maxLength: 256 minLength: 1 type: string maxItems: 50 type: array uniqueItems: true labelsNone: description: Reject when the pull request or issue carries any of these labels. items: maxLength: 256 minLength: 1 type: string maxItems: 50 type: array uniqueItems: true merged: description: >- For closed pull requests: true matches merged, false matches closed without merging. type: boolean repositories: description: >- Repository full names (owner/name), compared case-insensitively. Empty accepts every repository. items: maxLength: 256 minLength: 1 type: string maxItems: 100 type: array uniqueItems: true reviewStates: description: >- For submitted reviews: approved, changes_requested, or commented. Empty accepts any review. items: maxLength: 256 minLength: 1 type: string maxItems: 3 type: array uniqueItems: true senders: description: >- GitHub logins of the account that caused the delivery. Empty accepts anyone. items: maxLength: 256 minLength: 1 type: string maxItems: 100 type: array uniqueItems: true textContains: description: >- The comment or review body, or else the pull request or issue title and body, must contain at least one of these phrases, ignoring case. items: maxLength: 256 minLength: 1 type: string maxItems: 20 type: array uniqueItems: true textExcludes: description: >- The comment or review body, or else the pull request or issue title and body, must contain none of these phrases, ignoring case. items: maxLength: 256 minLength: 1 type: string maxItems: 20 type: array uniqueItems: true textMatches: description: >- An RE2 regular expression the comment or review body, or else the pull request or issue title and body, must match, ignoring case. maxLength: 256 type: string type: object AutomationWebhookFilters: additionalProperties: false description: Optional conditions on the custom webhook body. properties: fieldEquals: description: Conditions that must all hold. items: $ref: '#/components/schemas/AutomationWebhookFieldCondition' maxItems: 20 minItems: 1 type: array required: - fieldEquals type: object AutomationWebhookFieldCondition: additionalProperties: false description: One equality condition on a custom webhook body. properties: path: description: >- Dot-separated path into the JSON body, such as data.level. Decimal segments index arrays. maxLength: 256 minLength: 1 type: string value: description: >- Expected scalar written as JSON text without quotes: a string as-is, a number, true, false, or null. maxLength: 1024 type: string required: - path - value type: object headers: RecursionOrganizationId: description: Organization id resolved for this request. schema: type: string minLength: 1 RecursionTenantId: description: Tenant id resolved for this request. schema: type: string minLength: 1 securitySchemes: bearerAuth: type: http scheme: bearer description: A Recursion API key, created in the console under API keys. ````