API referenceEndpoints

Create schedule

Requires an authenticated tenant principal. Generated from the production route registered in `internal/features/schedules/inbound/http.go`.

POST/v1/schedules

Requires an authenticated tenant principal. Generated from the production route registered in internal/features/schedules/inbound/http.go.

Authorization

bearerAuth
AuthorizationBearer <token>

Engine-issued API key or tenant-signed JWT.

In: header

Header Parameters

Idempotency-Key?string

Optional, at most 200 bytes. Omitted, every call creates a new schedule. Sent, a replay compares a hash of the PARSED request body re-encoded — an unrelated formatting difference (key order, whitespace) does not change the hash, but a changed field does. Same key, unchanged body: the original schedule, unchanged. Same key, changed body: 409 {"error":{"type":"conflict","message":"Idempotency-Key reused with a different request"}} — no code.

Lengthlength <= 200

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

The action is derived from the shape: agent_id + message creates an agent_run task that fires as a durable agent run carrying the guardrail-screened message (endpoint_id/payload are rejected); agent_id without message is the pre-46a compatibility shape, stored as agent_run with the exact message scheduled trigger and its legacy delivery fields retained but never executed; message + model (+ optional tools) with NO agent_id creates an agent_run task for which the engine makes a hidden personal agent — persona framed around the message, the named tools at their default policy — and binds it (the response carries its agent_id; the agent is deleted with the schedule; model is required because the engine has no organization default; model/tools are rejected on every other shape); no agent_id and no message creates the original webhook action, which requires endpoint_id. Responses expose action_type, the stored message (agent_run only), the engine-computed owned_by_caller, and reads_from — dataset or project, which of the task's two data facts the runs it fires READ when a dataset.query call names none of its own (2026-09-22). reads_from is derived from the same resolution the fired run obeys, not restated from the body: dataset whenever the task carries a dataset_id, project when it carries only a project_id. It is ABSENT when the task carries neither — there is then no place to read, and saying project would assert one that does not exist — and absent on every webhook schedule, which fires no run. It appears identically on this create, on GET /v1/schedules/{id}, on PATCH /v1/schedules/{id} and on each row of GET /v1/schedules.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/schedules" \  -H "Content-Type: application/json" \  -d '{}'
{}