API

Boarbs exposes a REST/OpenAPI explorer at /api/docs.

/api/docs is the source of truth for real endpoints, request shapes, and schemas.

This page is only the orientation layer around that.

If you want the authoritative endpoint reference, open the explorer first:

• Open API Docs

That explorer is useful, but it is not the whole integration story.

Start Here

Use this rule:

• use /api/docs when you need the real endpoint-level reference
• use this page when you need to understand auth, surface area, and product-level integration choices

What the API Explorer Covers

The public explorer currently covers these resource groups:

• boards
• posts
• comments
• statuses
• tags
• roadmaps
• votes

Those are the main product objects most teams need for imports, syncs, and custom workflows.

What the Explorer Does Not Cover

Some important integration surfaces exist outside the public explorer:

• embed session creation
• API key management
• portal auth and portal user flows
• payments and admin internals
• the RPC surface used by the CLI

So if you are looking for a route and cannot find it in /api/docs, that does not always mean the capability does not exist.

Webhooks

Starter and Pro organizations can configure one outbound webhook in Settings → API. Boarbs sends an HTTPS POST for:

• post.created
• comment.created (public and internal comments)
• post.status_changed

The request body has this envelope:

{
  "id": "event-id",
  "type": "post.created",
  "createdAt": "2026-08-29T10:24:00.000Z",
  "data": {
    "post": {}
  }
}

Each delivery includes Webhook-Id, Webhook-Timestamp, and Webhook-Signature headers. The signature uses the secret shown when the endpoint is created or rotated:

import { createHmac, timingSafeEqual } from "node:crypto";

const signedContent = `${request.headers.get("webhook-id")}.${request.headers.get("webhook-timestamp")}.${rawBody}`;
const expected = createHmac("sha256", process.env.BOARBS_WEBHOOK_SECRET)
  .update(signedContent)
  .digest();
const signature = request.headers.get("webhook-signature") ?? "";
const provided = /^v1=[0-9a-f]{64}$/.test(signature)
  ? Buffer.from(signature.slice(3), "hex")
  : null;

const valid =
  provided?.length === expected.length &&
  timingSafeEqual(provided, expected);

Verify against the raw request body before parsing JSON, and reject timestamps outside your replay window. Return any 2xx response to acknowledge a delivery. Failed requests time out after 10 seconds and are retried three times with increasing delays.

REST Explorer vs CLI vs Embed

The Main Auth Models

Boarbs uses a few different auth patterns depending on the route:

API Keys

Create organization API keys in Settings → API.

The important split is:

For organization-scoped writes, the API key also needs to be scoped to the same organization you are targeting.

A Good Mental Model

Use this rule of thumb:

• use the explorer when you want to inspect schemas or test a REST endpoint quickly
• use the API when another backend or service needs to talk to Boarbs
• use the CLI when you want repeatable scripts without writing a custom client
• use embed when you want Boarbs to live inside your product

Good First API Workflows

The API is a strong fit for:

• importing posts into a private review board
• syncing statuses and tags from another system
• reading posts for reporting or dashboards
• building internal tooling around boards and roadmaps

If You Need Embed Sessions

Embed session creation exists, but it is not part of the public explorer right now.

For that flow, use Embed rather than expecting /api/docs to be the complete reference.

The same session token can log that person into the hosted portal. See Automatic Login.

Next Steps

• API Explorer — Inspect the current REST/OpenAPI surface
• MCP — Connect Cursor, Claude, ChatGPT, or another MCP client
• Embed — Set up server-created embed sessions
• CLI — Use the RPC-based terminal workflow
• Reference — Understand permissions, settings, and notifications before automating anything