Audit who can run your Format: list grants, pending versus accepted

To see which workspaces can run your Format, call GET /v1/formats/{handle}/{slug}/grants with formats:read and a key created in the Format's own team workspace. It lists the live grants, pending and accepted together, newest first, and leaves out revoked ones, so what you read is exactly who could call the address right now or could once they accept.

Reading the list

Each entry in data is a format.grant object with an fgr_ id, grantee_workspace_id, grantee_workspace_handle, the role (run or write) and a status. pending means invited but not accepted, which confers nothing. accepted means the grantee can use the role.

A pending entry that has sat for weeks is a cleanup candidate: either the partner never received the invite, or the deal fell through. Withdrawing it is a plain revoke.

import os, requests
base = "https://api.sume.com/v1/formats/acme/product-promo/grants"
h = {"Authorization": "Bearer " + os.environ["SUME_API_KEY"]}
r = requests.get(base, headers=h, timeout=30)
r.raise_for_status()
for g in r.json().get("data", []):
    print(g["id"], g["status"], g["role"], g["grantee_workspace_handle"])

What to check each time

Keep it cheap

The list is a read, so it spends the read budget and no credits. Run it from a weekly job and compare with your own record of who you invited. If the list shows a workspace that your records do not, that is a prompt to find out who invited it from the dashboard's Access tab, which can create live grants without the API.

A routine that scales

If you share a Format with many client workspaces, put the audit on a calendar. Each Monday, list the grants, diff the result against yesterday's copy, and post any new or changed row to the channel your team reads. A new write grant or a workspace nobody remembers inviting deserves a human look the same day.

Pair the audit with an offboarding rule: when a contract ends, the revoke is the first task, not the last. A revoke is complete by construction because nothing was copied to the grantee, so there is no data to chase down afterward. The runs already started finish on the grantee's own bill.

Record the fgr_ id next to each partner in your own system. It makes every later revoke or role change a one-line job.

Limits

The list does not show how much a grantee has spent or how many runs they made; those belong to the grantee's workspace and bill, and you cannot read their runs. If you need usage numbers for a partner, ask them for their own usage export.

Revoked grants disappear from the list, so keep your own log of revocations, including the revoked_at value that the revoke call returns.