End-to-end flow
This example puts the API pieces together in a typical integration flow:
Run the bot
Your system calls POST /v1/run with the bot name, the parameters and a webhook_url.
Receive the result
When the execution finishes, Sinfonia calls the webhook_url with the exec_id and the status.
Fetch the log
With the exec_id, your system calls GET /v1/execlog/{id} and stores the log or handles the error.
Trigger the execution
import json
import os
import requests
SINFONIA_API = "https://sinfonia.live/api"
TOKEN = os.environ["SINFONIA_TOKEN"]
def run_billing(month: str) -> None:
response = requests.post(
f"{SINFONIA_API}/v1/run",
headers={"token": TOKEN},
json={
"bot_name": "bot-billing",
"bot_params": json.dumps({"MONTH": month}),
"label": f"bill-{month}",
"webhook_url": "https://mysystem.com/webhooks/sinfonia?key=a-long-secret",
},
timeout=30,
)
response.raise_for_status() # 200: execution queued
run_billing("2026-10")Note
Notice that bot_params is serialized twice: the parameters become a JSON string, and that string goes inside the request body.
Receive the result and fetch the log
The webhook receiver gets the exec_id, fetches the log and decides what to do. See the full code in Completion webhook.
Error handling
| Status | What to do |
|---|---|
400 | Check the bot name, version, agent and whether the body is valid JSON. |
401 | Check the token header and whether the token still exists on the Tokens screen. |
429 | Wait and try again. The limit is 5 requests per second per route. |
5xx | Retry with increasing intervals between attempts. |
Last updated on