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.

Authentication

For MCP clients such as ChatGPT, Cursor, and Claude, OAuth is recommended. Connect to the hosted MCP URL, sign in, choose workspaces, and approve Read (default) or Read + Write. Write access is only available when requested by the client. See the MCP connection guide.

API keys are the alternative for CI, local configuration, and clients without OAuth. Create a workspace key under Settings → API and send it as Authorization: Bearer YOUR_BOARBS_API_KEY. Keys are restricted to their own workspace. OAuth bearer tokens are also accepted by the API's dual-auth procedures and follow their saved workspace grants and scopes. Current membership and role checks apply to both credentials.

Re-consent replaces workspace grants immediately, including for existing and refreshed tokens. Legacy OAuth connections without saved workspace grants keep access to the user's current workspaces; reconnect to restrict them explicitly.

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.

POST /api/embed/sessions also accepts optional company: { id?, name } and mrr: { amount, currency? } (default currency USD). Company and MRR are team-only and omitted from public responses. Customer context is synced once immediately after session creation and again on automatic login; embed requests do not repeat the sync. Supplied values replace existing workspace customer context; omitted values preserve it. A session-creation sync failure logs a generic message without customer data and still returns the session. Invalid values return 400. See the request fields and validation limits.

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

Submissions That Await Approval

When a board has submissionMode: PENDING, creating a post through the public API returns the created post with a non-null draftAt and draftSource: MODERATION. API keys and OAuth bearer tokens follow this setting even when their owner is a workspace member. Treat this response as a successful submission awaiting review, and show an approval confirmation instead of a public post link. Public reads hide pending posts; authenticated workspace members can review them in the workspace. The creator subscription and creation activity are retained, while public post.created notifications and webhooks wait for approval.

Unpublish a Public Post

Workspace members can call POST /posts/{id}/unpublish with organizationId, using the same session or read-write bearer permissions as POST /posts/{id}/approve. The post must currently be public on a public board and must not be deleted, spam, or merged. Non-members and credentials scoped to another workspace are denied; read-only credentials cannot unpublish.

The response contains the post with draftAt and draftSource: MODERATION. Public reads, lists, and counts hide it; workspace members and the signed-in author retain the existing pending-post access. Votes, comments, and subscriptions remain. Unpublishing sends no notifications or webhooks. Re-approve with POST /posts/{id}/approve to publish again without repeating post.created integration events. Previously unpublished posts are excluded from AI moderation, even after edits.

Comments That Await Approval

A board's commentMode is OPEN by default. With PENDING, comments created by non-members return a non-null pendingAt; the create request succeeds, but the comment is awaiting review. Verified workspace members publish immediately. Public comment lists, post responses, and counts exclude pending comments. The signed-in author may retrieve their own pending comments through the comments list; supplying an email or author ID is not proof of ownership.

Workspace members can call POST /comments/{id}/approve or POST /comments/{id}/reject with organizationId. Approval clears pendingAt and sends deferred public notifications once; rejection soft-deletes the comment. These endpoints verify membership in the comment's owning workspace. Only admins/owners can update commentMode through board settings.