Best practices

This page gives a few patterns that keep partner integrations stable and reliable. Use the interactive examples below as a start. Replace the handle, the slug, and the instruction with the values for your account.

Prefer a Format over raw model calls

When you have a saved recipe, call the recipe by its handle and slug. The Format owns the tools, the spend gates, and the house style. Your client only sends the brief.

For the full contract, refer to Calling a Format. When you must get typed JSON back, refer to Structured output.

Bind a schema when a system will consume the result

If another service will read the receipt, bind output_schema. Then you get a validated object, not free text. Mark a field as required only if the Format actually produces that field.

Full rules: Structured output.

Use Agent Completions for one-off work

If there is no saved Format or the brief changes each time, send an Agent Completion with a spend cap.

Keep credentials scoped

For Formats that are provisioned on a team handle, use a team API key. Select the narrowest scopes that your client needs. Rotate keys from the Dashboard.

Cap spend on every run

Always set generation_spend_cap_usd (and an agent cap when applicable). A missing cap is a bug in the client, not a convenience.