Revoke a Format grant: in-flight runs finish, new calls fail closed
DELETE .../grants/{workspace} revokes a pending or accepted grant. The grantee's running runs finish, and every new list, read or invoke fails closed at once.
DELETE /v1/formats/{handle}/{slug}/grants/{workspace} removes a workspace's access to your Format. Runs that the grantee already started keep going to their end; any new list, read or invoke from that workspace fails closed immediately and the address answers 404 format_not_found for them.
That asymmetry matters when you revoke a partner in the middle of a batch: you stop new spend at once, but you do not claw back the runs already in flight.
The call
The path segment {workspace} takes either the grantee's team handle or its org_... id, 2 to 64 characters. Use the org_ id when you stored it from an earlier grant receipt, because a handle can be renamed. The call needs formats:write and a key created in the Format's own team workspace.
It works on a pending grant as well as an accepted one, so it doubles as a way to withdraw an invite that was never accepted.
curl -sS -X DELETE "https://api.sume.com/v1/formats/acme/product-promo/grants/kiwi" \
-H "Authorization: Bearer $SUME_API_KEY"What comes back
The 200 response is the grant receipt with revoked_at set. That timestamp appears only on the receipt a revoke returns; the live roster never lists a revoked grant, so read the receipt if you need proof of when access ended.
| Question | Answer |
|---|---|
| Scope and key | formats:write, key created in the owner team workspace. |
| Targets | A pending or an accepted grant. |
| Grantee runs already started | They finish. |
| Grantee list, read, invoke afterward | Fail closed immediately; the address is a 404 for them. |
| Where revoked_at appears | On the receipt of the revoke call only. |
| Data to recover | None. No bytes were copied to the grantee. |
Spend after a revoke
Because runs bill to the grantee's workspace, the in-flight runs that finish after your revoke are on their bill, not yours. Your own cap on the Format does not apply to them either; each run carries the cap its caller sent.
If you need those runs gone too, the grantee must cancel them from their side. A grantee's runs are not visible to you: the runs list under the Format shows only the calling workspace's runs.
Limits
There is no bulk revoke. To remove a whole roster, list the grants and issue one DELETE per workspace.
A second DELETE on a grant that is already revoked reads as an unknown grant, which the API deliberately makes indistinguishable from other not-found cases. Treat a 404 on a repeat revoke as success in your own cleanup job.
Sources
Related posts
More in Formats
- Route tickets with Clef, then pick a Sume Format by its io profile
Clef routes a ticket by team and urgency. Then read GET /v1/formats/{handle}/{slug} for io.input_kind before you call POST .../runs. A short Python router.
- One Idempotency-Key, two Sume Formats: you start two runs
A Sume idempotency key is scoped to one Format, so one key sent to two Formats starts two paid runs. Build keys from order, Format and version.
- Client needs your Format: a grant, or a key from your workspace?
A grant bills the client and keeps the roster on your side; a team key you mint bills you. Pick the grant unless you intend to resell the output.
- Shared Format 409 format_inactive: the owner's switch hits partners
format_inactive and format_api_trigger_disabled are set on the owner's API tab and apply to every caller, including workspaces the Format was shared with.
Written by Sume