Skip to main content

Manage jobs

Section: DOC-CP-scheduling-managing#manage-jobs.

Let a user move their daily digest to a different time, take a temporary break or stop it permanently. Load their saved schedule, apply the requested change and show its returned state so they can see what will happen next.

Have the owning account and user, plus the scheduleId saved when you created the reminder or its application-owned externalId. Changes affect future dispatch; check execution history for work already sent.

Recipe: change or stop a daily digest​

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

Build the “change my weekday digest” flow for a job you previously created. Keep the schedule ID with the application’s reminder record, or use an immutable external ID as described below.

  1. Authenticate the owning user and load that job.
  2. Show its current timing and next trigger before accepting a change.
  3. Apply only the changed timing fields, then display the returned next trigger.
  4. Use pause for a temporary break and delete when the user removes the reminder.
  5. If a change loses its response, read the same job and its execution history before repeating it. Work already delivered to the receiver needs its own outcome check.

The person’s reminder stays tied to the same job. Account-wide cleanup and project teardown below are separate administrative variants, not sign-out behavior.

1. Load the reminder being changed​

Section: DOC-CP-scheduling-managing#get-a-job.

Load the saved ID under the same user that created the job. Use its current timing and state to populate the edit form; a different user’s supplied ID is not permission to change their reminder.

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"
}'

Reference: Get a scheduled job · Request fields.

Variant: show the user’s reminder list​

Section: DOC-CP-scheduling-managing#list-jobs.

Returns a page of jobs for the account and user identified by your authentication headers. Follow pagination to enumerate results, and 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_STATUS_ACTIVE"
}'

Reference: List scheduled jobs · Request fields.

2. Save a new delivery time​

Section: DOC-CP-scheduling-managing#update-a-job.

Submit the user’s selected time once. Use the returned next trigger as confirmation; if the response is lost, read the existing job to determine whether the new time was saved before trying again.

Send only the edited settings, following the update contract:

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"
}'

Reference: Update a scheduled job · Request fields.

Display the returned next-trigger time and check previously accepted work separately. See timing-update effects.

3. Let the user take a temporary break​

Section: DOC-CP-scheduling-managing#pause-and-resume.

Use pause to temporarily stop a job without deleting it. Resume returns it to SCHEDULE_STATUS_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 "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
  "scheduleId": "sched_a1b2c3d4e5f60718"
}'

Reference: Pause a scheduled job · Request fields.

Reference: Resume a scheduled job · Request fields.

4. Remove this reminder​

Section: DOC-CP-scheduling-managing#delete-a-job.

Soft-delete removes the job from future scheduling. It does not retract a callback already in flight. Deleted jobs remain available for audit according to retention policy.

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"
}'

Reference: Delete a scheduled job · Request fields.

Account cleanup: remove all of the user’s schedules​

Section: DOC-CP-scheduling-managing#delete-every-job-for-the-caller.

Soft-deletes every job owned by the calling subject, within the tenant and project from the verified request context. The body carries no owner selector. A backend using X-On-Behalf-Of must establish that beneficiary through its own authenticated application flow.

Use this only for an explicit request to remove all of the user's persistent schedules or for authorized account cleanup. Ordinary sign-out should clear the local session and device notification binding; it should not delete reminders on other devices. Keep the cleanup result, list remaining jobs and investigate failures before reporting that all schedules were removed.

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 '{}'

Reference: Delete all scheduled jobs for the calling owner · Request fields.

Response:

{
  "deletedCount": 3
}

Reference: Delete all scheduled jobs for the calling owner · Response fields.

Project teardown: remove schedules across all owners​

Section: DOC-CP-scheduling-managing#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. This operation requires a backend request without a selected user: adding X-On-Behalf-Of causes rejection. It currently applies to the legacy default project; it does not establish deletion support for arbitrary projects.

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

Reference: Delete all scheduled jobs for a project · Request fields.

Response:

{
  "deletedCount": 47
}

Reference: Delete all scheduled jobs for a project · Response fields.

No confirmation, no filter

Use this operation only for authorized project teardown. It deletes all jobs in its supported project scope, has no filter and cannot undo the deletion. Confirm the account and project in your backend, and require permission for teardown before sending the request. Client-supplied tenant/project headers do not grant that permission.

deletedCount is omitted when zero.

Variant: use your application’s reminder identifier​

Section: DOC-CP-scheduling-managing#referencing-jobs-by-external-id.

Use an immutable application reminder identifier when you want to keep job lookup tied to your own record. See identifier rules:

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"
  }
}'

Reference: Create a scheduled job · Request fields.

Use the same saved identifier when retrieving or changing the reminder; see supported lookups:

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"
}'

Reference: Get a scheduled job · Request fields.

Choose the application identifier before creation and retain it for the reminder’s lifetime; reserved values and immutability apply.

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