Create a Sume schedule by API? Dashboard first, then trigger by API

No, you cannot create a schedule through the Sume API. Schedules are created and edited in the dashboard only. The API can trigger and read an existing one, so the working pattern is to create the schedule once by hand, choose its trigger type, and then call it from your own code if it is an api-trigger schedule or a cron schedule with the API trigger enabled (Sume docs: Scheduled runs, read 2026-10-06).

There is also no MCP tool or CLI command for schedules, and the Developer API has no write endpoints for them. The docs say you can ask the Agent in chat to make one, so creation is a person or the in-product Agent, and your automation runs it from there.

Pick the trigger type carefully

The trigger type is fixed when you create the schedule. A cron trigger takes a five-field cron expression and an IANA time zone, and Sume starts the run on that clock. An api trigger has no clock of its own; it runs when your code calls it. You cannot change one into the other later, so if you are unsure, think about who should own the timing.

Choose cron when the timing is simple and fixed, like every Monday at nine in a given time zone. Choose api when the timing depends on something outside Sume, such as a content calendar, a deploy or an upstream data refresh.

Triggering from code

A trigger is a POST to /v1/actions/{handle}/{slug}/runs with a key that carries the actions:write scope. Older keys may not carry it, and scopes cannot be added to an existing key, so create a new one. Send an Idempotency-Key between 1 and 255 characters so retries replay.

Errors worth handling are action_inactive, when the schedule is switched off, and action_api_trigger_disabled, when you call the API on a schedule that has api_trigger_enabled set to false. Both mean fix the schedule, not retry.

import os, requests

H = {"Authorization": "Bearer " + os.environ["SUME_API_KEY"],
     "Idempotency-Key": "launch-recap-2026-10-06"}
r = requests.post(
    "https://api.sume.com/v1/actions/acme/launch-recap/runs",
    json={"input": {"launch": "october"}}, headers=H, timeout=30)
body = r.json()
err = (body.get("error") or {}).get("code")
if err in ("action_inactive", "action_api_trigger_disabled"):
    print("fix the schedule in the dashboard:", err)
else:
    print(r.status_code, body.get("data", {}).get("status"))

Where to read results

A scheduled run is read at /v1/action-runs/{id}. These runs do not appear in /v1/jobs, and events_url is null, so do not build monitoring on those. The public shape also omits the instruction text, which means the receipt shows what happened and what it cost, not the prompt you configured.

The default spend cap on a schedule is $1.00 and a per-run override can only lower it. If your work needs more, raise the cap in the dashboard where you set up the schedule.

Documenting the setup

Because creation happens in the dashboard, the configuration lives outside your repository. Write down the schedule's handle, slug, trigger type, cron and time zone, and cap in your runbook, so a rebuild or a hand-over does not depend on someone remembering which boxes were ticked.

When a Format and your own cron is simpler

If the only reason to want a schedule is to run a Format at a set time, your own scheduler calling the Format API is just as good and can be created and changed from code. A Sume schedule earns its place when you want the clock and the saved instructions on Sume's side.

Whichever you pick, keep an idempotency key per intended run, such as the date, so a duplicated tick from your scheduler does not produce two paid runs.