# SynthBoard REST API

> Run a SynthBoard session from any HTTP client. Embed the boardroom in your own product, agent framework, or workflow. Full session lifecycle, interactive controls, shares, integrations, and webhooks. Available on Ultra tier and Enterprise.

**Canonical URL:** https://www.synthboard.ai/api  
**Markdown source:** https://www.synthboard.ai/api.md  
**Base URL:** https://www.synthboard.ai/api  
**Interactive reference:** https://www.synthboard.ai/docs/api  
**Auth:** Bearer token

## What you can do

- **Start sessions** — choose a mode (Boardroom, Idea Lab, Lightning Round, The Arena, Shark Tank, Command Center, War Room, Deep Dive, Crystal Ball, Research Lab) and a Synth lineup (2–12 from the 24-Synth library).
- **Continue, fork, archive, cancel, delete** — full session lifecycle.
- **Send messages** — interrupt a running session, ask follow-ups, send specific Synths back to debate harder.
- **Pull live summary** — server-streamed cross-round synthesis.
- **Capture decisions** — record explicit decisions against a session for later outcome inference.
- **Generate shares** — public or password-protected share links for any session.
- **Execute actions** — when a session yields an action recommendation, execute it against connected tools with explicit approval.
- **Webhooks** — subscribe to session.complete, outcomes.ready, action.executed.

## Why this exists

Most teams using SynthBoard do so via the web app or MCP. The REST API exists for:

1. **Embedded boardrooms** — you ship your own product and want decision intelligence inside it.
2. **Agent frameworks** — you build with LangGraph, CrewAI, AutoGen, or custom orchestration and want a board your agent can convene mid-flow.
3. **Workflow automation** — you trigger boardrooms from Zapier, n8n, Make, or your own internal job queue.
4. **Custom dashboards** — you display SynthBoard outcomes inside your existing decision dashboard.

If you live in Claude Desktop, Cursor, or ChatGPT, use the [MCP server](https://www.synthboard.ai/mcp) instead — same backend, fewer lines of glue code.

## Auth

```http
Authorization: Bearer sk_synth_live_...
```

Generate keys from **MCP & API** → **API Keys** in the sidebar. Keys are scoped per environment (live/test) and per workspace. Rotate any time; old keys remain valid for 24 hours after rotation to allow zero-downtime cutover.

## A 30-second example

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

{
  "mode": "stress_test",
  "title": "Should we 2x our enterprise price?",
  "context": "We are SynthBoard. Currently $50/mo for Max tier. Considering moving Max to $99 and creating a new Ultra at $199. Pre-revenue, but Max users tell us we are underpriced.",
  "synths": ["the-cfo", "the-customer-champion", "the-skeptic", "the-strategist", "the-growth-hacker"],
  "rounds": 3
}
```

You get back a `session_id`. Stream events from `GET /api/v1/sessions/{id}/events` or pull the final synthesis from `GET /api/v1/sessions/{id}/outcomes` once `status === "complete"`.

## Rate limits

- **Ultra tier:** 60 session starts per minute, 600 messages per minute.
- **Enterprise:** custom limits per contract.
- **Bursting:** standard, with 429 responses including `Retry-After`.

## Idempotency

Every write endpoint accepts an `Idempotency-Key` header. Duplicate keys within 24 hours return the original response — safe to retry on network errors.

## Webhooks

Subscribe a URL from **MCP & API** → **Webhooks**. Events are signed (HMAC-SHA256) so you can verify source.

```
session.created
session.complete
session.cancelled
outcomes.ready
action.executed
action.undone
share.created
share.viewed
```

Per-event payloads: see [https://www.synthboard.ai/docs/webhooks](https://www.synthboard.ai/docs/webhooks).

## Errors

Standard problem-details format ([RFC 7807](https://tools.ietf.org/html/rfc7807)):

```json
{
  "type": "https://www.synthboard.ai/errors/insufficient-credits",
  "title": "Insufficient credits",
  "status": 402,
  "detail": "Estimated session cost is 800 credits. Account balance is 320.",
  "session_estimate_credits": 800,
  "balance_credits": 320,
  "topup_url": "https://www.synthboard.ai/pricing"
}
```

## Pricing

API access is included in the **Ultra** tier ($99/month) and Enterprise contracts. Sessions run via API draw from the same credit pool as web and MCP sessions. No per-call API surcharge.

## Status and uptime

- **Status page:** https://status.synthboard.ai (when published)
- **Target SLA:** 99.9% on the API, 99.5% on long-running session orchestration.
- **Multi-region failover** between US-East and EU-West.

## Further reading

- [Interactive OpenAPI reference](https://www.synthboard.ai/docs/api)
- [Webhooks](https://www.synthboard.ai/docs/webhooks)
- [MCP server (alternative interface)](https://www.synthboard.ai/mcp)
- [Integrations](https://www.synthboard.ai/docs/integrations)
- [Native adapters: Zapier, n8n, Make, Pipedream](https://www.synthboard.ai/docs/adapters)

## How to cite this page

> SynthBoard REST API — run the AI boardroom from any HTTP client. https://www.synthboard.ai/api

Site: https://www.synthboard.ai