Pealboard
Overview
Pealboard API 1.0.0
Section titled “Pealboard API 1.0.0”Work management on GitHub Issues and Projects, with portals for the people who are not on GitHub.
GitHub is the system of record. Every issue, comment, label, milestone, project and 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.
Reads come from Pealboard’s cache of GitHub and cost the installation nothing. Writes cost one GitHub round trip and are serialised per installation, so a bulk edit cannot race itself into a secondary rate limit.
Every response carries X-Request-Id. Every failure has the same shape: { error: { code, message, detail?, remedy?, requestId } }. Lists are cursor-paged: send nextCursor back as cursor. Creates accept Idempotency-Key, and a retry with the same key returns the first answer rather than making a second object.
Sign-in failures do not use that envelope, because they are browser redirects and not API calls. Better Auth’s endpoints under /auth and /portal/auth redirect a failed sign-in to the application’s own /auth/error?error=<code> — the workspace application for /auth, and the portal the request arrived on for /portal/auth. The client reads the error query parameter and says what to do about it. The values are Better Auth’s, not this API’s; the ones a person actually meets are email_not_found (a GitHub account with no address this App may read), account_not_linked, signup_disabled, please_restart_the_process (an expired or reused state) and unable_to_create_user. Treat an unrecognised value as a generic failure and offer the sign-in screen again.
Authentication
Section titled “Authentication”bearerAuth
Section titled “bearerAuth”A session token, or an API key beginning pb_. A browser sends the session cookie instead and needs no header. X-Workspace-Id names the workspace when the credential belongs to more than one.
Security scheme type: http