Scheduled and triggered runs

A deployment starts agent sessions for you, either on a schedule or when an event arrives. Every firing creates a new session with a message you define, so the run shows up in session lists, executions and usage exactly like a session you started yourself.

When to use it

If your own code already decides when to run, call POST /v1/sessions directly; a deployment adds nothing.

Endpoints

Base URL https://app.syntic.ai/v1 (the paths above already include /v1). Authenticate with a private key and send syntic-beta: agents-2026-11-01, except on the inbound /trigger URL, which uses its own signing secret.

The deployment object

{
  "id": "dep_01JC9E2G4J6L8N0Q2S4U",
  "type": "deployment",
  "name": "daily-ticket-digest",
  "agent_id": "agt_01JC4R8W6Q2N9X3T5V7Y",
  "agent_version": null,
  "status": "active",
  "trigger": {
    "type": "schedule",
    "cron": "0 7 * * 1-5",
    "timezone": "Europe/London"
  },
  "input_template": "Summarise the support tickets opened on {{run.date_previous_day}}. Post the digest to #support-leads.",
  "session_options": { "memory_scope": "team:support", "limits": { "max_turns": 20 } },
  "concurrency": "skip_if_running",
  "next_run_at": "2026-11-06T07:00:00Z",
  "last_run": { "id": "drn_01JC9F...", "status": "succeeded", "session_id": "sesn_01JC9F...", "fired_at": "2026-11-05T07:00:00Z" },
  "created_at": "2026-11-01T12:00:00Z"
}

Triggers

Schedule

{ "type": "schedule", "cron": "0 7 * * 1-5", "timezone": "Europe/London" }

cron uses the usual five-field syntax; 0 7 * * 1-5, for example, means 07:00 on weekdays. timezone is an IANA name; default UTC. Daylight-saving changes follow the time zone, so a 07:00 job stays at 07:00 local time. The minimum interval is 5 minutes. Firings happen within 60 seconds of the scheduled time.

Webhook

{ "type": "webhook" }

When you create a webhook deployment, the response includes a trigger_url and a signing_secret (shown once). Your system calls:

POST https://app.syntic.ai/v1/deployments/dep_01JC9E2G4J6L8N0Q2S4U/trigger
Content-Type: application/json
syntic-signature: t=1762300800,v1=5d41402abc4b2a76b9719d911017c592...
 
{"order_id": "88123", "total": 412.50}

The signature is an HMAC-SHA256 of "<t>.<raw body>" with the signing secret, hex-encoded, the same scheme Syntic uses for outgoing webhooks. Requests older than 5 minutes or with a bad signature are refused with 401. The JSON body (up to 256 KB) is available to the template as {{payload}}. The response is 202 Accepted with the run id.

Manual

{ "type": "manual" }

Fires only through POST /v1/deployments/{id}/run. That endpoint also accepts an optional payload object for any trigger type.

Templates

Placeholders are substituted as text. Treat webhook payloads as untrusted input: they become part of a user message, and the agent’s instructions should say how to handle content it did not expect.

Create a scheduled deployment

curl -sS https://app.syntic.ai/v1/deployments \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "syntic-beta: agents-2026-11-01" \
  -d '{
    "name": "daily-ticket-digest",
    "agent_id": "agt_01JC4R8W6Q2N9X3T5V7Y",
    "trigger": {"type": "schedule", "cron": "0 7 * * 1-5", "timezone": "Europe/London"},
    "input_template": "Summarise the support tickets opened on {{run.date_previous_day}}.",
    "concurrency": "skip_if_running"
  }'

const res = await fetch('https://app.syntic.ai/v1/deployments', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNTIC_API_KEY}`,
    'Content-Type': 'application/json',
    'syntic-beta': 'agents-2026-11-01',
  },
  body: JSON.stringify({
    name: 'daily-ticket-digest',
    agent_id: 'agt_01JC4R8W6Q2N9X3T5V7Y',
    trigger: { type: 'schedule', cron: '0 7 * * 1-5', timezone: 'Europe/London' },
    input_template: 'Summarise the support tickets opened on {{run.date_previous_day}}.',
    concurrency: 'skip_if_running',
  }),
})
const dep = await res.json()
console.log(dep.id, dep.next_run_at)

import os, requests
 
dep = requests.post(
    "https://app.syntic.ai/v1/deployments",
    headers={"Authorization": f"Bearer {os.environ['SYNTIC_API_KEY']}", "syntic-beta": "agents-2026-11-01"},
    json={
        "name": "daily-ticket-digest",
        "agent_id": "agt_01JC4R8W6Q2N9X3T5V7Y",
        "trigger": {"type": "schedule", "cron": "0 7 * * 1-5", "timezone": "Europe/London"},
        "input_template": "Summarise the support tickets opened on {{run.date_previous_day}}.",
        "concurrency": "skip_if_running",
    },
).json()
print(dep["id"], dep["next_run_at"])

Run history

GET /v1/deployments/{id}/runs lists firings, newest first, with cursor pagination (limit, after_id, before_id). Each run has id, fired_at, trigger_type, status (started, skipped, queued, succeeded, failed), session_id (when a session was created), skip_reason (for example previous_run_active) and error. A run is succeeded when its session’s turn ends with outcome end_turn, and failed for any other outcome or if the session could not be started.

Subscribe to deployment.run.failed with webhooks to hear about failures without polling.

Errors

Errors use the error envelope.

Limits and billing

Deployments are free; the sessions they start are billed like any other session.

Build notes for the platform team

• Reuse the workflow trigger tick and activation functions for schedules and inbound webhooks.
• Each firing calls the same internal path as POST /v1/sessions, so limits, billing and audit stay identical.
• The auto-pause after 5 consecutive failures writes an audit event and sends deployment.paused.

Related

• Sessions
• Agent definitions API
• Webhooks
• Deployment: runtime nodes for Console agents