Share an AI video workflow with another team: Sume Format grants

To share an AI video workflow with another team on Sume, the workspace that owns the Format grants the other team's workspace access to run it, on the Format's Access tab or with POST /v1/formats/{handle}/{slug}/grants. Once the grant is live, the other team calls the Format at the owner's address with its own team key, and the runs, spend, and media belong to that team.

The facts below come from the sharing section of Create a run, Errors and spend, and the grant endpoints in the Sume API reference, read on 2026-09-26.

Who can share a Format, and with whom?

A team Format can be shared with another workspace, never with a user, the way a GitHub repository takes an outside collaborator. The invite names the other team's handle; user handles are not grantable. Only team Formats can be shared, and grants are managed by the owner workspace with a key created in that workspace.

Formats by Sume need no grant. Any key with the Formats scopes can call them at the reserved sume handle, and the run belongs to that key.

How do I invite another team to run my Format?

Two ways. Add the other team's handle on the Format's Access tab, which is live immediately. Or invite it over the API with formats:write and a key from your own team workspace. An API grant (fgr_…) starts pending and confers nothing until an admin of the invited workspace accepts it.

GET /v1/formats/{handle}/{slug}/grants lists your Format's live grants, pending and accepted, newest first. An invite is refused with 409 format_grant_exists when that workspace already holds a pending or accepted grant, 409 format_grant_self when it already owns the Format, and 409 format_workspace_required when the Format is not owned by a team workspace.

# Owner workspace: invite a team by its handle
curl -sS -X POST "https://api.sume.com/v1/formats/acme/product-promo/grants" \
  -H "Authorization: Bearer $OWNER_TEAM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workspace": "example-team"}'

# Invited workspace: list pending invites, then accept one
curl -sS "https://api.sume.com/v1/format-grants" \
  -H "Authorization: Bearer $YOUR_TEAM_KEY"
curl -sS -X POST "https://api.sume.com/v1/format-grants/fgr_…/accept" \
  -H "Authorization: Bearer $YOUR_TEAM_KEY"

How does the other team accept?

GET /v1/format-grants lists grants shared with the calling key's team workspace: pending invites an admin can accept, plus accepted ones. POST /v1/format-grants/{grant_id}/accept accepts one, using a key created in your own workspace with formats:write.

• Accept is idempotent: accepting an already-accepted grant answers it unchanged.
• A personal key reads an empty grant list and cannot accept; accept answers 403 workspace_key_required.
• A grant invited to a different workspace is a 404, indistinguishable from an unknown id.

Who pays for runs of a shared Format?

The team that calls it. You call the Format at the owner's address with your own team key, and there is no workspace field on the request: the key is the actor. The run, its spend, its concurrency slot, and its media are your workspace's, not the owner's.

GET …/runs with your key lists your runs only. If you hold seats in both workspaces, the key you bring decides: each workspace keeps its own run history and its own bill, and a key from one never reads the other's runs. Key basics are in How Sume API keys work.

What can still block a shared Format?

Always call with a team key: a personal key is refused the same way it is on any team Format, and membership of the owner workspace does not stand in for a grant. The owner also keeps control of whether the Format takes API calls at all. These are the answers a grantee meets:

What happens when the owner removes access?

The owner revokes with DELETE /v1/formats/{handle}/{slug}/grants/{workspace}, where {workspace} is the grantee's team handle or its org_… id. It works on pending and accepted grants.

• The grantee's in-flight runs finish.
• New lists, reads, and invokes fail closed immediately, and the address is a 404 for the grantee again.
• Revoked grants never appear in the live lists.