Create a schedule

You create schedules in the Agents dashboard. The Developer API has no create or update endpoint. Thus, this flow is the only way to author a schedule.

1. Open Scheduled

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

2. Write instructions and pick a model

The Agent executes the instructions on each run. Treat them as the prompt. They persist across runs, and data from the caller arrives separately (refer to Advanced: run a schedule via API).

Empty instructions cannot run. The run request fails with 400.

Cadence is the default and needs no extra choice. Select the frequency of the runs. Scheduled takes a 5-field cron expression and an IANA timezone. The hourly, daily, and weekly presets write the expression for you. The custom option accepts the raw expression.

Under Advanced, you can change the trigger to API call. This option persists trigger_type: "api" and removes the cadence fully. The schedule then runs only when your service calls Sume. Use this option when an external system, not a clock, decides when the work starts.

After you create the schedule, you cannot change trigger_type. An API-only schedule can never get a cadence. A cron schedule can never change to API-only. But a cron schedule can also enable the API trigger and accept both.

4. Set the spend cap

The generation spend cap sets the maximum that one run can spend on generation. If you do not set it, the effective default is $1.00 for each run.

A caller can use generation_spend_cap_usd to lower the cap for a single run. The caller can never raise it above the cap of the schedule. If you send null, the run has no automation ceiling (wallet balance, generation admission, and org limits still apply). The API rejects 0.

5. Bind an output schema (optional)

By default, Sume projects the output of a run onto sume/action-run-output/v1: { text, images[], videos[], audio[], files[] }. The Output schema section binds your own shape instead. Paste a JSON Schema. Give it a name. Then name the primary_output_key.

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

the root is an object.
each object sets "additionalProperties": false.
each property appears in required. An optional property uses a nullable union such as "type": ["string", "null"].
a maximum of 10 nesting levels, 5000 properties, and 1000 enum values.
$ref can point only at #/$defs/<name> or the registered SumeMediaFile#.

When you save, Sume rejects a schema outside the subset and lists the rules that it breaks. Load image example adds a valid image schema:

Name it sume/action-image-v1. Set the primary output key to image. Runs then return output.image.url as a durable media.sume.com URL. To go back to the default schema, clear the two fields.

Schema names accept A-Z a-z 0-9 . _ / -, up to 64 characters. When Sume calls the structuring model, it rewrites all characters outside A-Z a-z 0-9 _ -. The reason is that the provider accepts only the narrower set. Sume stores the name that you typed, and the receipt reports that name. For example, sume/action-image-v1 stays sume/action-image-v1 in output_schema.name.

Sume accepts strict: false and returns it on the receipt, but it does not relax the subset. Sume fills only schemas that it can mechanically satisfy.

6. Activate

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

7. Copy the invoke endpoint

When the API trigger is enabled, the trigger card shows the invoke endpoint, the required scopes, and a request that you can copy and paste:

The endpoint host depends on the dashboard that you copied it from. A dashboard on a *.dev.sume.com host gives https://api.dev.sume.com. All other dashboards give https://api.sume.com. Before you paste a copied command into production code, examine the host.

8. Check run history

The list shows each run with its trigger source. Runs started through the API have the label API. Scheduled runs have the label Cron.