Skip to main content
Use the Hobbes API when a backend service or coding agent needs to read or update the Playbook. Updates always go to staging first. Publishing production is a separate action with its own scope, confirmation, and test gate.
For a person working from Claude or another AI client, connect to the Hobbes MCP server instead of managing an API key.

​
Choose scopes

These scopes are off by default and are never added to existing keys. Create or rotate a key with only the access the integration needs.

​
Preview and apply a change

1

Read the current Playbook

Call GET /api/v1/playbook. Save sectionsEtag and use the returned section catalog to target supported fields. The response also includes links for testing the staging and production agents.
2

Create a preview

Call POST /api/v1/playbook/update-previews with restricted JSON Patch operations and a stable operationKey. Set expectedSectionsEtag to the current sectionsEtag. Hobbes validates the request against a clone and returns a before-and-after summary without changing staging.
3

Review the summary

Show the changed sections to the person who requested the update. Do not treat a preview as an applied or published change.
4

Apply the preview to staging

Call POST /api/v1/playbook/update-previews/{preview_id}/apply. The preview must be unexpired and created by the same API key. If staging changed after the preview, Hobbes returns 409 and creates no version. Create a fresh preview against the latest sectionsEtag.
5

Test staging

Open the staging link from Hobbes and verify the changed behavior before publishing.
Previews expire after 24 hours. Repeating a successful apply returns the original result instead of creating another version.

​
Apply a Hobbes suggestion

Call GET /api/v1/playbook/suggestions to list ready suggestion groups with their evidence and exact proposed changes. Apply one with POST /api/v1/playbook/suggestions/{group_id}/apply only when the stored wording should be used as generated. Use the preview process when the wording needs to change.

​
Publish the staged agent

Publishing changes production and requires a new confirmation at the time of the request.
  1. Read the Playbook again and confirm the exact current staging version.
  2. Ask the user to confirm publishing that version to production.
  3. Call POST /api/v1/agent/publish-jobs with a stable operationKey, the current staging version, and confirmation: "publish_to_production".
  4. Poll GET /api/v1/agent/publish-jobs/{job_id}. Send the returned ETag as If-None-Match and honor Retry-After.
Hobbes runs its conversation tests before changing production. A failed job does not publish the agent. Review its safe failure message, correct staging, and ask for confirmation again before creating a different publish job.
Never infer publishing approval from an earlier Playbook request. The user must confirm the exact staged version immediately before the publish job is queued.