Reference
API notes
The HTTP API behind the Forseti dashboard: how it authenticates, how errors look, and the routes for repos, policies, reviews, spend and team.
Everything the dashboard does goes through a JSON API on the same origin, under /api. These notes are for teams who want to script against it or understand what the app sends.
Conventions
- JSON in and out. Sign-in, sessions and sign-out live under
/api/auth/*. - Every request acts on your active workspace, taken from your membership on the server, never from the request. Switch with
POST /api/me/active-org. - Roles: owner and admin manage repos, policies, settings, team and the audit log; billing (with owners and admins) manages caps and top-ups; members can read, trigger reviews and give feedback on findings.
- Every change is written to the audit log.
Errors
| Status | Body | Meaning |
|---|---|---|
400 | { error: "invalid_input", field, message } | A field failed validation |
401 | { error: "unauthorized" } | No valid session |
403 | { error: "forbidden", need: [...] } | Your role cannot do this; need lists the roles that can |
409 | { error: "no_workspace" } | You are not in a workspace yet |
429 | Rate limited; slow down and retry |
You and your workspace
| Method | Path | Does | Role |
|---|---|---|---|
GET | /api/me | You, your workspaces, the active one, and your GitHub installations | Signed in |
POST | /api/me/active-org | Switch the active workspace | Signed in |
GET | /api/github/install-url | Link to install the GitHub App | Signed in |
POST | /api/github/claim | Link an installation you can reach to a workspace | Signed in |
POST | /api/github/resync | Re-read repositories from GitHub | Owner, admin |
POST | /api/workspaces/:id/join | Join a workspace your GitHub organisation uses | Signed in |
DELETE | /api/workspaces/:id | Delete a workspace (confirm by name) | Owner |
Repositories, policies and estimates
| Method | Path | Does | Role |
|---|---|---|---|
GET | /api/repos | Repos with enabled state, branch targeting, depth per branch, config source and 30-day spend | Any member |
PATCH | /api/repos/:id | Enable, branch mode, branches, depth per branch, dimensions | Owner, admin |
POST | /api/repos/bulk | The same for many repos, or all of them | Owner, admin |
GET | /api/repos/:id/branches | Live branch list from GitHub | Any member |
GET | /api/policies | Workspace defaults, locks and policy rules | Any member |
PUT | /api/policies | Replace defaults, locks and rules | Owner, admin |
POST | /api/policies/preview | Monthly impact of proposed policies, from the last 30 days of PRs | Owner, admin |
POST | /api/estimate | Price and time estimate for a depth, dimensions and PR size | Any member |
GET | /api/packs | Built-in and custom domain packs | Any member |
POST | /api/packs/custom | Create a custom pack | Owner, admin |
DELETE | /api/packs/custom/:name | Delete a custom pack | Owner, admin |
{ "depth": "deep", "lines": 420, "files": 9 }
→ { "creditsP50": …, "creditsP90": …, "gbpP50": …, "etaSecondsP50": … }Reviews and findings
| Method | Path | Does | Role |
|---|---|---|---|
GET | /api/reviews | Review feed; filter by repo, status, depth and verdict; cursor paging | Any member |
GET | /api/reviews/:id | One review: files, findings with evidence, timeline per stage, coverage, cost | Any member |
POST | /api/reviews | Start a review of a PR at a depth | Any member |
POST | /api/reviews/:id/post | Post a review that was held for your approval | Any member |
POST | /api/findings/:id/feedback | Dismiss, accept or reopen a finding, with a reason | Any member |
POST | /api/reviews/:id/request-review | Ask suggested people to review on GitHub | Any member |
POST | /api/reviews/:id/ask | Ask a question about the PR; streamed answer with file:line citations | Any member |
GET | /api/reviews/:id/chat | The questions and answers so far | Any member |
GET | /api/reviews/:id/stream | Live events for one review (server-sent events) | Any member |
GET | /api/events | Live events for the workspace (server-sent events) | Any member |
Feedback reasons are not_useful, incorrect, wont_fix and other. “Not useful here” can teach Forseti to stop raising that category or that exact finding; “incorrect” credits back the finding's share of the cost. Review streams send stage, finding, posted and done events. A PR patch shown in a review is fetched from GitHub on request, never stored.
Asking about a PR is metered as a small charge, at least one credit per question, and limited to 20 questions per person per hour.
Team memory, quality and import
| Method | Path | Does | Role |
|---|---|---|---|
GET | /api/learnings | Team rules and suppressions | Any member |
POST | /api/learnings | Add a rule | Owner, admin |
PATCH | /api/learnings/:id | Switch on or off, edit | Owner, admin |
DELETE | /api/learnings/:id | Delete | Owner, admin |
GET | /api/learnings/export | As a ready .forseti/rules.md (format=md) or JSON | Any member |
GET | /api/quality | Precision by repo, category and author, noise per PR, trend | Any member |
GET | /api/quality/noise-budget | Current noise budget | Any member |
PUT | /api/quality/noise-budget | Change the noise budget | Owner, admin |
POST | /api/import/preview | Map pasted files, or scan repos, into a preview | Owner, admin |
POST | /api/import/apply | Apply a preview, once | Owner, admin |
GET | /api/export | Policies and rules as JSON, .forseti.yaml (format=yaml) or rules.md (format=rules) | Any member |
Spend, insights and team
| Method | Path | Does | Role |
|---|---|---|---|
GET | /api/spend | Balance, month spend against cap, forecast, by repo and developer, ledger | Any member |
PUT | /api/spend/caps | Per-PR, per-repo and workspace caps, and what happens at a cap | Owner, admin, billing |
POST | /api/spend/topup | Start a top-up checkout | Owner, admin, billing |
GET | /api/spend/forecast | Forecast from recent history, per repo | Any member |
GET | /api/spend/ceilings | Monthly ceilings per developer, team or repo | Any member |
POST | /api/spend/ceilings | Add a ceiling | Owner, admin, billing |
DELETE | /api/spend/ceilings/:id | Remove a ceiling | Owner, admin, billing |
GET | /api/teams | Teams used for ceilings | Any member |
GET | /api/insights | Acceptance rate, time to first review, bugs caught, spend per merged PR | Any member |
GET | /api/insights/roi | Cost per bug caught | Any member |
GET | /api/readiness | Merge readiness of open PRs | Any member |
POST | /api/release-notes | Draft release notes for merged PRs between two refs | Any member |
GET | /api/team | Members and pending invites | Any member |
POST | /api/team/invite | Create a single-use invite link | Owner, admin |
PATCH | /api/team/:userId | Change a member's role | Owner, admin |
GET | /api/settings | Workspace settings and the GitHub permission checklist | Any member |
PATCH | /api/settings | Name, auto-enable new repos, snippet storage, retention | Owner, admin |
GET | /api/audit | Audit log, paged | Owner, admin |
GET | /api/integrations | Connections and their status | Any member |
PUT | /api/integrations/:kind | Connect or update an integration | Owner, admin |
POST | /api/integrations/:kind/test | Test a connection | Owner, admin |
Inbound webhooks
GitHub delivers events to POST /webhooks/github. The signature is checked on the raw body (401 if it fails), the delivery is recorded and queued in one transaction, and the endpoint answers 202 at once. The review runs on a worker, so a slow model never delays GitHub.
Payments use POST /api/stripe/webhook, also signature-checked; each checkout grants its credits once.