Developer foundations

TL;DR: The building blocks for integrating with Ballet. Authenticate with a workspace API token, run playbooks over the REST API, stream live run and step events over SSE, wake suspended runs with reply/resume, trigger runs from external events with webhooks, or connect Ballet as an MCP server so any MCP client can call your playbooks.

Who this is for

Developers who want the core primitives before building a framework integration.

What's covered here

• Authentication and API tokens — create a token and send it as a Bearer credential.
• Run playbooks over the REST API — execute a playbook and read its run and step results.
• Stream run events — the SSE envelope, run/step lifecycle, input_request, and error types.
• Wake a suspended run — POST /reply and /resume for durable pause/continue.
• Webhooks — start runs from external events and react to completion.
• The MCP endpoint — connect Ballet as an MCP server and the tools it exposes.

Which approach should I use?

• Direct control from your backend or CI — REST API
• Live progress in a UI or agent loop — Streaming run events (SSE)
• Continue a parked HITL / pause — Reply / resume
• React to an external event — Webhook trigger
• Let an MCP-aware client/agent drive Ballet — MCP endpoint

Related articles

• How do I create and use API tokens?
• How do I pause and resume a playbook run?
• How do I run a playbook?
• What triggers can start a playbook?
• Agent frameworks