Skip to main content

Managing Jobs

Managing Jobs​

Get a Job​

curl -X POST https://api.travila.ai/api/v1/scheduler/get-job \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{ "scheduleId": "sched_a1b2c3d4e5f60718" }'

List Jobs​

Returns all jobs for the authenticated tenant and project. Optionally filter by state or target kind.

curl -X POST https://api.travila.ai/api/v1/scheduler/list-jobs \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "pageSize": 20,
    "stateFilter": "SCHEDULE_STATE_ACTIVE"
  }'

Update a Job​

Partial update — only the fields you include are changed. Omitted fields are left unchanged.

curl -X POST https://api.travila.ai/api/v1/scheduler/update-job \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduleId": "sched_a1b2c3d4e5f60718",
    "cronExpression": "0 10 * * 1-5"
  }'
Cron expression changes

Cron expression updates may not take effect until the next worker deployment. Check effectiveAt in the response — it will say either immediate or next_worker_deployment.

Pause and Resume​

Use pause to temporarily stop a job without deleting it. Resume returns it to SCHEDULE_STATE_ACTIVE.

# Pause
curl -X POST https://api.travila.ai/api/v1/scheduler/pause-job \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduleId": "sched_a1b2c3d4e5f60718",
    "reason": "Target service under maintenance"
  }'

# Resume
curl -X POST https://api.travila.ai/api/v1/scheduler/resume-job \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "scheduleId": "sched_a1b2c3d4e5f60718" }'

Delete a Job​

Soft-delete — the job stops firing immediately. Deleted jobs are retained for audit and can still be retrieved by ID.

curl -X POST https://api.travila.ai/api/v1/scheduler/delete-job \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{ "scheduleId": "sched_a1b2c3d4e5f60718" }'

Delete Every Job for the Caller​

Soft-deletes every job owned by the calling subject, within the tenant and project from the request headers. The body carries no fields — there is no way to sweep another user's jobs.

Call this at sign-out, so per-user schedules don't outlive the session on a shared or handed-down device.

curl -X POST https://api.travila.ai/api/v1/scheduler/delete-jobs-for-owner \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "deletedCount": 3
}

Delete Every Job in the Project​

The project-teardown equivalent: soft-deletes every job belonging to the tenant and project in the request context, across all owners. The body carries no fields.

curl -X POST https://api.travila.ai/api/v1/scheduler/delete-jobs-for-project \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "deletedCount": 47
}
No confirmation, no filter

This is a tenant lifecycle hook, not an admin convenience. It takes no arguments, so there is nothing to narrow it with and nothing to undo it with — the scope is decided entirely by the tenant and project headers you send. Check those before you call it.

deletedCount is omitted when zero.

Referencing Jobs by External ID​

Every job has a server-assigned scheduleId (prefixed sched_). You can also attach your own externalId at creation — a stable identifier from your own system, unique within your tenant and project, and immutable once set.

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",
    "externalId": "user-42-daily-digest",
    "target": { "url": "https://your-api.example.com/jobs/daily-digest", "kind": "digest" }
  }'

Once set, get-job, update-job, pause-job, resume-job, and delete-job accept externalId in place of scheduleId — provide exactly one of the two. This lets you address a job by your own key without first storing the generated scheduleId.

curl -X POST https://api.travila.ai/api/v1/scheduler/get-job \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "user-42-daily-digest" }'
note

externalId must not start with the reserved sched_ prefix, and cannot be changed after the job is created.