post_api_schedules

POST

/api/schedules

const url = 'https://example.com/api/schedules';
const options = {
  method: 'POST',
  headers: {
    cookie: 'supacloud_session=<supacloud_session>',
    'Content-Type': 'application/json'
  },
  body: '{"agent_profile_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","agent_type":"example","app_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","app_inputs":"example","cadence":"example","config":"example","next_run_at":"2026-04-15T12:00:00Z","project_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","prompt":"example","timezone":"example","title":"example","workflow_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/api/schedules \
  --header 'Content-Type: application/json' \
  --cookie supacloud_session=<supacloud_session> \
  --data '{ "agent_profile_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "agent_type": "example", "app_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "app_inputs": "example", "cadence": "example", "config": "example", "next_run_at": "2026-04-15T12:00:00Z", "project_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "prompt": "example", "timezone": "example", "title": "example", "workflow_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'

Authorizations

cookie_auth

Request Body^required

application/json

object

agent_profile_id

#708 F11 / who-5 — the agent PROFILE the fired task runs under (its agent_profile_id WHO column). Optional; None = no pin (the no-profile WHO default). A task schedule only.

string | null format: uuid

agent_type

string

app_id

ADR 0030 W4 — when set, the schedule fires a kind='app' run of this App instead of a task or a workflow. Exactly one of workflow_id / app_id / a task definition (agent_type + prompt) must be set. prompt and agent_type are unused for an App schedule.

string | null format: uuid

app_inputs

ADR 0030 W4 — the per-fire App input payload, prefilled into the fired run’s trigger context. Ignored for a task / workflow schedule.

cadence

required

string

config

next_run_at

required

string format: date-time

project_id

Optional: a task schedule runs in a project, but an App schedule is workspace-scoped and may omit it (the service stores Option<Uuid>).

string | null format: uuid

prompt

string

timezone

string | null

title

required

string

workflow_id

When set, the schedule fires a kind='workflow' run of this workflow instead of creating a task (ADR 0020 V4 schedule trigger). prompt and agent_type are unused for a workflow schedule.

string | null format: uuid

Example^generated

{
  "agent_profile_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "agent_type": "example",
  "app_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "app_inputs": "example",
  "cadence": "example",
  "config": "example",
  "next_run_at": "2026-04-15T12:00:00Z",
  "project_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "prompt": "example",
  "timezone": "example",
  "title": "example",
  "workflow_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
}

Responses

200

application/json

object

agent_profile_id

required

#708 F11 / who-5 — the agent PROFILE the fired task runs under (agent_profile_id WHO column). None = no pin. Surfaced so the schedule editor shows the current pin.

string | null format: uuid

agent_type

required

string

app_id

required

ADR 0030 W4 — when set, this schedule fires a kind='app' run of the given App on cadence. Exactly one of workflow_id / app_id / a task definition is set. Surfaced on the wire so the schedule-editor can show (and the trigger picker can filter on) the App target.

string | null format: uuid

app_inputs

required

ADR 0030 W4 — the per-fire App input payload prefilled into the run’s trigger context. None for a task / workflow schedule.

cadence

required

string

config

required

created_at

required

string format: date-time

failure_count

required

integer format: int32

required

string format: uuid

last_error

required

string | null

last_run_at

required

string | null format: date-time

last_run_id

required

The runs row of the schedule’s most recent fire (ADR 0022 R4). R5’s schedule-page run column links this into /runs/{last_run_id}; last_task_id (the task definition) is kept alongside it.

string | null format: uuid

last_task_id

required

string | null format: uuid

next_run_at

required

string | null format: date-time

project_id

required

string | null format: uuid

prompt

required

string

run_count

required

integer format: int32

status

required

string

timezone

required

string

title

required

string

updated_at

required

string format: date-time

user_id

required

string format: uuid

workflow_id

required

When set, this schedule fires a kind='workflow' run of the given workflow on cadence (ADR 0020 V4 schedule trigger). Exposed on the wire (V10) so the web builder’s schedule trigger config form can filter the schedules picker down to the rows that already belong to the workflow being edited, without a second round-trip.

string | null format: uuid

workspace_id

required

string format: uuid

Example^generated

{
  "agent_profile_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "agent_type": "example",
  "app_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "app_inputs": "example",
  "cadence": "example",
  "config": "example",
  "created_at": "2026-04-15T12:00:00Z",
  "failure_count": 1,
  "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "last_error": "example",
  "last_run_at": "2026-04-15T12:00:00Z",
  "last_run_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "last_task_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "next_run_at": "2026-04-15T12:00:00Z",
  "project_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "prompt": "example",
  "run_count": 1,
  "status": "example",
  "timezone": "example",
  "title": "example",
  "updated_at": "2026-04-15T12:00:00Z",
  "user_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "workflow_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "workspace_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
}

400

Structured client error

application/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object

code

required

Machine-readable, stable error code.

string

Allowed values: not_found unauthorized forbidden bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited quota_exceeded database_error docker_error vault_error internal_error

details

One of:

null
object

null

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

401

Authentication required

application/json

object

code

required

Machine-readable, stable error code.

string

details

One of:

null
object

null

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

403

Permission denied

application/json

object

code

required

Machine-readable, stable error code.

string

details

One of:

null
object

null

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

500

Structured server error

application/json

object

code

required

Machine-readable, stable error code.

string

details

One of:

null
object

null

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

post_api_schedules

Authorizations

Request Bodyrequired

Examplegenerated

Responses

200

Examplegenerated

400

Example

401

Example

403

Example

500

Example

Request Body^required

Example^generated

Example^generated