# API Reference

> Every endpoint, schema, and webhook event SynthBoard exposes. 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  
**Auth:** `Authorization: Bearer sk_synth_live_...`  
**Available on:** Ultra tier and Enterprise.

## Auth

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

Generate keys from **MCP & API** → **API Keys** in the sidebar. Per-environment keys (`sk_synth_live_` and `sk_synth_test_`). Rotate any time; old keys remain valid for 24 hours after rotation.

## Resources

- **`/api/v1/sessions`** — full session lifecycle (start, get, list, continue, fork, archive, cancel, delete, update meta).
- **`/api/v1/sessions/{id}/events`** — server-sent events stream of board activity.
- **`/api/v1/sessions/{id}/outcomes`** — final synthesis after a session completes.
- **`/api/v1/sessions/{id}/plan`** — pre-flight plan before execution.
- **`/api/v1/sessions/{id}/messages`** — send a follow-up message into a running session.
- **`/api/v1/sessions/{id}/decisions`** — capture an explicit decision against the session.
- **`/api/v1/sessions/{id}/exports`** — export session in markdown, PDF, or JSON.
- **`/api/v1/sessions/{id}/shares`** — generate / list / revoke share links.
- **`/api/integrations`** — list connected integrations.
- **`/api/synths`** — list available Synths in the user's library.
- **`/api/modes`** — list available session modes.
- **`/api/credits`** — current balance + recent usage.
- **`/api/webhooks`** — manage webhook subscriptions.

## A 30-second example

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

{
  "mode": "stress_test",
  "title": "Should we 2x our enterprise price?",
  "context": "Currently $50/mo for Max. Considering moving Max to $99 and creating a new Ultra at $199.",
  "synths": ["the-cfo", "the-customer-champion", "the-skeptic", "the-strategist", "the-growth-hacker"],
  "rounds": 3,
  "model_class": "premium"
}
```

Response:
```json
{
  "id": "ses_2c4d8e...",
  "status": "running",
  "estimated_cost_credits": 480,
  "events_url": "https://www.synthboard.ai/api/v1/sessions/ses_2c4d8e.../events",
  "outcomes_url": "https://www.synthboard.ai/api/v1/sessions/ses_2c4d8e.../outcomes"
}
```

## Idempotency

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

## Pagination

List endpoints (`/api/v1/sessions`, `/api/integrations`, etc.) use cursor pagination:

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

Response includes `next_cursor` (or `null` if no more).

## Errors

[RFC 7807](https://tools.ietf.org/html/rfc7807) Problem Details:

```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"
}
```

Common error types:
- `400 invalid-request` — schema validation
- `401 unauthorized` — missing/invalid token
- `402 insufficient-credits` — out of credits
- `403 tier-required` — feature requires higher tier
- `404 not-found`
- `409 conflict` — idempotency or state conflict
- `429 rate-limited` — includes `Retry-After`
- `500 internal-error`

## Rate limits

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

## Webhooks

Subscribe a URL from **MCP & API** → **Webhooks**. Events are signed with HMAC-SHA256 (header: `X-SynthBoard-Signature`). Verify on receipt.

Event names:
- `session.created`
- `session.complete`
- `session.cancelled`
- `outcomes.ready`
- `action.executed`
- `action.undone`
- `share.created`
- `share.viewed`
- `decision.captured`

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

## Streaming

`GET /api/v1/sessions/{id}/events` returns a server-sent events (SSE) stream. Events:

```
event: synth.message
data: {"synth": "the-strategist", "round": 1, "content": "..."}

event: round.complete
data: {"round": 1, "synthesis_preview": "..."}

event: session.complete
data: {"outcomes_url": "..."}
```

## Status codes

- `200 OK` — read success
- `201 Created` — resource created
- `202 Accepted` — write accepted, async processing started
- `204 No Content` — successful delete
- See errors above for failure codes

## Versioning

The API is currently v1, served at `/api/`. Breaking changes will move to `/api/v2/` with at least 6 months overlap. Non-breaking additive changes ship continuously.

The header `X-SynthBoard-API-Version: 2026-05-01` echoes the version the server processed your request as. Pin to a specific date by sending the header on requests.

## Related

- [Marketing API page](https://www.synthboard.ai/api)
- [Webhooks](https://www.synthboard.ai/docs/webhooks)
- [MCP server (alternative)](https://www.synthboard.ai/mcp)

## How to cite this page

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

Site: https://www.synthboard.ai