Can I create a Sume scheduled agent by API? Read and run, not create

No: the Sume API cannot create, edit or delete a scheduled agent. You author a schedule in the Agents dashboard, or by asking the Agent in chat to set one up. The Developer API can list schedules, read them, start runs and monitor runs. If your pipeline has to create the saved object itself, the object to reach for is a Format, which POST /v1/formats does create.

What can the API do with a schedule?

The product is called Scheduled; the HTTP namespace is still /v1/actions, ids are aut_…, and objects come back as object: "action". Those names are stable.

The table separates what the public API covers from what stays in the dashboard, as documented.

Why are instructions hidden from the API?

The instructions text is deliberately omitted from the public shape. You read and edit instructions in the dashboard. The API gives you an invoke handle: an invoke_url, the trigger_type, an optional cron with next_run_at, the output schema binding and the cap in generation_spend_cap_usd_micros.

So the clean split is that a person (or the chat Agent) owns what the schedule does, and your service owns when it fires and what data goes in. Caller data arrives separately as input, as data and never as instructions.

What if I need to create the workflow in code?

Use a Format. A Format is a saved packaged workflow that an API key can create with POST /v1/formats and edit through the Contents API, with SKILL.md as the entry file. It runs through POST /v1/formats/{handle}/{slug}/runs, a different surface with its own receipt and its own on_active_run default.

If the task itself changes on every call and nothing is worth saving, neither is right: Agent Completions takes the instruction per request and stores nothing.

How do I list what exists today?

A read-only listing is the way to audit schedules from code. Pass next_cursor back as cursor until has_more is false; limit takes 1 to 100 and defaults to 50.

curl -sS "https://api.sume.com/v1/actions?limit=20" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  | jq '.data[] | {id, title, status, trigger_type, api_trigger_enabled, next_run: .cron.next_run_at}'

Which surface should my team pick?

Pick by who owns the instructions. If a person or the chat Agent owns them and a clock or an external event decides when work happens, a schedule fits, and your code only fires and monitors it. If your code owns the recipe, so that versions, reviews and edits flow through your own tooling, a Format fits, since its package is files you can read and commit over the API. The two return the same receipt shape and run the same agent. They differ in where the instruction comes from and what Sume saves on your behalf.