API Quickstart

Create, validate, publish, run, and inspect a B3OS workflow with copy-paste API requests.

Use this path when you want to create workflows from a backend service, CI job, CLI, or provisioning script. The examples assume you already created an API key in the B3OS app.

Use B3OS API keys only from trusted backend environments. Browser and mobile clients should call your backend, not B3OS directly with a long-lived key.

API workflow lifecycle

Setup

bash
export B3OS_API_KEY="YOUR_API_KEY"export B3OS_API_URL="https://api.b3os.org"

Minimal Workflow Definition

This workflow starts with the manual trigger and logs the value supplied at run time.

json
{  "nodes": {    "root": {      "type": "manual",      "payload": {        "inputSchema": {          "type": "object",          "properties": {            "message": {              "type": "string"            }          }        }      },      "children": ["log_message"]    },    "log_message": {      "type": "log",      "payload": {        "message": "Incoming message: {{$trigger.body.message}}"      },      "children": []    }  }}

Create, Validate, Publish, Run

Create a workflow draft

bash
curl -sS -X POST "$B3OS_API_URL/v1/workflows" \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "name": "API quickstart logger",    "description": "A minimal workflow created from the API.",    "definition": {      "nodes": {        "root": {          "type": "manual",          "payload": {            "inputSchema": {              "type": "object",              "properties": {                "message": { "type": "string" }              }            }          },          "children": ["log_message"]        },        "log_message": {          "type": "log",          "payload": {            "message": "Incoming message: {{$trigger.body.message}}"          },          "children": []        }      }    }  }'

Validate before publishing

bash
curl -sS -X POST "$B3OS_API_URL/v1/workflows/validate" \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Content-Type: application/json" \  -d @workflow.json

Publish the workflow

bash
curl -sS -X POST "$B3OS_API_URL/v1/workflows/$WORKFLOW_ID/publish" \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Content-Type: application/json" \  -d '{}'

Run it with input

bash
curl -sS -X POST "$B3OS_API_URL/v1/workflows/$WORKFLOW_ID/run" \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "payload": {      "message": "Hello from the API"    },    "simulate": true  }'

Follow the Run

Use the run ID returned by the run request.

bash
curl -N "$B3OS_API_URL/v1/runs/$RUN_ID/stream" \  -H "Authorization: Bearer $B3OS_API_KEY"

javascript
const response = await fetch(`${process.env.B3OS_API_URL}/v1/runs/${runId}/stream`, {  headers: {    Authorization: `Bearer ${process.env.B3OS_API_KEY}`,  },});for await (const chunk of response.body) {  process.stdout.write(Buffer.from(chunk));}

python
import osimport requestswith requests.get(    f"{os.environ['B3OS_API_URL']}/v1/runs/{run_id}/stream",    headers={"Authorization": f"Bearer {os.environ['B3OS_API_KEY']}"},    stream=True,) as response:    for line in response.iter_lines():        if line:            print(line.decode())