DigitalOcean API (unofficial showcase)
POST/v2/agents/triggers

CreateTrigger creates a webhook or cron trigger.

Validation is synchronous, so a mistake is a 400/409 at creation, not a silent miss at the first fire. Exactly one of webhook / cron must be present and match kind. kind=cron forbids a webhook block and requires a parseable cron.cron_expr and a valid IANA cron.timezone. session_mode=fresh requires session_template (a well-formed agents.yaml Agent manifest) and forbids bound_session_id; session_mode=reuse requires bound_session_id (an existing team-owned session) and forbids session_template. output.mode selects the destination block (email/slack), which is stored encrypted. name must be unique per team among non-deleted triggers.

For webhook triggers the response includes webhook_secret exactly ONCE - it is never returned again. Cron triggers return no secret and carry a computed trigger.cron.next_run_at. The team and user identity are taken from the authenticated principal, never the body.

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

9 body fields

The trigger to create.

kindstringrequired
How the trigger fires - on an event (webhook) or on a schedule (cron). Immutable after create.
Allowed:webhookcron
namestringrequired
Team-unique (among non-deleted triggers) trigger name. Same rules as session names; not UUID-form.
session_modestringrequired
fresh = a new session is created from the trigger's spec on every firing and destroyed after. reuse = the trigger binds an existing PAUSED session, resumed on each firing and paused after; multiple triggers may bind one session.
Allowed:freshreuse
prompt_templatestringrequired
The prompt sent on each fire. For cron it must not contain payload-interpolation placeholders.
outputobjectrequired
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 only. Full agents.yaml Agent manifest (YAML or JSON). Any embedded env values are split out and encrypted server-side.
bound_session_idstringoptional
reuse only. UUID of an existing session owned by the team.
webhookobjectoptional
webhook block on create. Omitting provider defaults to custom.
cronobjectoptional
cron block on create.

11 status codes
201Trigger created. `webhook_secret` present for webhook triggers only, shown once.
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.
webhook_secretstringoptional
The generated webhook secret. Present for webhook triggers only and shown EXACTLY ONCE - it is never returned again. Paste it into the external system's webhook configuration.
400Validation failed (bad manifest/cron/timezone, kind/block/mode mismatch, provider on cron, payload placeholder in a cron prompt, invalid email, etc.).
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.
401Authentication failed due to invalid credentials.
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.
403The caller is not permitted to create the backing agent config for this 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.
409A non-deleted trigger with this name already exists for the team.
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.
422The 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.
429The 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.
500There was a server 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.
502The backing agent config service returned 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.
503An upstream dependency needed to validate the trigger is temporarily unavailable; retry.
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: Validation failed (bad manifest/cron/timezone, kind/block/mode mismatch, provider on cron, payload placeholder in a cron prompt, invalid email, etc.). A 401 is returned: Authentication failed due to invalid credentials. A 403 is returned: The caller is not permitted to create the backing agent config for this trigger. A 409 is returned: A non-deleted trigger with this name already exists for the team. A 422 is returned: The team's trigger limit has been reached. A 429 is returned: The API rate limit has been exceeded. A 500 is returned: There was a server error. A 502 is returned: The backing agent config service returned an unexpected error. A 503 is returned: An upstream dependency needed to validate the trigger is temporarily unavailable; retry. Any other status is an error: There was an unexpected error.