Agent productions

Agent runs coordinate several creative steps. They require agents:write for creation, approval, and review, and agents:read for retrieval.

1. Request a plan

curl --fail-with-body https://app.verbatik.com/api/v1/agents/runs \
  -H "Authorization: Bearer $VERBATIK_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: campaign-plan-001' \
  -d '{
    "brief":"Plan a coffee-cup launch with a square product image and a short voiceover.",
    "priority":"balanced",
    "direction_strategy":"best",
    "auto_approve":false
  }'

The brief supports up to 12,000 characters. Optional source_images accepts up to 12 HTTPS image URLs. Priority can be quality, balanced, cost, or speed; direction strategy can be best or multiple.

Planning itself uses credits, even when auto_approve is false. A successful proposal returns 201 with its ID, plan, and estimated_credits.

2. Approve a budget

Read the proposed steps and estimate before approving. Send POST /agents/runs/{id}/approve with a positive integer max_credits that is at least the current estimate. You may optionally provide an edited plan using the schema in the reference.

{
  "max_credits": 100
}

The number above is illustrative; use a budget you have reviewed against the returned plan. Execution reserves credits and requires the Agent worker to be available. Planning charges are separate from the execution budget.

With auto_approve: true, creation attempts approval immediately. Inspect auto_approval_error and the returned status: a created plan can still need manual approval if the budget is too small or execution cannot start.

3. Monitor and review

Poll GET /agents/runs/{id} or subscribe to Agent webhooks. The run exposes its plan, status, estimates, reserved and spent credits, completed step IDs, and outputs. Only one live Agent run executes per workspace.

When the run requires review, send POST /agents/runs/{id}/review with one of these decisions:

{ "decision": "assets_only" }

Use assemble when you want the available assembly result, or assets_only to complete with the generated assets. A run that is not waiting for review returns 409 for a review action.

Unused execution reservations are released on completion. Completed paid steps remain charged. Use idempotency keys for the create, approve, and review actions.