Accept a Format grant: personal key 403, wrong workspace 404

To accept a Format grant, call POST /v1/format-grants/{grant_id}/accept with formats:write and a key created in the invited team workspace. A personal key gets 403 workspace_key_required, and a grant id that was issued to some other workspace answers 404 format_grant_not_found, the same as an id that does not exist.

Until this call succeeds the grant is pending, and a pending grant gives the invitee nothing: the owner's Format address still answers 404 to them.

Find the grant first

The invitee can list their inbox with GET /v1/format-grants, which needs formats:read. It returns pending and accepted grants, newest first. With a personal key the inbox is simply an empty list rather than an error, so an empty inbox is the first thing to check if you expected an invite: you may be holding the wrong key.

# 1. see what is waiting for this workspace
curl -sS "https://api.sume.com/v1/format-grants" \
  -H "Authorization: Bearer $SUME_TEAM_KEY"

# 2. accept one (safe to repeat)
curl -sS -X POST "https://api.sume.com/v1/format-grants/$GRANT_ID/accept" \
  -H "Authorization: Bearer $SUME_TEAM_KEY"

What each failure means

Why wrong-workspace looks like not-found

The API refuses to confirm that a grant id exists for somebody else. If it answered 403 for a real id and 404 for a missing one, a caller could probe ids. So both read the same. When you see this error, compare the workspace of the key you used against the workspace the owner typed in the invite.

After accepting

Run the owner's Format at the owner's address with your own team key. There is no workspace field to add. The run, its spend, its concurrency slot and its media belong to your workspace, and GET .../runs lists only your runs.

What you can do depends on the role the owner chose: run means list, read, invoke and overlay; write adds editing through the Contents API.

A short onboarding checklist

For a partner who has never done this, the sequence is short. Create or find a team workspace, create an API key inside that team with formats:read and formats:write, call the inbox, accept the grant, and then run the Format once at the owner's address with a small input.

Do the first run with a modest per-run cap, because the spend lands on your bill and the owner's Format may be tuned for a different budget. If the first call returns 404, the cause is almost always one of two things: the accept did not happen, or the key belongs to a different workspace than the one that was invited.

Limits

Accepting does not copy the Format, so you cannot rename it, archive it, or change its Status or API trigger. Those stay with the owner and apply to every caller. If the owner revokes, your new calls fail closed at once while in-flight runs finish.