Create a schedule

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

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:

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:

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