Scheduled tasks API

Classes

ScheduledTasksApi: Scheduled tasks: interval, fixed-time, one-time and webhook triggers that start agent runs. A one-time trigger needs the oneTimeSchedules capability. Reading needs orchestration:read; the server removes webhook endpoints from a reader's results. Mutations, webhook endpoints and delivery records need orchestration:operate. Signing secrets are write-only.

Constants

ScheduledTaskWebhookEndpoint: A webhook task's endpoint. path carries the URL token and is relative to the environment; url is the T3 Connect relay URL, null without one. The server removes the whole endpoint for a caller without orchestration:operate.
ScheduledTaskWebhookDeliveryOutcome: What happened to one webhook request. The set grows; newer outcomes stay strings.
ScheduledTaskWebhookDelivery: One recorded request with its query, headers, (possibly truncated) body and rendered prompt.
ScheduledTaskWebhookDedupe: Replay key (kept 7 days), coalesce key and coalesce window in seconds (server default 120).
ScheduledTaskWebhookFilter: A filter as sent. Every filter must match for a request to run the task.
ScheduledTaskWebhookFilterRecord: A stored filter; a newer operator decodes as { unknown: true, raw }.
ScheduledTaskWebhookSignature: Stored HMAC-SHA256 check over the raw request body. The secret is never returned.
ScheduledTaskWebhookSignatureInput: Signature check as sent. Omit secret and secretRef to keep the stored secret; secretRef is consumed by the save that uses it.
ScheduledTaskSchedule: A stored trigger. Sub-minute legacy intervals still decode so they can be listed, disabled, edited or deleted. A newer trigger type decodes as { unknown: true, raw }.
ScheduledTaskUpsertSchedule: A writable trigger; intervals are at least one minute.

ScheduledTasksApi

Scheduled tasks: interval, fixed-time, one-time and webhook triggers that start agent runs. A one-time trigger needs the oneTimeSchedules capability. Reading needs orchestration:read; the server removes webhook endpoints from a reader’s results. Mutations, webhook endpoints and delivery records need orchestration:operate. Signing secrets are write-only.

Kind: global class

ScheduledTasksApi

scheduledTasksApi.list()

Every task this client can decode; a task with an unfamiliar shape is left out.

async list(signal?: AbortSignal): Promise<ScheduledTask[]>;

Kind: instance method of ScheduledTasksApi

scheduledTasksApi.get()

One task, or undefined when no task has id.

async get(id: ScheduledTaskId, signal?: AbortSignal): Promise<ScheduledTask | undefined>;

Kind: instance method of ScheduledTasksApi

scheduledTasksApi.upsert()

Create a task, or replace one by id, with the server’s upsert semantics.

async upsert(input: ScheduledTaskUpsertInput, signal?: AbortSignal): Promise<ScheduledTask>;

Kind: instance method of ScheduledTasksApi

scheduledTasksApi.update()

Change the given properties of an existing task and keep the rest. This reads the task and then saves it with requireExisting: true; a task deleted in between fails, and a concurrent edit is overwritten.

async update(
    id: ScheduledTaskId,
    patch: ScheduledTaskPatch,
    signal?: AbortSignal,
  ): Promise<ScheduledTask>;

Kind: instance method of ScheduledTasksApi

scheduledTasksApi.validateTarget()

Check that an existing target thread belongs to the selected project. A null or omitted thread starts a new thread per run and needs no read. Bound threads use orchestration:read; missing threads, permission errors and cancellation propagate. Native upsert remains a thin operate-only call.

async validateTarget(input: ScheduledTaskTarget, signal?: AbortSignal): Promise<void>;

Kind: instance method of ScheduledTasksApi

scheduledTasksApi.setEnabled()

Enable or disable a task without changing its execution settings.

async setEnabled(
    id: ScheduledTaskId,
    enabled: boolean,
    signal?: AbortSignal,
  ): Promise<ScheduledTask>;

Kind: instance method of ScheduledTasksApi

scheduledTasksApi.delete()

Delete a scheduled task through the server’s native mutation.

async delete(id: ScheduledTaskId, signal?: AbortSignal): Promise<void>;

Kind: instance method of ScheduledTasksApi

scheduledTasksApi.runNow()

Start a run now. The server refuses webhook tasks and a task that is already running.

async runNow(id: ScheduledTaskId, signal?: AbortSignal): Promise<ScheduledTask>;

Kind: instance method of ScheduledTasksApi

scheduledTasksApi.rotateWebhookToken()

Replace a webhook task’s URL token; the previous URL stops working.

async rotateWebhookToken(id: ScheduledTaskId, signal?: AbortSignal): Promise<ScheduledTask>;

Kind: instance method of ScheduledTasksApi

scheduledTasksApi.listWebhookDeliveries()

Recorded webhook requests; outcomes newer than this client stay strings.

async listWebhookDeliveries(
    id: ScheduledTaskId,
    signal?: AbortSignal,
  ): Promise<ScheduledTaskWebhookDeliverySummary[]>;

Kind: instance method of ScheduledTasksApi

scheduledTasksApi.getWebhookDelivery()

Read one webhook request’s diagnostic record, including its body and headers.

async getWebhookDelivery(
    id: ScheduledTaskId,
    deliveryId: ScheduledTaskWebhookDeliveryId,
    signal?: AbortSignal,
  ): Promise<ScheduledTaskWebhookDelivery>;

Kind: instance method of ScheduledTasksApi

scheduledTasksApi.watch()

The full task list now and after every change; decode failures remain stream items.

watch(
    options: WatchScheduledTasksOptions = {},
  ): AsyncIterable<DecodedStreamItem<ScheduledTaskListResult>>;

Kind: instance method of ScheduledTasksApi

scheduledTasksApi.webhookEndpoint()

A webhook task’s endpoint. A missing task fails as not found and another trigger type as a precondition. A caller without orchestration:operate fails with insufficient scope; the endpoint is never reconstructed.

async webhookEndpoint(
    id: ScheduledTaskId,
    signal?: AbortSignal,
  ): Promise<ScheduledTaskWebhookEndpointInfo>;

Kind: instance method of ScheduledTasksApi

ScheduledTaskWebhookEndpoint

A webhook task’s endpoint. path carries the URL token and is relative to the environment; url is the T3 Connect relay URL, null without one. The server removes the whole endpoint for a caller without orchestration:operate.

Kind: global constant

ScheduledTaskWebhookDeliveryOutcome

What happened to one webhook request. The set grows; newer outcomes stay strings.

Kind: global constant

ScheduledTaskWebhookDelivery

One recorded request with its query, headers, (possibly truncated) body and rendered prompt.

Kind: global constant

ScheduledTaskWebhookDedupe

Replay key (kept 7 days), coalesce key and coalesce window in seconds (server default 120).

Kind: global constant

ScheduledTaskWebhookFilter

A filter as sent. Every filter must match for a request to run the task.

Kind: global constant

ScheduledTaskWebhookFilterRecord

A stored filter; a newer operator decodes as { unknown: true, raw }.

Kind: global constant

ScheduledTaskWebhookSignature

Stored HMAC-SHA256 check over the raw request body. The secret is never returned.

Kind: global constant

ScheduledTaskWebhookSignatureInput

Signature check as sent. Omit secret and secretRef to keep the stored secret; secretRef is consumed by the save that uses it.

Kind: global constant

ScheduledTaskSchedule

A stored trigger. Sub-minute legacy intervals still decode so they can be listed, disabled, edited or deleted. A newer trigger type decodes as { unknown: true, raw }.

Kind: global constant

ScheduledTaskUpsertSchedule

A writable trigger; intervals are at least one minute.

Kind: global constant