API Overview

Integrate with B3OS workflows, runs, connectors, execution hooks, Caddie chat, templates, and organization resources through the REST API.

The B3OS REST API lets backend services create workflows, publish versions, run workflows, inspect executions, manage connectors and API keys, configure execution webhooks, call Caddie workflow tooling, and read organization state.

B3OS public integrations page showing available automation surfaces

Base URL

text
https://api.b3os.org

All versioned endpoints use /v1.

text
https://api.b3os.org/v1/workflows

Authentication

Use a Bearer token:

http
Authorization: Bearer YOUR_API_KEY

See Authentication for API key scopes, user session behavior, organization context, and service-account guidance.

Major API Areas

AreaExamples
WorkflowsCreate, update, validate, publish, pause, resume, run, rollback, discard drafts, manage visibility
Runs and executionsList runs, stream run events, cancel runs, inspect node executions, activity streams
Triggers and webhooksGet trigger info, manage workflow webhook secrets, test triggers, resume waits
ActionsRead action schemas, logic actions, tags, and action execution surfaces
ConnectorsManage connector records and connector types
API keys and service accountsCreate, list, revoke, and scope machine access
Execution hooksConfigure signed run and execution event delivery
OrganizationsMembers, invites, restrictions, wallets, managed data, knowledge, Caddie profile, CU, subscription
Caddie workflow toolingChat, sessions, history, debug, schema search, and workflow repair
Templates and public resourcesTemplates, blocks, public workflows, public runs, public executions, widgets
x402Protected endpoint and payment-related workflow surfaces
API integration path
Bearer tokenrun or publisheventsobserve / reconcile Your backend Holds API keys and owns retries B3OS REST API Workflows, runs, connectors, org state Workflow execution Actions, wallets, policies Streams and hooks Run status, execution events, delivery logs

Request Format

Most write endpoints accept JSON:

http
Content-Type: application/json

Use standard HTTP status codes. Error responses include a message and may include field-level details depending on the endpoint.

Pagination

List endpoints generally support pagination parameters such as limit, offset, cursor, or endpoint-specific filters. Read the API reference for each endpoint's exact query parameters.

API keys should be used from trusted backend services. Do not put B3OS API keys in browser code or mobile clients.

Example: List Workflows

List workflows

bash curl https://api.b3os.org/v1/workflows \ -H "Authorization: Bearer YOUR_API_KEY"

Example response 200 
json
{  "workflows": [    {      "id": "wf_123",      "name": "Daily market alert",      "status": "active",      "visibility": "org"    }  ],  "hasMore": false}

API Reference

The API tab includes endpoint pages with exact paths, methods, request bodies, and response schemas.

Use narrative docs for concepts and integration patterns. Use the API reference for exact paths, methods, request bodies, and response schemas.

Previous Social
Next Authentication