DigitalOcean API (unofficial showcase)
PATCH/v2/agents/triggers/{trigger_id}

Update a trigger

Updates a trigger's mutable settings, including its name, status, prompt template, output configuration, session configuration, and schedule. Supply only the fields you want to change; kind and webhook.provider cannot be changed, and updating session_template replaces the stored template. Re-enabling a trigger does not produce a catch-up run, and schedule changes recompute next_run_at.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 7 body fields
trigger_idstringrequired
The UUID of the trigger to update.

Partial trigger update; only supplied fields change. kind and webhook.provider are immutable.

namestringoptional
New team-unique trigger name. Same charset/length rules as create.
statusstringoptional
Trigger lifecycle state. Soft-deleted triggers are never returned (404).
Allowed:activepaused
prompt_templatestringoptional
The prompt template to use for trigger runs.
outputobjectoptional
Output-delivery configuration on create/update. Exactly one of email / slack is required for the matching mode and forbidden otherwise; destinations are stored encrypted and never returned.
session_templatestringoptional
fresh triggers only. A session_template PATCH is a full replacement of the stored template; you must resupply every spec.secrets slot value the new manifest declares, or the request is a 400.
bound_session_idstringoptional
reuse triggers only. UUID of an existing session owned by the team.
cronobjectoptional
cron block on create.

12 status codes
200Returns the updated trigger object. Secret values and protected output destinations are not returned.
triggerobjectoptional
A single automation bound to exactly one agent/session (agent == session in v1). The nested block present depends on `kind` (webhook xor cron) and `session_mode` (fresh => session_template; reuse => bound_session_id). `agent_kind` is read-only and derived; the webhook secret, the output email address / Slack webhook URL, and any env values inside session_template are write-only and never returned.
400Returned when trigger validation fails, including when a replacement session template omits a declared secret-slot value.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
401Returned when authentication fails because the credentials are invalid.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
403Returned when the caller is not permitted to create the backing agent config for the trigger.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
404Returned when the trigger resource is not found.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
409Returned when the name is a duplicate or the request attempts to change an immutable field such as `kind` or `webhook.provider`.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
422Returned when the team's trigger limit has been reached.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
429Returned when the API rate limit has been exceeded.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500Returned when a server error occurs.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
502Returned when the backing agent config service returns an unexpected error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
503Returned when a dependency needed to validate the trigger is temporarily unavailable.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
defaultThere was an unexpected error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Error handling

A 400 is returned when validation fails, including when a replacement session_template omits a declared secret slot value. A 401 indicates invalid credentials; a 403 indicates the caller is not permitted to create the backing agent config; a 404 indicates the trigger was not found; and a 409 indicates a duplicate name or an attempt to change an immutable field. A 422 indicates the team's trigger limit has been reached, a 429 indicates the API rate limit was exceeded, a 500 indicates a server error, a 502 indicates an unexpected error from the backing agent config service, and a 503 indicates a temporarily unavailable dependency; retry the request for a 503. name must be 1–64 characters and match the specified trigger-name pattern, status must be active or paused, and output.mode must be none, email, or slack; provide output.email only for email mode and output.slack.webhook_url for Slack mode. The trigger_id path parameter must identify an existing trigger.