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



## 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](/api/authentication) for API key scopes, user session behavior, organization context, and service-account guidance.

## Major API Areas

| Area | Examples |
| --- | --- |
| Workflows | Create, update, validate, publish, pause, resume, run, rollback, discard drafts, manage visibility |
| Runs and executions | List runs, stream run events, cancel runs, inspect node executions, activity streams |
| Triggers and webhooks | Get trigger info, manage workflow webhook secrets, test triggers, resume waits |
| Actions | Read action schemas, logic actions, tags, and action execution surfaces |
| Connectors | Manage connector records and connector types |
| API keys and service accounts | Create, list, revoke, and scope machine access |
| Execution hooks | Configure signed run and execution event delivery |
| Organizations | Members, invites, restrictions, wallets, managed data, knowledge, Caddie profile, CU, subscription |
| Caddie workflow tooling | Chat, sessions, history, debug, schema search, and workflow repair |
| Templates and public resources | Templates, blocks, public workflows, public runs, public executions, widgets |
| x402 | Protected endpoint and payment-related workflow surfaces |

**API integration path**

**Your backend**
  **B3OS REST API**
  **Workflow execution**
  **Streams and hooks**
  **Bearer token**
  **run or publish**
  **events**
  **observe / reconcile**

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

**Prefer server-side integration**

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

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

**API reference is the endpoint contract**

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