Skip to main content
PATCH
Update automation

Permissions

Requires a service user with the ManageOrgAutomations permission at the organization level.

Merge semantics

Under the default merge_patch semantics, PATCH fields merge member-wise (RFC 7396 style): omitted members keep their stored value, explicit nulls clear, and empty groups are no-ops. Metadata merges per key, with null values deleting keys. Lists replace wholesale, while each sent element merges onto the stored element of the same type when that type occurs exactly once on both sides. Under replace_groups semantics, nothing merges: a sent object group replaces the stored group wholesale, and a sent triggers or actions list replaces the stored list wholesale with no element-wise merging. Resend every member you want to keep — omitted members are cleared or reset to their default. metadata is also a full replacement set, so removing a key means resending the set without it; null metadata values are rejected with a 400 rather than deleting keys. Omitted top-level fields still stay unchanged. Check the update_semantics field of the event schemas endpoint for the semantics active for your organization before relying on either behavior. Treat it as an open enum and tolerate values beyond the two above.

Webhook triggers

Re-adding a webhook:incoming trigger mints a new secret and returns it in the update response. This is the only time the secret is shown, so capture it when you receive it. Replacing or keeping an existing webhook trigger preserves the existing secret.

Authorizations

Authorization
string
header
required

Service User credential (prefix: cog_)

Path Parameters

automation_id
string
required
org_id
string
required

Organization ID (prefix: org-)

Example:

"org-abc123def456"

Body

application/json

PATCH fields merge member-wise by default: omitted members are kept, explicit nulls clear, and empty groups are no-ops. Metadata merges per key, with null values deleting keys. Lists replace wholesale (deletion = resend the list without the element), while each sent element merges onto the stored element of the same type when that type occurs exactly once on both sides. Element members that are required on create (prompt, setup_prompt, the monitor/triage slack configs, scan_id) may be omitted when a counterpart exists — they carry like any other member; explicit null is rejected.

actions
(AutomationStartSessionActionUpdate · object | AutomationMessageSessionActionUpdate · object | AutomationMonitorSessionActionUpdate · object)[] | null
concurrency
AutomationConcurrency · object | null
enabled
boolean | null
limits
AutomationLimits · object | null
metadata
Metadata · object | null
name
string | null
Required string length: 1 - 500
notifications
AutomationNotifications · object | null
run_as
AutomationRunAsOrganization · object

Identity the spawned sessions run under. organization: the org's automation identity (the System User in the app) — sessions use system permissions, so MCP servers installed with a personal (user-scoped) connection cannot be selected, and switching an automation to organization removes them from its selection. creator: personal automation — runs with the creator's own permissions and is visible only to the creator and org admins; rejected for service-user-created automations. Required on create; null on update resets to organization.

security_profile
AutomationSecurityProfileSelection · object | null

The automation's own security-profile binding: a profile_id pins that profile, {"profile_id": null} records an explicit opt-out, and explicit null reverts to inheriting from the org/enterprise. Requires the security-profile management permission.

session_settings
AutomationSessionSettings · object | null

Applied to every session this automation spawns (including monitor sessions).

tools
AutomationTools · object | null
triggers
AutomationTriggerRequest · object[] | null

Response

Successful Response

actions
(AutomationStartSessionAction · object | AutomationMessageSessionAction · object | AutomationMonitorSessionAction · object)[]
required
automation_id
string
required
created_at
integer
required
created_by
ActorResponse · object
required

A user or service-user principal attributed to an action or resource.

enabled
boolean
required
name
string
required
triggers
AutomationTriggerResponse · object[]
required
updated_at
integer
required
concurrency
AutomationConcurrency · object | null
last_edited_by
ActorResponse · object | null

A user or service-user principal attributed to an action or resource.

last_invocation
AutomationLastInvocation · object | null
limits
AutomationLimits · object | null
metadata
Metadata · object
notifications
AutomationNotifications · object | null
run_as
AutomationRunAsOrganization · object

Identity the spawned sessions run under. organization: the org's automation identity (the System User in the app) — sessions use system permissions, so MCP servers installed with a personal (user-scoped) connection cannot be selected, and switching an automation to organization removes them from its selection. creator: personal automation — runs with the creator's own permissions and is visible only to the creator and org admins; rejected for service-user-created automations. Required on create; null on update resets to organization.

security_profile
AutomationSecurityProfileResponse · object | null

The automation's security-profile binding and the resolved governing profiles. null when security profiles are not enabled for the organization.

session_settings
AutomationSessionSettings · object | null

Applied to every session this automation spawns (including monitor sessions).

template_id
string | null
tools
AutomationTools · object | null