---
title: Create a schedule
description: Author a recurring Agents automation in the dashboard, and pick a cadence.
---

Schedules are created in the Agents dashboard. The Developer API has no create
or update endpoint, so this flow is the only way to author one.

## 1. Open Scheduled

Go to `https://www.sume.com/agents/scheduled` and use the Create control in the
header.

## 2. Write instructions and pick a model

Instructions are what the Agent carries out on every run. Treat them as the
prompt: they persist across runs, and caller-supplied data arrives separately
(see [Advanced: run a schedule via API](/agents/actions/api-trigger)).

Empty instructions cannot run — the run request fails with `400`.

## 3. Set the cadence

Cadence is the default and needs no extra choice: pick how often it should run.
**Scheduled** takes a 5-field cron expression and an IANA timezone. Hourly,
daily, and weekly presets write the expression for you; custom accepts the raw
expression.

Under **Advanced** you can switch the trigger to **API call**, which persists
`trigger_type: "api"` and drops the cadence entirely — the schedule then runs
only when your service calls Sume. Reach for it when an external system, not a
clock, decides when work happens.

`trigger_type` is fixed once created. An API-only one can never gain a cadence,
and a cron one can never drop to API-only. A cron schedule can, however, also
enable the API trigger and accept both.

## 4. Set the spend cap

The generation spend cap bounds what one run may spend on generation. When
unset, the effective default is $1.00 per run.

A caller can lower the cap for a single run with `generation_spend_cap_usd`, but
never raise it above the schedule's cap.

## 5. Bind an output schema (optional)

By default a run's `output` is projected onto `sume/action-run-output/v1` —
`{ text, images[], videos[], audio[], files[] }`. The **Output schema** section
binds your own shape instead: paste a JSON Schema, name it, and name the
`primary_output_key`.

Custom schemas must follow the strict subset (the same rules OpenAI Structured
Outputs enforces):

- the root is an object;
- every object sets `"additionalProperties": false`;
- every property appears in `required` — optionality is a nullable union such as
  `"type": ["string", "null"]`;
- at most 10 nesting levels, 5000 properties, and 1000 enum values;
- `$ref` may only point at `#/$defs/<name>` or the registered `SumeMediaFile#`.

A schema outside the subset is rejected when you save, with the offending rules
listed. **Load image example** fills a working image schema:

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": ["caption", "image"],
  "properties": {
    "caption": { "type": ["string", "null"] },
    "image": { "$ref": "SumeMediaFile#" }
  }
}
```

Name it `sume/action-image-v1` and set the primary output key to `image`. Runs
then return `output.image.url` as a durable `media.sume.com` URL. Clear both
fields to go back to the default schema.

Schema names accept `A-Z a-z 0-9 . _ / -`, up to 64 characters. Sume rewrites
anything outside `A-Z a-z 0-9 _ -` when it calls the structuring model, because
that provider only accepts the narrower set. The name you typed is what is
stored and what the receipt reports — `sume/action-image-v1` stays
`sume/action-image-v1` in `output_schema.name`.

`strict: false` is accepted and echoed on the receipt, but it does not relax the
subset — Sume only fills schemas it can mechanically satisfy.

## 6. Activate

Set the schedule to Active. While it is Inactive, API runs are rejected with
`409 action_inactive`.

## 7. Copy the invoke endpoint

With the API trigger enabled, the trigger card shows the invoke endpoint, the
required scopes, and a copy-pasteable request:

```bash
curl -sS -X POST "https://api.sume.com/v1/actions/$ACTION_ID/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'
```

The endpoint host follows the dashboard you copied it from. A dashboard served
from a `*.dev.sume.com` host yields `https://api.dev.sume.com`; everything else
yields `https://api.sume.com`. Check the host before pasting a copied command
into production code.

## 8. Check run history

Each run is listed with its trigger source. Runs started through the API are
labeled `API`; scheduled runs are labeled `Cron`.

## Next

- [Runs and results](/agents/actions/runs)
- [Advanced: run a schedule via API](/agents/actions/api-trigger)