REST API

Everything the web app does goes through the Botream Server's REST API, so you can start runs, read results and manage queues from your own scripts and systems. This page shows how to sign in, call the API and find the full reference.

#Base address

The API lives under /api on the same address and port as the web app, for example http://rpa-server:3000/api. Requests and responses use JSON.

Warning: Access tokens and passwords travel in every request. Publish Botream behind HTTPS when clients reach it over networks you do not trust.

#Authentication

Every endpoint needs a signed-in user, except signing in, refreshing, signing out, the health probe (GET /api/system/health) and the API documentation. API calls run with the permissions of the user who signed in, so create a dedicated user with the smallest role that does the job (see Users and roles).

#Sign in

Send the user name and password to POST /api/auth/login:

curl -X POST http://rpa-server:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"api-runner","password":"<password>"}'

The answer contains a short-lived access token, its lifetime in seconds and the user:

{
  "accessToken": "eyJhbGciOi...",
  "expiresIn": 900,
  "user": { "id": 7, "username": "api-runner", "...": "..." }
}

The server also sets a refresh token as an HttpOnly cookie (path /api/auth). The refresh token never appears in the response body.

#Token lifetimes

When the access token expires, either sign in again or call POST /api/auth/refresh with the refresh cookie. Each refresh returns a new access token and rotates the refresh cookie: the old refresh token stops working. Reusing an old refresh token is treated as theft and ends the session. POST /api/auth/logout revokes the session behind the cookie.

With curl, keep the cookie in a file:

# Sign in and store the refresh cookie
curl -c botream.cookies -X POST http://rpa-server:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"api-runner","password":"<password>"}'

# Later: a new access token (and a new cookie)
curl -b botream.cookies -c botream.cookies -X POST http://rpa-server:3000/api/auth/refresh

Note: Sign-in attempts are rate limited (by default 10 per minute, LOGIN_RATE_LIMIT_PER_MINUTE). A script should sign in once and reuse the access token until it expires, not sign in for every call.

#Calling the API

Send the access token in the Authorization header:

TOKEN="eyJhbGciOi..."
curl http://rpa-server:3000/api/auth/me -H "Authorization: Bearer $TOKEN"

In PowerShell:

$login = Invoke-RestMethod -Method Post -Uri "http://rpa-server:3000/api/auth/login" `
  -ContentType "application/json" -Body '{"username":"api-runner","password":"<password>"}'
$headers = @{ Authorization = "Bearer $($login.accessToken)" }
Invoke-RestMethod -Uri "http://rpa-server:3000/api/agents" -Headers $headers

#Errors

Failed requests answer with an HTTP status and a JSON body:

{ "statusCode": 409, "code": "CONFLICT", "message": "No agent is online" }

Validation errors add an issues list with the path and message of each invalid field. Typical statuses: 400 invalid request, 401 missing or expired token, 403 the user's role may not do this, 404 not found (also for executions the user may not see), 409 the request conflicts with the current state.

#Interactive documentation (Swagger)

The server can publish an OpenAPI 3.1 description of the API with a Swagger UI:

The documentation is on by default except in production. An installed Botream Server runs in production mode, so turn it on yourself: add "API_DOCS": "true" to C:\ProgramData\Botream\Server\server.json (or set the API_DOCS=true environment variable for the service) and restart the BotreamServer service. Each route in the Swagger UI shows its request and response schemas and a Roles: line with the roles allowed to call it; routes without that line accept any signed-in user. Click Authorize and paste an access token to try calls from the page.

#Endpoint groups

The table summarizes the main groups. The Swagger UI lists every route.

Live updates (execution logs, agent status) are not part of the REST API: the web app receives them over Socket.io on /monitor.

#Starting a run

POST /api/executions starts the current public version of a task, the same version schedules run.

curl -X POST http://rpa-server:3000/api/executions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"taskId": 42, "agentId": 3, "inputs": {"customer": "ACME Ltd", "maxOrders": 5}}'

The answer (201 Created) is the new execution, including its id. Follow it with:

# Status and result
curl http://rpa-server:3000/api/executions/1234 -H "Authorization: Bearer $TOKEN"

# Log lines
curl http://rpa-server:3000/api/executions/1234/logs -H "Authorization: Bearer $TOKEN"

# Stop it
curl -X POST http://rpa-server:3000/api/executions/1234/cancel -H "Authorization: Bearer $TOKEN"

Poll GET /api/executions/{id} until the status is final. When a run failed, GET /api/executions/{id}/failure returns the failing line, the variables (secrets masked) and whether a screen picture exists (GET /api/executions/{id}/failure/screenshot).

Tip: To feed a robot with work instead of starting it per item, add items to a work queue with POST /api/queues/{id}/items and let a schedule process the queue.

#Roles and permissions

API calls follow the same rules as the web app: the user's roles and their permissions decide, and a change of roles applies to the next call (no new token needed). Each route in the Swagger UI lists the permissions that allow it. With the default roles:

GET /api/auth/me returns the signed-in user with roles (names) and permissions (what they may do). Users are created and changed with roles: ["Runner", "Finance"]; the older role: "Runner" is still accepted, and role in answers is the first of roles (deprecated).

Without See all runs, users only see the executions they started; for executions they may not see, the API answers 404. Every security-relevant call (sign-ins, changes, credential access) is written to the audit log. See Users and roles for details.