> ## Documentation Index
> Fetch the complete documentation index at: https://docs.b3os.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

**Keep API keys server-side**

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**

**Backend service**
  **Create draft**
  **Validate**
  **Publish**
  **Run and stream**
  **definition**
  **schema check**
  **valid**
  **live version**

## 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
curl -N "$B3OS_API_URL/v1/runs/$RUN_ID/stream" \
  -H "Authorization: Bearer $B3OS_API_KEY"
```

```javascript node.js
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 python
import os
import requests

with 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())
```

## Read Next

**[Workflow JSON](/examples/workflow-json)**

Learn the graph shape, node IDs, payloads, children, connectors, and expressions.
  **[Action Testing](/examples/action-testing)**

Inspect action schemas and run action-level tests before adding nodes.
  **[API Reference](/api/reference/post-v1-workflows)**

Use the API pages for exact request and response schemas.