Which Sume key scope starts a Format, schedule or agent run

Three scopes start three kinds of agent work on Sume: formats:write starts a Format run, actions:write starts a schedule (Action) run, and agent_completions:write starts an Agent Completion. Each has a matching :read scope for reading runs. Keys created before a scope shipped do not have it, and you cannot add scopes to an existing key.

The usual cause of a 403

A 403 insufficient_scope on a create almost always means the key, not the body. The docs say the same for Format runs and schedule runs: an older key fails each run request, and the fix is to create a new key in the dashboard and rotate to it. Service-account keys cannot create Format runs or Action runs, and fail with the same code and a reason in details.

Three scopes, three starts

Here are the three side by side, so you can pick the right key before you wire up a job.

Defaults that differ

The defaults point in different directions, which is the second trap. A Format run defaults to allow, so two calls run side by side. A schedule defaults to skip, so a second start while one is running is recorded as skipped. The docs warn not to copy a scheduled body into a Format call for that reason.

Check a key before you deploy

The script below tests a key before a deploy. It sends a Format run with a body that cannot start a run, and reads only the status code: a 403 means the key lacks the scope, and a 400 means the scope is present and the empty body was refused. The documented empty-body rule is that {} is 400 invalid_request, so nothing runs and nothing is charged.

import json, os, urllib.error, urllib.request
req = urllib.request.Request(
    "https://api.sume.com/v1/formats/sume/sume-product-commercial/runs",
    data=b"{}",
    method="POST",
    headers={
        "Authorization": "Bearer " + os.environ["SUME_API_KEY"],
        "Content-Type": "application/json",
        "Idempotency-Key": "scope-probe-1",
    },
)
try:
    urllib.request.urlopen(req)
except urllib.error.HTTPError as e:
    body = json.load(e)
    print(e.code, json.dumps(body)[:300])

Reading the probe

Read the output as a probe, not a run. A 400 is the good answer here. If you see 403, create a new key with the scopes you need, keep the old one until the cutover, and then revoke it.

Habits

Keep one key per job type, name it for the job, and rotate it on a schedule you can remember. A key with only formats:write cannot start a schedule, and that is the point.