Developer documentation

Pealboard is work management on GitHub Issues and Projects, with portals for the people who are not on GitHub. Everything a workspace member can do in the application, and everything a customer can do in a portal, a script or an agent can do through this API with the same credential and the same role.

GitHub is the system of record. Every issue, comment, label, milestone, project and project field value this API returns exists in GitHub first, and every write goes to GitHub before it goes anywhere else — so a write this API reports is a write GitHub accepted.

Base URL

https://api.pealboard.com

The full OpenAPI 3.1 document is at /openapi.json. It is what this reference is generated from and what rohan-sdk’s types are generated from, so a documented field and a served field cannot disagree.

Two bases under it

Base path	For	Resolved by
/v1/...	A workspace member, or a script or agent acting with their credential	X-Workspace-Id, or the workspace the credential belongs to
/portal/...	A signed-in portal customer	The host the request arrived on

/portal is not for integrators. A portal is a space at <slug>.pealboard.com for a customer without a GitHub account, and the API behind it resolves which portal from the domain the browser is already on. It has no concept of X-Workspace-Id and issues no API keys of its own. Building against Pealboard means building against /v1.

The three credentials

Credential	Where it comes from	Used by
A session cookie	Signing in to the application	The workspace application in a browser
A session token, Authorization: Bearer <token>	The same sign-in, held by a client that is not a browser	The mobile app
An API key, Authorization: Bearer pb_...	Settings → API keys in the application	Scripts, integrations and the MCP server

An API key is created by a workspace member, acts with that member’s role narrowed by whatever scopes were chosen, and is shown once in full — Pealboard stores only a SHA-256 digest of it. See Authentication for how to send one and for X-Workspace-Id, and API keys in the help documentation for creating and revoking one.

Three ways to call it

Surface	Address	For
REST API	https://api.pealboard.com	Anything that speaks HTTP
TypeScript SDK	@pealboard/sdk, installed from a private repository	TypeScript and JavaScript callers
MCP server	https://mcp.pealboard.com/mcp	Agents and assistants that speak the Model Context Protocol

All three are the same API. The SDK is a typed wrapper generated from the same OpenAPI document; the MCP server is a stateless Worker that forwards a caller’s own API key to /v1 and holds no state of its own. Neither can do anything the REST API cannot, and neither can do anything the credential’s role does not allow. See SDK and MCP.

What every response carries

A request id, on every response, success or failure:

X-Request-Id: 9a1c2e3f-...

Quote it in a support message. An id the caller supplies in the request is kept, so a trace that starts in a caller’s own logging stays one trace.

Every failure has the same shape:

{
  "error": {
    "code": "forbidden",
    "message": "Your role does not allow that.",
    "remedy": "This needs the admin role or above. An owner or admin can change yours.",
    "requestId": "9a1c2e3f-..."
  }
}

See Errors for every code, Pagination for cursors, and Idempotency for Idempotency-Key.

Two rules that explain the API’s behavior

1. GitHub is written first. A create or an update goes to GitHub, and only what GitHub returns is cached and returned to you. If GitHub refuses, you get GitHub’s refusal, and nothing changed on either side.
2. Authorization is declared per route, and every id is checked against the caller’s scope. An id that names something in another workspace answers 404, identical to an id that names nothing — no route confirms what exists elsewhere.

Where the rest of this is

• Authentication — credentials, scopes, X-Workspace-Id.
• Errors — the envelope and every code.
• Rate limits — the limits on this API, and GitHub’s own.
• Pagination — cursors and updated_since.
• Idempotency — Idempotency-Key on creates.
• GitHub — what the App reads and writes, and attribution.
• Webhooks — there are none outbound in v1; how to poll instead.
• API reference — every operation, generated from the OpenAPI document.
• SDK — the TypeScript client.
• MCP — connecting an agent.
• Changelog — what shipped and when, for the API.