Invite a workspace to run your Format: POST grants stays pending

To let another team run a Format you own, call POST /v1/formats/{handle}/{slug}/grants with the invitee's team handle. The response is 201 with a grant whose status is pending, and a pending grant confers nothing: the other workspace still gets 404 format_not_found until one of its admins accepts.

This page is about the owner side of that call: what the key must be, what the body accepts, and what you can and cannot tell from the receipt. The invitee side is a different endpoint and is covered in the accept post of this series.

The request

The call needs the formats:write scope and a key that was created in the Format's own team workspace. A personal key is refused, because only the owning team workspace manages the roster. The body has one required field and one optional field.

The same share can also be made on the Format's Access tab in the dashboard, where it is live immediately. The API route is the scriptable path.

curl -sS -X POST "https://api.sume.com/v1/formats/acme/product-promo/grants" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workspace":"kiwi","role":"run"}'

What the grant says

Run versus write

run lets the grantee list, read, invoke and overlay the Format. write adds editing the package through the Contents API at your same {handle}/{slug} address. Managing the roster itself is never granted: invite, change role and revoke stay with the owner workspace.

The grantee never gets a copy. The Format stays at your address, so a grantee calls POST /v1/formats/acme/product-promo/runs with their own team key, and a revoke is complete by construction because no bytes moved.

Store the grant id

Keep the fgr_ id from the 201. The invitee's admin needs it for the accept call, and you will want it in your records when you audit who has access. The roster read is the source of truth if you lose it.

Limits and when not to use this

Only a Format owned by a team workspace can be shared. If your Format lives under a personal account, the call returns a 409 with format_workspace_required, and the fix is to move the work into a team rather than to retry.

If the other party only needs to try one output, a grant is more than you need. Run the Format yourself and hand over the result URL instead; a grant is for a partner who will run it repeatedly on their own bill.