Share a Format with another workspace: grants, accept and the 404

To let another workspace run your team Format, the owner grants access to that workspace, and its admin accepts. The grant is workspace to workspace and never to a single user, like adding an outside collaborator to a GitHub repository. After the grant, the other team calls the Format at the owner's address with its own team key, and the run, the spend and the media belong to the caller's workspace.

The flow

The call docs describe two ways for the owner to add a workspace: type the team handle on the Format's Access tab, which is live immediately, or invite with an API call. Then the other workspace accepts.

What the guest workspace gets

The request has no workspace field: the key is the actor. The caller's run history lists only its own runs, and each workspace keeps its own bill. GET …/runs with the guest key returns only the guest's runs, and a key from one workspace never reads the other workspace's runs.

• Spend, concurrency slot and media belong to the guest workspace.
• The owner's Status and API-call trigger apply to every caller; format_inactive or format_api_trigger_disabled returns 409 for guests too.
• Seats in both workspaces do not merge access. The key you use decides.

Failure modes

A grant that is still pending, or that the owner removed, gives 404 format_not_found, the same answer as an address that does not exist. A personal key on any team Format gives 403 workspace_key_required. If your guest calls fail, check three things in order: the grant is accepted, the key is from the accepting workspace, and the key carries formats:write.

When to use a grant

A grant fits an agency that builds a Format for several client workspaces, or two teams in one company that want to share one recipe while paying separately. The owner keeps control of the recipe, and each guest pays for its own runs. If you instead want a guest to change the recipe, a grant does not do that: the guest calls the Format. For a changed copy, fork the Format in the library, and call your copy at {your_handle}/{slug}.

Plan for the owner's switches. If the owner disables the API trigger or sets the Format inactive, every guest gets a 409, and the guests see no change on their side. Tell guests which webhook and schema your Format expects, since input has no published field list and the owner's recipe is the only contract.

Keep a record of grants on your side as well: the grant id, the guest handle, the date of accept, and who asked for it. The API gives the owner the Access tab, and a short internal list makes it easier to see who can call a Format when you plan a change to its recipe or its schema.