Reference

REST API

The routes behind the CLI and the MCP server, for scripts and CI.

Basics

The base URL is https://api.stableship.ai. Every request sends a token:

Authorization: Bearer sst_your_token

Requests and responses are JSON. Routes about one app take project (its id, from GET /api/v1/projects) or repo (owner/name) as a query parameter, or projectId or repo in a JSON body.

Errors

Errors are { "error": "…" } with one of these statuses:

Status	Meaning
400	The request is missing something or has a bad value.
401	The token is missing, wrong, revoked or expired.
402	A full audit cannot start: the app is not on a plan (`needs_plan`), or this month's audits are used (`no_audits_left`). The body has a `checkoutUrl` for a person to pay at; the audit then starts by itself.
403	The token lacks the scope this route needs.
404	Not found, or not visible to this token.
409	A full audit cannot start: no repository, no confirmed rules, or one is already running (`already_running`, with its `runId`).
429	Too many requests. Wait for the `retry-after` header's seconds.

Routes

Each route does what the MCP tool named beside it does.

Findings and fixes

Route	Scope	What it does
`GET /api/v1/projects`	read	Your apps, each with its repositories, latest verdict and counts of open and blocking findings. Tool: `list_projects`.
`GET /api/v1/findings`	read	An app's findings, blocking ones first. Filter by status, blocking only, or first seen since a time. Tool: `get_findings`.
`GET /api/v1/findings/:id/brief`	read	Everything needed to fix one finding: what is wrong, the rule it breaks, where to look, how to reproduce it, when it is done, and a ready prompt. Tool: `get_fix_brief`.
`GET /api/v1/findings/:id/explain`, `GET /api/v1/runs/:id/explain`	read	Why a finding blocks or does not, or why a run came out as it did. Tool: `explain_finding`.
`GET /api/v1/known-issues`	read	Accepted risks, false positives, won't-fix and in-progress items, and dismissed findings. Tool: `get_known_issues`.
`GET /api/v1/projects/:id/fix-plan`	read	Every open finding as ordered tasks, blocking first: STABLESHIP_FIXES.md. Tool: `get_fix_plan`.
`POST /api/v1/findings/:id/verify`	run	Run again the check that found a finding, on a branch or commit, to confirm a fix. Tool: `verify_fix`.

Checks and audits

Route	Scope	What it does
`POST /api/v1/checks`	run	Start a check of a pushed commit or branch, at a scope you choose or the one the change needs. Can be narrowed to one flow, kind of user or endpoint. Tool: `run_check`.
`GET /api/v1/runs/:id`	read	A run's status and verdict, whether it is done, and its findings. Tool: `get_run_status`.
`POST /api/v1/runs/:id/rerun`	run	Run a check again with the same scope, narrowing and commit. Tool: `rerun_gate`.
`POST /api/v1/audits`	run	Start a full audit of the default branch, from the app's monthly audits or a purchased one. Tool: `run_audit`.
`GET /api/v1/audits/status`	read	Whether a full audit is running or can start, without starting one. Tool: `get_audit_status`.
`GET /api/v1/audits/:id`	read	The run a full-audit request became, once it is scheduled.
`GET /api/v1/scope-policy`	read	The scope minimums and blocking policy, and the scope a check would pick for a set of paths. Tool: `get_scope_policy`.

Rules, notes and flows

Route	Scope	What it does
`GET /api/v1/rules`	read	The app's rules and critical flows, or only the rules that concern one file. Tool: `get_rules`.
`GET /api/v1/context`	read	The rules as sentences, the kinds of user, your product notes, and what the last private copy could not test. Tool: `get_context`.
`POST /api/v1/context/notes`	run	Add one lasting fact to the product notes. Tool: `add_context_note`.
`DELETE /api/v1/context/notes`	run	Take one product note out. Tool: `remove_context_note`.
`POST /api/v1/rules/proposals`	run	Suggest who may do what, for a person to accept, instead of changing access in code. Tool: `propose_rule`.
`POST /api/v1/flows`	run	Add something people do that every check clicks through. Tool: `add_flow`.
`GET /api/v1/repo-files`	read	The .gate files and the Stableship section of AGENTS.md, for your agent to commit. Tool: `get_repo_files`.

Reports and setup

Route	Scope	What it does
`GET /api/v1/projects/:id/report`, `GET /api/v1/runs/:id/report`	read	The audit report: verdict, steps, problems and what was not tested. Tool: `get_report`.
`GET /api/v1/projects/:id/launch-report`	read	The latest launch report. Tool: `get_launch_report`.
`GET /api/v1/setup`	read	The short block for CLAUDE.md or AGENTS.md that points your agent at the rules and the fix plan. Tool: `get_setup`.

Your account and app

Route	Scope	What it does
`GET /api/v1/whoami`	read	The workspace, the apps this connection can see, its scopes, and whose it is. Tool: `whoami`.
`GET /api/v1/next-steps`	read	The latest audit as a plan: how it went, what to fix first, and the one next step. Tool: `get_next_steps`.
`GET /api/v1/activity`	read	What changed recently and who did it. Tool: `get_activity`.
`GET /api/v1/app-map`	read	The pages each kind of user reached and how each went, the endpoints the checks called, and the outside services and personal data the app holds. Tool: `get_app_map`.
`GET /api/v1/compliance`	read	How the app maps to SOC 2, ISO 27001, GDPR, PCI DSS and more: what was proven, the gaps, and what to ask a professional. Tool: `get_compliance`.
`GET /api/v1/approvals/:id`	read	Whether a person approved an action, and whether Stableship carried it out. Tool: `get_approval`.

CI

Route	Scope	What it does
`GET /api/v1/checks/by-sha`	read	Whether a commit may deploy: the check for it, and Stableship's decision.
`GET /api/v1/projects/:id/findings.sarif`	read	Open findings, or one run's, as SARIF 2.1.0 for GitHub code scanning.

Actions (manage scope)

Route	Scope	What it does
`POST /api/v1/actions/triage_finding`	manage	Mark a finding a false positive, an accepted risk, fixed, or open again. Tool: `triage_finding`.
`POST /api/v1/actions/resume_held_audit`	manage	Start again an audit that was on hold because the private copy could not be built. Tool: `resume_held_audit`.
`POST /api/v1/actions/ship_anyway`	manage	Let a held release go out, with a reason that is kept in the activity log. Tool: `ship_anyway`.
`POST /api/v1/actions/decide_rule_suggestion`	manage	Accept or dismiss a rule suggestion. Tool: `decide_rule_suggestion`.
`POST /api/v1/actions/set_policy`	manage	Change a policy: what blocks, what happens when Stableship cannot finish, the audit schedule, notifications. Tool: `set_policy`.
`POST /api/v1/actions/set_autonomy`	manage	Change how much Stableship does on its own: hands on, guided or autopilot. Tool: `set_autonomy`.
`POST /api/v1/actions/set_role`	manage	Add or rename a kind of user. Tool: `set_role`.
`POST /api/v1/actions/set_role_reach`	manage	Set whether a kind of user reaches every record or only related ones. Tool: `set_role_reach`.
`POST /api/v1/actions/remove_role`	manage	Remove a kind of user, so checks stop testing as it. Tool: `remove_role`.
`POST /api/v1/actions/remove_rule`	manage	Remove a rule, so checks stop testing it. Removing an access or money rule needs the approvers the policy names. Tool: `remove_rule`.
`POST /api/v1/actions/share_report`	manage	Make an audit report readable by anyone with its link. Tool: `share_report`.
`POST /api/v1/actions/unshare_report`	manage	Stop sharing an audit report. Tool: `unshare_report`.
`POST /api/v1/actions/reanalyze`	manage	Read the app again: its pages, data and flows. Tool: `reanalyze`.
`POST /api/v1/actions/set_notifications`	manage	Choose which emails you get. Tool: `set_notifications`.
`POST /api/v1/actions/create_app`	manage	Add an app from one or more repositories. Tool: `create_app`.
`POST /api/v1/actions/link_repo`	manage	Add a repository to an app. Tool: `link_repo`.
`POST /api/v1/actions/set_service`	manage	Correct how one of the app's services is built and started. Tool: `set_service`.

For your coding agent: this page as Markdown