Scheduling

Two ways to trigger agents on a schedule: cron schedules for time-based runs, and webhook triggers for event-driven runs from external systems.

Cron schedules

Create a named schedule that runs an agent on a cron expression. Theazo handles overlap prevention — if a previous run is still active when the next trigger fires, the new run is skipped.

schedule.ts

import { Theazo } from class="cb-str">'theazo'

const theazo = new Theazo({ apiKey: class="cb-str">'th_live_...' })

const schedule = await theazo.schedules.create({
  name: class="cb-str">'daily-digest',
  agent: class="cb-str">'digest-writer',
  userId: class="cb-str">'user_123',
  cron: class="cb-str">'0 9 * * 1-5',       class="cb-cmt">// 9am Monday–Friday
  timezone: class="cb-str">'America/New_York',
  input: {
    sources: [class="cb-str">'hackernews', class="cb-str">'producthunt', class="cb-str">'arxiv'],
    topics:  [class="cb-str">'AI', class="cb-str">'infrastructure', class="cb-str">'developer tools'],
    format:  class="cb-str">'markdown',
  },
})

console.log(schedule.id)       class="cb-cmt">// 'sch_abc123'
console.log(schedule.nextRun)  class="cb-cmt">// '2024-01-16T14:00:00Z' (UTC)

Cron expressions follow standard 5-field syntax: minute hour day month weekday. All times are stored in UTC and converted using the timezone field. Supported timezones are IANA names (e.g. Europe/London, Asia/Tokyo).

Common cron expressions

class="cb-str">'0 * * * *'       class="cb-cmt">// every hour at :00
class="cb-str">'*/15 * * * *'    class="cb-cmt">// every 15 minutes
class="cb-str">'0 9 * * 1-5'     class="cb-cmt">// 9am weekdays
class="cb-str">'0 0 * * 0'       class="cb-cmt">// midnight every Sunday
class="cb-str">'0 8 1 * *'       class="cb-cmt">// 8am on the 1st of each month
class="cb-str">'30 17 * * 5'     class="cb-cmt">// 5:30pm every Friday

Managing schedules

// List all schedules
const schedules = await theazo.schedules.list()

// Pause — stops future runs, preserves history
await theazo.schedules.pause(class="cb-str">'sch_abc123')

// Resume
await theazo.schedules.resume(class="cb-str">'sch_abc123')

// Delete — removes schedule entirely
await theazo.schedules.delete(class="cb-str">'sch_abc123')

// Run history for a schedule
const history = await theazo.schedules.history(class="cb-str">'sch_abc123', {
  limit: class="cb-num">20,
})
// Returns array of { runId, startedAt, completedAt, status, cost }

// Schedule object shape:
// {
//   id:        'sch_abc123',
//   name:      'daily-digest',
//   agent:     'digest-writer',
//   userId:    'user_123',
//   cron:      '0 9 * * 1-5',
//   timezone:  'America/New_York',
//   status:    'active',        // 'active' | 'paused' | 'deleted'
//   lastRun:   '2024-01-15T14:00:00Z',
//   nextRun:   '2024-01-16T14:00:00Z',
//   runCount:  42,
// }

Webhook triggers

Create a trigger to get a unique URL that launches an agent run when called. Use this to trigger agents from external systems — Zapier, GitHub Actions, your own backend, etc.

trigger.ts

const trigger = await theazo.triggers.create({
  name: class="cb-str">'new-signup-onboarding',
  agent: class="cb-str">'onboarding-agent',
  userId: class="cb-str">'user_123',        class="cb-cmt">// the session userId for each run
})

console.log(trigger.id)     class="cb-cmt">// 'trg_xyz789'
console.log(trigger.url)    class="cb-cmt">// 'https://api.theazo.com/v1/triggers/trg_xyz789'
console.log(trigger.secret) class="cb-cmt">// 'whsec_...' — shown ONCE, store it now

Calling a trigger

POST to the trigger URL with a JSON body. The body is passed as inputto the agent. Include an X-Theazo-Signature header for request verification.

// Your external system calls the trigger
const body = JSON.stringify({
  userId:   class="cb-str">'new_user_456',
  email:    class="cb-str">'alice@acme.com',
  plan:     class="cb-str">'pro',
  signedUp: new Date().toISOString(),
})

const signature = createHmac(class="cb-str">'sha256', triggerSecret)
  .update(body)
  .digest(class="cb-str">'hex')

await fetch(trigger.url, {
  method: class="cb-str">'POST',
  headers: {
    class="cb-str">'Content-Type':        class="cb-str">'application/json',
    class="cb-str">'X-Theazo-Signature':  signature,
  },
  body,
})

// Theazo launches the agent with input = parsed body
// Agent runs: "Onboard new user alice@acme.com on the pro plan"

Managing triggers

// List all triggers
const triggers = await theazo.triggers.list()

// Delete a trigger (URL stops accepting requests immediately)
await theazo.triggers.delete(class="cb-str">'trg_xyz789')

// Trigger object shape:
// {
//   id:        'trg_xyz789',
//   name:      'new-signup-onboarding',
//   agent:     'onboarding-agent',
//   userId:    'user_123',
//   url:       'https://api.theazo.com/v1/triggers/trg_xyz789',
//   secret:    null,           // only returned on create
//   createdAt: '2024-01-10T...',
//   lastFired: '2024-01-15T...',
//   fireCount: 127,
// }

Trigger secrets are shown only once at creation time. Store the secret securely — it cannot be retrieved again. If you lose it, delete the trigger and create a new one.

Trigger events

trigger.fired

A webhook trigger was called. Includes triggerId, the request body as input, and the agentId that was launched.

trigger.rejected

A webhook trigger call was rejected due to an invalid signature or rate limit.

Overlap prevention

For cron schedules, Theazo checks if the previous run is still active before launching the next one. If it is, the scheduled run is skipped and logged as skipped in history.

// Schedule history includes skipped runs
const history = await theazo.schedules.history(class="cb-str">'sch_abc123')

// history[0] = { status: 'skipped', reason: 'previous_run_active', startedAt: '...' }
// history[1] = { status: 'completed', cost: { amount: 120, currency: 'usd' }, ... }

// Trigger endpoints do NOT enforce overlap by default.
// Add concurrencyLimit to restrict simultaneous runs from one trigger:
const trigger = await theazo.triggers.create({
  name:             class="cb-str">'stripe-webhook',
  agent:            class="cb-str">'payment-handler',
  userId:           class="cb-str">'system',
  concurrencyLimit: class="cb-num">1,   class="cb-cmt">// at most 1 active run from this trigger at a time
})

API reference

Schedules

theazo.schedules.create(config)Promise<Schedule>Create a new cron schedule.

theazo.schedules.list()Promise<Schedule[]>List all schedules for this platform.

theazo.schedules.get(scheduleId)Promise<Schedule>Fetch a schedule by ID.

theazo.schedules.pause(scheduleId)Promise<void>Pause a schedule. Future triggers are skipped until resumed.

theazo.schedules.resume(scheduleId)Promise<void>Resume a paused schedule.

theazo.schedules.delete(scheduleId)Promise<void>Permanently delete a schedule.

theazo.schedules.history(scheduleId, { limit?, cursor? })Promise<RunHistory[]>Paginated execution history for a schedule.

Triggers

theazo.triggers.create(config)Promise<Trigger>Create a webhook trigger. Returns secret once — store it immediately.

theazo.triggers.list()Promise<Trigger[]>List all triggers. Secret is never returned on list.

theazo.triggers.get(triggerId)Promise<Trigger>Fetch a trigger by ID.

theazo.triggers.delete(triggerId)Promise<void>Delete a trigger. URL stops accepting requests immediately.