# 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:

```text
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`. |