# API Reference

> Every REST v1 endpoint, the auth model, error shape, rate limits, and webhook events. The marketing API page is at [/api](https://www.synthboard.ai/api); the interactive OpenAPI explorer is at [/docs/api](https://www.synthboard.ai/docs/api). This page is the complete operator reference.

**Canonical URL:** https://www.synthboard.ai/docs/api
**Markdown source:** https://www.synthboard.ai/docs/api.md
**Base URL:** https://www.synthboard.ai/api/v1
**Auth:** `Authorization: Bearer sb_live_...` (API key) or an OAuth 2.1 access token
**Availability:** every tier, including Free. Tier changes rate-limit capacity, not feature access.
**Machine-readable spec:** https://www.synthboard.ai/api/v1/openapi.json

## Auth

```http
Authorization: Bearer sb_live_...
```

Create keys in the Control Center at [/mcp/console](https://www.synthboard.ai/mcp/console). Keys are prefixed `sb_live_` (or `sb_test_` for test keys) and carry explicit scopes. OAuth 2.1 with PKCE and dynamic client registration is also supported — the same endpoints accept either credential.

Scopes (each endpoint requires exactly one):

- `session:read` — read sessions, tasks, transcripts, exports, shares
- `session:write` — create/reconvene/cancel/fork/share sessions + bookmarks/decisions
- `synth:chat` — 1-on-1 chat with an expert + Consult turns
- `synth:read` — read expert profiles + knowledge listings
- `synth:write` — create/edit/delete experts of your own, preferences, knowledge
- `assistant:use` — Session Assistant Q&A
- `integrations:read` — list connected integration providers
- `integrations:write` — execute or reverse proposed tool actions + webhook subscription CRUD

## Endpoints

Grouped inventory of the v1 surface. Paths are relative to `https://www.synthboard.ai/api/v1`.

### Meta

| Method | Path | What it does |
|---|---|---|
| GET | /health | Unauthenticated health probe |

### Sessions

| Method | Path | What it does |
|---|---|---|
| POST | /sessions | Start a session (plan_id or explicit setup; session_type boardroom or consult) |
| GET | /sessions | List sessions with filter/sort/cursor |
| POST | /sessions/plan | Propose a session setup + credit estimate without starting |
| GET | /sessions/{id} | Get session state + latest task (v4_phase, decision_brief, memo, board_artifact) |
| PATCH | /sessions/{id} | Rename / retag a session |
| DELETE | /sessions/{id} | Hard-delete a draft session |
| POST | /sessions/{id}/continue | Follow-up round (legacy-engine sessions) |
| POST | /sessions/{id}/reconvene | Chain a new board round on a completed board (returns new_session_id) |
| POST | /sessions/{id}/messages | Send one Consult turn (expert reply + composed document) |
| POST | /sessions/{id}/cancel | Cancel the in-flight task |
| POST | /sessions/{id}/outcomes | Generate a deliverable (action plan / report / memo / bullets) |
| POST | /sessions/{id}/export | Export as markdown / JSON / text |
| POST | /sessions/{id}/archive | Archive or unarchive |
| POST | /sessions/{id}/fork | Duplicate with altered context (rerun optional) |
| POST | /sessions/{id}/update | Mid-session mutations on legacy-engine sessions (experts, mode, tuning) |
| GET | /sessions/{id}/live-summary | Live snapshot: who agrees, who dissents, running confidence |
| GET | /sessions/{id}/cross-round | How positions moved across rounds |
| POST | /sessions/{id}/assistant | Ask the Session Assistant |
| POST | /sessions/{id}/bookmarks | Bookmark a moment or pin a thread |
| POST | /sessions/{id}/decisions | Capture a formal decision record |
| POST | /sessions/{id}/promote-to-synth | Promote session documents into an expert's knowledge |

### Experts (the paths say `synths`)

| Method | Path | What it does |
|---|---|---|
| POST | /synths/chat | 1-on-1 chat with an expert in a session |
| GET | /synths | List experts (the 24 named experts, public ones, and your own) |
| POST | /synths | Create an expert of your own |
| GET | /synths/{id} | Get an expert |
| PATCH | /synths/{id} | Update an expert of your own |
| DELETE | /synths/{id} | Delete an expert of your own |
| PATCH | /synths/{id}/preferences | Set per-user preferences for one of the 24 named experts |
| DELETE | /synths/{id}/preferences | Reset those preferences |
| GET | /synths/{id}/knowledge | List an expert's knowledge files |
| POST | /synths/{id}/knowledge | Add knowledge (URL or text) |
| DELETE | /synths/{id}/knowledge/{fileId} | Remove a knowledge file |

### Catalog

| Method | Path | What it does |
|---|---|---|
| GET | /catalog/search | Search the catalog (experts, templates, strategies, models) |

### Shares

| Method | Path | What it does |
|---|---|---|
| GET | /shares | List shares for a session |
| POST | /shares | Create a share link (public, password, or invite) |
| DELETE | /shares/{id} | Revoke a share by share code |
| POST | /shares/verify-password | Verify a password-protected share |

### Actions & integrations

| Method | Path | What it does |
|---|---|---|
| POST | /actions/execute | Execute a Recommended Action via a connected tool |
| POST | /actions/undo | Reverse an executed action where the tool allows it |
| GET | /integrations | List connected integration providers |

### Webhooks

| Method | Path | What it does |
|---|---|---|
| GET | /webhooks | List webhook subscriptions |
| POST | /webhooks | Create a subscription (signing secret returned once) |
| PATCH | /webhooks/{id} | Update / enable / disable a subscription |
| DELETE | /webhooks/{id} | Delete a subscription |
| GET | /webhooks/{id}/deliveries | Recent delivery attempts for a subscription |

## A quick example

Start a board, then poll until the memo lands. Sessions started over the API run the same engine as the web app — an express intake turns the question into a decision brief, the brief staffs the board, the board researches alone and then reacts once, and the run terminates in a decision memo or a shaped artifact.

```http
POST https://www.synthboard.ai/api/v1/sessions
Authorization: Bearer sb_live_...
Content-Type: application/json

{
  "question": "Should we move enterprise pricing from $50 to $99?",
  "session_type": "boardroom",
  "mode": "decision",
  "context": "Currently $50/mo for Max. Considering a new Ultra at $199."
}
```

Poll with long-poll `wait_ms` (up to 60,000 ms per request):

```http
GET https://www.synthboard.ai/api/v1/sessions/{id}?wait_ms=60000
Authorization: Bearer sb_live_...
```

Completed boards return `v4_phase`, `decision_brief`, `memo`, and `board_artifact` on the session read. There is no server-sent-events stream — poll with `wait_ms`, or subscribe to [webhooks](https://www.synthboard.ai/docs/webhooks) for completion events.

## The Consult over the API

A Consult is a 1-on-1 with a single named expert, billed per turn:

```http
POST /api/v1/sessions
{ "question": "Rewrite my pricing page hero", "session_type": "consult", "synth_id": "the-marketer" }

POST /api/v1/sessions/{id}/messages
{ "message": "Make it sharper — lead with the outcome, not the mechanism." }
```

Each turn returns the expert's reply and any composed document.

## Plan before start

`POST /sessions/plan` proposes a full setup — the staffed board and a credit estimate — without charging anything, and returns a single-use `plan_id` (valid 15 minutes). Pass that `plan_id` to `POST /sessions` to run exactly the approved plan.

## Idempotency

Write operations accept an optional `idempotency_key` **body field** (8–128 chars). Retrying with the same key returns the original result instead of duplicating work — safe to retry on network errors.

## Pagination

`GET /sessions` uses cursor pagination:

```http
GET /api/v1/sessions?limit=50&cursor=...
```

The response includes a `next_cursor` when more results exist.

## Errors

Every error is a JSON envelope with a machine-readable code and a correlation id you can quote to support:

```json
{
  "error": {
    "code": "insufficient_credits",
    "message": "Estimated cost is 120 credits. Account balance is 40.",
    "correlation_id": "abc123...",
    "retry_after_s": 60
  }
}
```

Common codes: `unauthorized` (401), `scope_missing` / `forbidden` (403), `not_found` (404), `validation_error` / `invalid_session_state` (400), `insufficient_credits` / `daily_spend_cap_exceeded` / `monthly_budget_exceeded` (402 — the last two are per-key spend caps you configure on the key), `rate_limited` (429, includes `retry_after_s`), `concurrent_session_limit` (409 — a resource-state conflict, retry after a running session finishes), `upstream_error` / `internal_error` (5xx). The full code list is in the OpenAPI spec.

## Rate limits

Limits are per-endpoint sliding windows. Baselines are the Pro tier; other tiers multiply capacity (Free 0.15x, Pro 1x, Max 3.3x, Ultra 16x). Representative Pro baselines:

- `POST /sessions` — 60 per hour
- `POST /sessions/plan` — 120 per hour
- `GET /sessions/{id}` and most reads — 60 per minute
- `POST /actions/execute` — 10 per minute
- Webhook subscription writes — 20 per minute

Exceeding a limit returns `429 rate_limited` with `retry_after_s`. Rate limits are operational caps, not feature gates.

## Webhooks

Subscribe a URL via `POST /api/v1/webhooks` or from [/mcp/console](https://www.synthboard.ai/mcp/console). Deliveries are HMAC-SHA256 signed (`X-SynthBoard-Signature` over `timestamp.body`, with the timestamp in `X-SynthBoard-Timestamp`).

The six events:

- `session.complete`
- `session.failed`
- `session.cancelled`
- `session.continued`
- `session.reconvened`
- `outcomes.ready`

Payloads, signature verification code, and retry behavior: [/docs/webhooks](https://www.synthboard.ai/docs/webhooks).

## Versioning

The API is served at `/api/v1`. Additive changes (new endpoints, new optional fields) ship continuously and are documented in the [changelog](https://www.synthboard.ai/docs/changelog). Breaking changes would ship as a new path version with an overlap window — the policy is documented at [/docs/versioning](https://www.synthboard.ai/docs/versioning).

## Related

- [Interactive OpenAPI reference](https://www.synthboard.ai/docs/api)
- [Webhooks](https://www.synthboard.ai/docs/webhooks)
- [Changelog](https://www.synthboard.ai/docs/changelog)
- [API versioning](https://www.synthboard.ai/docs/versioning)
- [MCP server (alternative transport)](https://www.synthboard.ai/mcp)

## How to cite this page

> SynthBoard API reference — https://www.synthboard.ai/docs/api

Site: https://www.synthboard.ai