Skip to content
Kindgi

Take over a schedule

View as Markdown
POST
/v1/schedules/{triggerId}/owner
curl --request POST \
  --url https://example.com/v1/schedules/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/owner \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "runAsServiceAccountId": "example", "runAsProject": true }'

The caller becomes the schedule’s owner, so its runs act as the caller from the next fire. Needs admin on the schedule’s project (without an authorization store, a tenant-admin key) and execute on what it runs. For a schedule whose owner left or lost access, or to make one shared or personal. It’s the one way a schedule’s owner changes, audited as trigger-owner-set; a person it’s taken from is told, where the server tells owners. Name runAsServiceAccountId instead to make a service account the owner: that needs act_as on the account (a tenant admin’s), and the account must itself hold the access the schedule’s target needs. With an authorization store, that’s checked when the account is named: an account that can’t is refused (409 trigger-owner-cannot-run-target). Or name runAsProject: true to make the project’s own service account the owner, made the first time with the editor role on the project, so the schedule is shared and runs as the project. It runs only what the project’s editors can, and is checked the same way. The schedule keeps its toolsAllowedUnattended, now for the new owner’s runs; a body naming it is refused (change it with PATCH).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
triggerId
required
string format: uuid

TriggerId — the trigger id (a UUID).

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
>= 1 characters

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).

Request Body

Section titled “Request Body”
Media typeapplication/json

Who the trigger’s runs act as from now: for a trigger whose owner left, or to make one shared or personal. Absent, or an empty body: the caller takes it over (today’s behaviour). With runAsServiceAccountId: that service account becomes the owner. With runAsProject: the project’s own account does. A take-over keeps the trigger’s toolsAllowedUnattended: change that with PATCH.

object
runAsServiceAccountId

A service account the trigger’s runs act as (its owner), named by id, instead of the caller. Needs act_as on that account — a tenant admin holds it — and the account must itself hold what the trigger runs. With an authorization store, that’s checked when the account is named: an account that can’t is refused (409 trigger-owner-cannot-run-target). Not a project’s own account (409 service-account-project-owned: name it with runAsProject).

string
>= 1 characters
runAsProject

true: the trigger’s runs act as its project’s own service account, made the first time with the editor role on the project, so it’s shared. It runs only what the project’s editors can. With an authorization store, that’s checked when it’s named: if it can’t run what the trigger runs, the request is refused (409 trigger-owner-cannot-run-target). Takes admin on the trigger’s project (without an authorization store, a tenant-admin key), not act_as. Not with runAsServiceAccountId, and not without a project (400). A runtime that can’t make the account answers 501 trigger-operation-unsupported. false or absent: as runAsServiceAccountId says.

boolean
Examplegenerated
{
  "runAsServiceAccountId": "example",
  "runAsProject": true
}

Responses

Section titled “Responses”

200

Section titled “200”

The schedule, with its new owner.

Media typeapplication/json

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
scheduleId
required

Domain-friendly alias for triggerId — the trigger id (a UUID). Use interchangeably in admin URLs.

string
triggerId
required
string
flowId

A schedule that runs a flow: the flow, at flowVersion.

string
>= 1 characters
flowVersion
string
>= 1 characters
agentId

A schedule that runs an agent: the agent, at agentVersion, else its version live for the schedule’s project (else the latest), as a run that names none.

string
>= 1 characters
agentVersion
string
>= 1 characters
improve

A schedule that starts Improve runs: on this agent, for this scope, when enough answers have been marked wrong since its last Improve run (input: the threshold, the monthly cap and the Improve options).

object
agentId
required
string
>= 1 characters
scope
required
One of: discriminator: kind

The agent’s default for the whole tenant.

object
kind
required
string
Allowed values: tenant
projectId

The schedule’s project: its runs are this project’s.

string format: uuid
owner

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
kind
required
string
Allowed values: user service
id
required
string
displayName

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.

string
isProjectAccount

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.

boolean
cronExpression
required

5- or 6-field cron expression (croner-compatible). 6-field enables second precision.

string
>= 1 characters
timezone

IANA timezone (e.g. UTC, America/New_York). Absent → UTC.

string
input

Static input handed to the run on every fire. Absent → {}.

catchUp

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.

string
Allowed values: latest skip
overlap

When an occurrence comes while the previous run of this schedule is still running: skip records the fire as skipped; allow starts another run.

string
Allowed values: skip allow
startingDeadlineSeconds

How late a fire may start and still count as on time; past it, catchUp applies.

integer
>= 1
label
required
string | null
status
required

Lifecycle status. Only active triggers fire. Tombstoned rows are excluded from every read path.

string
Allowed values: active paused
statusReason

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.

string
toolsAllowedUnattended

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.

Array<string>
<= 100 items unique items
nextFireAt
required

Wall-clock time of the next scheduled fire. null on paused rows if the cron scheduler never re-armed.

string | null format: date-time
upcoming

The next occurrences, when the request asked for them (?upcoming=N).

Array<string>
lastFiredAt
required
string | null format: date-time
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
Example
{
  "improve": {
    "scope": {
      "kind": "tenant"
    }
  },
  "owner": {
    "kind": "user",
    "isProjectAccount": true
  },
  "catchUp": "latest",
  "overlap": "skip",
  "status": "active"
}

400

Section titled “400”

A malformed body, or runAsProject with runAsServiceAccountId, or a body naming toolsAllowedUnattended (bad-input).

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Section titled “401”

Missing / malformed / expired / revoked bearer token.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

403

Section titled “403”

permission-denied: not an admin of the schedule’s project, or no execute on what it runs, or no act_as on the account named.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

Section titled “404”

No cron trigger with that id, or no such service account.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

Section titled “409”

runAsServiceAccountId names an unregistered account (service-account-unregistered), a project’s own account (service-account-project-owned: name it with runAsProject), or one that can’t run what the schedule runs (trigger-owner-cannot-run-target). Or, with runAsProject, the project’s own account can’t run what the schedule runs either (trigger-owner-cannot-run-target; the account stays, for the next runAsProject), or an active account someone made already has the project account’s name, project-<projectId> (service-account-name-taken: a tenant admin can unregister it). Or an idempotency conflict.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

413

Section titled “413”

The request body is over the API’s limit (request-too-large; details.maxBytes says how much).

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

500

Section titled “500”

Server error (unmapped domain code or framework crash).

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

501

Section titled “501”

trigger-operation-unsupported: this deployment can’t change a schedule’s owner, or can’t make a project’s own account (runAsProject).

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also