Manage jobs
Section ID: Guide/jc6dsbqlqu#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 ID: Guide/jc6dsbqlqu#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.
-
Authenticate the owning user and load that job.
-
Show its current timing and next trigger before accepting a change.
-
Apply only the changed timing fields, then display the returned next trigger.
-
Use pause for a temporary break and delete when the user removes the reminder.
-
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 ID: Guide/jc6dsbqlqu#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.
Request example: Get a scheduled job. Example identifiers and values are illustrative; substitute authorized values.
Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.
Variant: show the user’s reminder list
Section ID: Guide/jc6dsbqlqu#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.
Request example: List scheduled jobs. Example identifiers and values are illustrative; substitute authorized values.
Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.
2. Save a new delivery time
Section ID: Guide/jc6dsbqlqu#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:
Request example: Update a scheduled job. Example identifiers and values are illustrative; substitute authorized values.
Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.
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 ID: Guide/jc6dsbqlqu#pause-and-resume
Use pause to temporarily stop a job without deleting it. Resume returns it to SCHEDULE_STATUS_ACTIVE.
Request example: Pause a scheduled job. Example identifiers and values are illustrative; substitute authorized values.
Request example: Resume a scheduled job. Example identifiers and values are illustrative; substitute authorized values.
Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json; X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.
4. Remove this reminder
Section ID: Guide/jc6dsbqlqu#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.
Request example: Delete a scheduled job. Example identifiers and values are illustrative; substitute authorized values.
Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.
Account cleanup: remove all of the user’s schedules
Section ID: Guide/jc6dsbqlqu#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.
Response example: Delete all scheduled jobs for the calling owner. Example identifiers and values are illustrative; substitute authorized values.
Project teardown: remove schedules across all owners
Section ID: Guide/jc6dsbqlqu#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.
Response example: Delete all scheduled jobs for a project. Example identifiers and values are illustrative; substitute authorized values.
Warning: 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 ID: Guide/jc6dsbqlqu#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:
Request example: Create a scheduled job. Example identifiers and values are illustrative; substitute authorized values.
Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.
Use the same saved identifier when retrieving or changing the reminder; see supported lookups:
Request example: Get a scheduled job. Example identifiers and values are illustrative; substitute authorized values.
Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.
Choose the application identifier before creation and retain it for the reminder’s lifetime; reserved values and immutability apply.
Document ID: Guide/jc6dsbqlqu