Skip to main content

Create a scheduled job

Section: DOC-CP-scheduling-creating#create-a-scheduled-job.

Deliver a weekday digest at 9 a.m. in the user’s chosen timezone. Prepare a receiver that turns the scheduled firing into the digest, create the calendar schedule, and show the returned next delivery time in the app.

Before enabling the schedule, implement callback verification and retry handling. Use the scheduled agent recipe when an agent writes the digest.

Recipe: deliver a weekday digest​

Section: DOC-CP-scheduling-creating#creating-jobs.

You need an authenticated user, a backend secret key and an HTTPS receiver that implements signature verification and durable acceptance.

  1. Choose the digest’s calendar time and IANA timezone with the user.
  2. Register your receiver and the payload that identifies the intended work using the cron example below.
  3. Save the returned schedule ID and show its nextTriggerAt to the user.
  4. After the first firing, check execution history and the digest result produced by your receiver.

For a single reminder use the one-shot variant; for cache maintenance use the interval variant. All three use the same receiver and recovery contract.

Schedule the weekday digest​

Section: DOC-CP-scheduling-creating#cron-job.

Use the user’s chosen timezone and weekday time in this request. See timing fields and defaults for other schedule forms.

curl -X POST https://api.travila.ai/api/v1/scheduler/create-job \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Daily digest",
  "scheduleType": "SCHEDULE_TYPE_CRON",
  "cronExpression": "0 9 * * 1-5",
  "timezone": "America/New_York",
  "target": {
    "url": "https://your-api.example.com/jobs/daily-digest",
    "kind": "digest",
    "payload": {
      "report": "daily"
    }
  }
}'

Reference: Create a scheduled job · Request fields.

Use the cron expression reference when the customer needs a different calendar pattern.

Confirm and save the next scheduled time​

Section: DOC-CP-scheduling-creating#response.

Persist the returned scheduleId with your application’s reminder or digest record. Display the next trigger time in the intended timezone. If it is wrong, correct the timing through Manage jobs before relying on the schedule.

Save the returned schedule with the reminder:

{
  "scheduleId": "sched_a1b2c3d4e5f60718",
  "name": "Daily digest",
  "state": "SCHEDULE_STATUS_ACTIVE",
  "scheduleType": "SCHEDULE_TYPE_CRON",
  "cronExpression": "0 9 * * 1-5",
  "timezone": "America/New_York",
  "nextTriggerAt": "2026-06-04T13:00:00Z",
  "createdAt": "2026-06-03T14:00:00Z"
}

Reference: Create a scheduled job · Response fields.

Use the counter representation when displaying the reminder’s history.

Choose how long failed delivery may retry​

Section: DOC-CP-scheduling-creating#retry-policy-defaults.

Choose a delivery window appropriate for the reminder, using the retry policy. Let the same accepted firing recover within that window before considering a replacement.

Recover when repeated failures pause the job​

Section: DOC-CP-scheduling-creating#auto-pause-threshold.

Repair the receiver before resuming a paused reminder. The auto-pause contract defines the threshold and supported overrides.

Variant: remind the user once at a chosen time​

Section: DOC-CP-scheduling-creating#one-shot-job.

Creates one scheduled firing at the given timestamp. Delivery can be retried, so your receiver must deduplicate acceptance and its business effects. Use a future RFC 3339 timestamp.

curl -X POST https://api.travila.ai/api/v1/scheduler/create-job \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Send welcome email",
  "scheduleType": "SCHEDULE_TYPE_ONCE",
  "scheduledAt": "2026-10-10T14:00:00Z",
  "target": {
    "url": "https://your-api.example.com/jobs/welcome",
    "kind": "notification",
    "payload": {
      "user_id": "usr_abc123"
    }
  }
}'

Reference: Create a scheduled job · Request fields.

Variant: refresh application data every few minutes​

Section: DOC-CP-scheduling-creating#recurring-interval-job.

Use a recurring interval to refresh a cache or perform routine maintenance every N seconds without tying it to a clock time. The minimum interval is 60 seconds.

curl -X POST https://api.travila.ai/api/v1/scheduler/create-job \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Sync cache",
  "scheduleType": "SCHEDULE_TYPE_RECURRING_INTERVAL",
  "intervalSeconds": 300,
  "target": {
    "url": "https://your-api.example.com/jobs/cache-sync",
    "kind": "maintenance"
  }
}'

Reference: Create a scheduled job · Request fields.

Document ID: DOC-CP-scheduling-creating. Section identities and revisions.