Run bot

Queues a bot execution, as if it were triggered manually on the platform. The execution follows the same queue rules and shows up in Executions as soon as it starts.

Only bot_name is required. Without bot_version and agent_name, Sinfonia uses the bot’s release version and the agent configured in it. Without bot_params, it uses the bot’s default parameters.

POST /v1/run

Base URL: https://sinfonia.live/api

Headers

token stringrequired

API type token, generated in Administration → Tokens.

Example: YOUR_TOKEN

Content-Type stringrequired

Always application/json.

Example: application/json

Request body

bot_name stringrequired

Name of the bot to run.

Example: bot-notas-fiscais

bot_version stringoptional

Bot version. If omitted, the release version is used.

Example: 1.0.0

agent_name stringoptional

Agent that will run the bot. If omitted, the release version’s agent is used.

Example: SVWPRD0027

bot_params stringoptional

Execution parameters, as a JSON object serialized into a string. If omitted, the bot’s default parameters are used.

Example: {"PARAM1": "123", "PARAM2": "value2"}

label stringoptional

Free-form label to identify the execution on the platform.

Example: api-test

webhook_url stringoptional

URL that receives a POST when the execution finishes. See Completion webhook.

Example: https://meusistema.com/webhooks/sinfonia

Request example

curl -X POST "https://sinfonia.live/api/v1/run" \
  -H "token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_name": "bot-notas-fiscais",
    "bot_version": "1.0.0",
    "agent_name": "SVWPRD0027",
    "bot_params": "{\"PARAM1\": \"123\", \"PARAM2\": \"value2\"}",
    "label": "api-test",
    "webhook_url": "https://meusistema.com/webhooks/sinfonia"
  }'

const response = await fetch("https://sinfonia.live/api/v1/run", {
  method: "POST",
  headers: {
    "token": "YOUR_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "bot_name": "bot-notas-fiscais",
    "bot_version": "1.0.0",
    "agent_name": "SVWPRD0027",
    "bot_params": "{\"PARAM1\": \"123\", \"PARAM2\": \"value2\"}",
    "label": "api-test",
    "webhook_url": "https://meusistema.com/webhooks/sinfonia"
  }),
});

console.log(response.status);

import requests

response = requests.post(
    "https://sinfonia.live/api/v1/run",
    headers={"token": "YOUR_TOKEN"},
    json={
      "bot_name": "bot-notas-fiscais",
      "bot_version": "1.0.0",
      "agent_name": "SVWPRD0027",
      "bot_params": "{\"PARAM1\": \"123\", \"PARAM2\": \"value2\"}",
      "label": "api-test",
      "webhook_url": "https://meusistema.com/webhooks/sinfonia"
    },
)

print(response.status_code)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
	  "bot_name": "bot-notas-fiscais",
	  "bot_version": "1.0.0",
	  "agent_name": "SVWPRD0027",
	  "bot_params": "{\"PARAM1\": \"123\", \"PARAM2\": \"value2\"}",
	  "label": "api-test",
	  "webhook_url": "https://meusistema.com/webhooks/sinfonia"
	}`)

	req, err := http.NewRequest("POST", "https://sinfonia.live/api/v1/run", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("token", "YOUR_TOKEN")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.Status, string(data))
}

Responses

Execution added to the queue. The response has no body.

Notes

The success response doesn’t include the execution number. To know when it finished and with what result, provide a webhook_url: Sinfonia sends the exec_id and the status to it at the end. See Completion webhook.
bot_params is a string containing JSON, not an object. Serialize the parameters before sending, for example with JSON.stringify or json.dumps.
The parameters reach the bot just like in other execution methods. See how to read them in Script Examples.

Last updated on 03/11/2026

Authentication Execution log