Update a cron schedule
const url = 'https://example.com/v1/schedules/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0';const options = { method: 'PATCH', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"flowId":"example","flowVersion":"example","agentId":"example","agentVersion":"example","improve":{"agentId":"example","projectId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"},"config":{"cronExpression":"example","timezone":"example","input":"example"},"catchUp":"latest","overlap":"skip","startingDeadlineSeconds":1,"label":"example","toolsAllowedUnattended":["example"]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url https://example.com/v1/schedules/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "flowId": "example", "flowVersion": "example", "agentId": "example", "agentVersion": "example", "improve": { "agentId": "example", "projectId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }, "config": { "cronExpression": "example", "timezone": "example", "input": "example" }, "catchUp": "latest", "overlap": "skip", "startingDeadlineSeconds": 1, "label": "example", "toolsAllowedUnattended": [ "example" ] }'Partial merge on config. If config.cronExpression changes, nextFireAt is recomputed. label: null clears the label; omit to leave unchanged. Malformed cron expressions return 400 trigger-invalid-config. toolsAllowedUnattended replaces the list ([] clears it; absent keeps it): naming it takes admin on the schedule’s project, and every change is audited. A new target (another flow or agent) while the list isn’t empty must name it again, as it is or [], else 400; a new version alone keeps it. A schedule is personal or shared, and no change moves its owner: only POST /v1/schedules/{triggerId}/owner does. So with an authorization store, a new target (another flow or agent, or an Improve run) must be one the owner can run, a person or a service account, else 409 trigger-owner-cannot-run-target; that’s not checked when the caller is the owner, nor for an owner that was unregistered or removed. A schedule a person owns is personal: only they (holding write on its project) or a project admin may change it. A schedule a service account owns is shared: changing its target or version, its input or toolsAllowedUnattended takes admin on its project, and the project’s writers may change its label, cron line and policies. Without an authorization store, a project admin here is a tenant-admin key. A change by anyone but a personal schedule’s owner is audited as trigger-changed-for-owner, naming the fields changed and the schedule’s version after it, never their values.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”TriggerId — the trigger id (a UUID).
Header Parameters
Section titled “Header Parameters”Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1). A retry sent while the first request still runs is answered 409 idempotency-key-in-flight with Retry-After, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets 409 idempotency-key-replay-withheld, with the first request’s status and when it succeeded (from 0.1.5). A request whose key store can’t be read before it runs is answered 503 idempotency-store-unavailable with Retry-After: nothing ran, so retry with the same key (from 0.3.0).
Request Bodyrequired
Section titled “Request Bodyrequired”Change what it runs (the target fields, as at registration, which also needs what registering it needs on the new target; a new improve target stays in the schedule’s project), when, or its policies.
object
Run a flow (with flowVersion).
Run an agent (instead of a flow): at agentVersion, else its pinned version.
Start an Improve run instead of a run (instead of flowId or agentId). Its config.input is the Improve run options; registering needs write on the project and publish on the agent.
object
The schedule’s own project.
object
What each run gets. An agent schedule’s runs take the agent payload, { userMessage, parameters? }, so it needs userMessage; a flow’s take the flow’s input. An improve schedule’s is ImproveScheduleInput, kept with its defaults applied.
Default latest.
Default skip.
Default 600.
null clears the label; omit to leave unchanged.
Replaces the schedule’s list; [] clears it, and absent keeps it. Naming it takes admin on the schedule’s project. A change of what it runs (another flow or agent) while the list isn’t empty must name it again, as it is or []; a new version alone keeps it. Each tool by its id, with no wildcard or pattern, and only tools this trigger’s flow or agent calls. It lifts only that wait: the tenant’s approval rules, the agent’s own rules, the permission check (as the trigger’s owner) and the tool’s own limits all still apply.
Responses
Section titled “Responses”Updated schedule.
A schedule: what it runs (a flow at a version, or an agent), when (a cron expression in a timezone), as whom (its owner), and what it does after a gap or while a run is still going.
object
Domain-friendly alias for triggerId — the trigger id (a UUID). Use interchangeably in admin URLs.
A schedule that runs a flow: the flow, at flowVersion.
A schedule that runs an agent: the agent, at agentVersion, else its version pinned for the schedule’s project (else the latest), as a run that names none.
A schedule that starts Improve runs: on this agent, in this project (the schedule’s), when the project has enough new corrections sorted to improve since its last Improve run (input: how many, whose, and what a run and the month may cost). An agent and project have one at most.
object
The schedule’s own project. Absent from older servers, and on a schedule registered for a tenant or an org before Improve schedules worked in a project: its fires are refused until its target is saved with the schedule’s project.
The schedule’s project: its runs are this project’s.
Who its runs act as. A person: a personal trigger, which only they or a project admin change. A service account: a shared trigger. Only a take-over (POST …/owner) changes it. Checked again at every fire.
object
The owner’s name at the time of the response: the person’s display name, or the service account’s name. Absent when it can’t be read (no directory, a removed account) and from a runtime before Kindgi 0.1.6: show the id then.
Set when the owner is the trigger’s project’s own service account (runAsProject): the trigger is shared, and runs as the project. Show it as “This project”. Absent otherwise.
5- or 6-field cron expression (croner-compatible). 6-field enables second precision.
IANA timezone (e.g. UTC, America/New_York). Absent → UTC.
Static input handed to the run on every fire. Absent → {}.
After a gap (the runtime was down, or a fire is later than startingDeadlineSeconds): latest runs once, for the latest missed occurrence, and its fire says how many it missed; skip drops the missed occurrences. Never a run per missed occurrence. A tenant’s suspension isn’t caught up either way: once the tenant is restored, a schedule that’s on fires next at its first occurrence after the restore.
When an occurrence comes while the previous run of this schedule is still running: skip records the fire as skipped; allow starts another run.
How late a fire may start and still count as on time; past it, catchUp applies.
Lifecycle status. Only active triggers fire. Tombstoned rows are excluded from every read path.
Why the runtime paused it: repeated fires that were refused (the owner lost access) or failed. Skipped fires (an overlap, an erasure in progress) never count. For an Improve schedule, owner-lost-publish pauses it at once: its owner no longer has publish on the agent. Saving it with a new owner resumes it.
For an Improve schedule whose month’s Improve runs have reached its monthly cap (input.monthCapUsd): when it starts again by itself, the 1st of next month (UTC). It stays active, and its fires until then are skipped. Absent otherwise.
Why it waits until pausedUntil: its month’s cap.
The trigger’s newest version (GET …/versions): one more for each change to what it runs, when, as whom or with what. Absent until its first version.
The tools whose calls in this schedule’s runs don’t wait for a person’s yes, though a tool asks for one in a run no person started (needsApprovalWhenUnattended). Absent: none. Each tool by its id, with no wildcard or pattern, and only tools this trigger’s flow or agent calls. It lifts only that wait: the tenant’s approval rules, the agent’s own rules, the permission check (as the trigger’s owner) and the tool’s own limits all still apply.
Wall-clock time of the next scheduled fire. null on paused rows if the cron scheduler never re-armed.
The next occurrences, when the request asked for them (?upcoming=N).
Example
{ "owner": { "kind": "user", "isProjectAccount": true }, "catchUp": "latest", "overlap": "skip", "status": "active", "pausedReason": "month-cap"}Malformed request body, or trigger-invalid-config. Or reference-out-of-scope: a new target isn’t registered in the schedule’s project, its org or the tenant, or the version it names isn’t one that project runs (details.issues, at /target, whose message names the version). Nothing changes.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Missing / malformed / expired / revoked bearer token.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}permission-denied: the schedule is personal and the caller is neither its owner nor a project admin (the message names the owner), or it’s shared and changing what it runs takes a project admin. A caller without write on its project (for an improve schedule, publish on the agent) is refused first, and learns nothing of its owner.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}No cron trigger with that id.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}A new target the schedule’s owner can’t run (trigger-owner-cannot-run-target), with an authorization store. schedule-exists: a new improve target whose agent has another Improve schedule in the project (details.scheduleId). Or an Idempotency-Key reused with a different body.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}The request body is over the API’s limit (request-too-large; details.maxBytes says how much).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Server error (unmapped domain code or framework crash).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}The Idempotency-Key store couldn’t be read before the request ran (idempotency-store-unavailable), so nothing was changed; Retry-After (whole seconds) says when to try again with the same key.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}See also
GET /v1/schedules/{triggerId}: Fetch a cron schedulePOST /v1/schedules/{triggerId}/pause: Pause a cron schedulePOST /v1/schedules/{triggerId}/resume: Resume a cron schedulePOST /v1/schedules/{triggerId}/unregister: Soft-delete a cron schedule (tombstone)- Error code
idempotency-store-unavailable - Error code
permission-denied - Error code
reference-out-of-scope - Error code
request-too-large - Error code
schedule-exists - Error code
trigger-invalid-config - Error code
trigger-owner-cannot-run-target - Every error code