pydo.harness.create_trigger()
Generated on 13 Nov 2026
from pydo version
v0.46.0
Usage
client.harness.create_trigger(
body={
"kind": "webhook",
"name": "nightly-deploy-check",
"session_mode": "fresh",
...,
},
)Description
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. Triggers do
not support persistent workspaces: a session_template that names workspace_id, and a
bound_session_id whose session has a workspace, are both refused.
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.
Parameters
kindstring requiredHow the trigger fires - on an event (webhook) or on a schedule (cron). Immutable after create.
namestring requiredExample:
nightly-deploy-checkTeam-unique (among non-deleted triggers) trigger name. Same rules as session names; not UUID-form.
session_modestring requiredfresh = 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.
prompt_templatestring requiredExample:
Review the latest push and summarize risks.The prompt sent on each fire. For cron it must not contain payload-interpolation placeholders.
outputobject requiredOutput-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.
Show child properties
modestring requirednone = nothing pushed; the result stays in run history for self-serve. email = the collected run output is emailed to a configured address. slack = the collected run output is posted to a Slack incoming webhook URL (channel fixed by the webhook at install time).
emailstring optionalExample:
[email protected]Destination address; required iff mode=email.
slackobject optionalSlack destination on create/update. webhook_url is required when mode=slack; must be https://hooks.slack.com/services/...; stored encrypted and never returned.
Show child properties
webhook_urlstring requiredExample:
https://hooks.slack.com/services/T0000/B0000/XXXXSlack incoming webhook URL (https://hooks.slack.com/services/...). The channel is bound to this URL at install time.
session_templatestring optionalfresh only. Full agents.yaml Agent manifest (YAML or JSON). Any embedded env values are split out and encrypted server-side.
bound_session_idstring optionalExample:
a1b2c3d4-e5f6-7890-abcd-ef1234567890reuse only. UUID of an existing session owned by the team.
webhookobject optionalwebhook block on create. Omitting provider defaults to custom.
Show child properties
providerstring optionalSignature-verification scheme applied to a delivery. Omitted on create defaults to custom.
cronobject optionalcron block on create.
Show child properties
cron_exprstring requiredExample:
0 9 * * 1-5timezonestring requiredExample:
America/New_YorkIANA timezone.
Request Sample
Response Example
More Information
See /v2/agents/triggers in the API reference for additional detail on responses, headers, parameters, and more.