Ship Safe

API reference

Everything in the Ship Safe dashboard is available over REST. Generate an API key in Settings → API keys and authenticate every request with it.

curl https://api.shipsafe.pro/v1/scans \
  -H "Authorization: Bearer $SHIPSAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"repoId": "your-repo-id"}'

Machine-readable spec: the full OpenAPI 3.0 document lives at api.shipsafe.pro/v1/openapi.json — import it into Postman, Insomnia, or an OpenAPI client generator.

Scans

Trigger scans, poll status, and re-run or cancel them.

POST/v1/scans
GET/v1/scans
GET/v1/scans/{id}
GET/v1/scans/{id}/runs
POST/v1/scans/upload
POST/v1/scans/{id}/rescan
POST/v1/scans/{id}/regrade
POST/v1/scans/{id}/cancel

Findings

Everything the engines surfaced, mapped to OWASP, CWE, and SOC 2.

GET/v1/scans/{id}/findings
GET/v1/findings/{id}
PATCH/v1/findings/{id}

Fixes

AI-generated fix pull requests (paid tiers).

POST/v1/findings/{id}/fixes
GET/v1/fixes/{id}

Reports

SOC 2 evidence packs, executive summaries, and full technical PDFs.

POST/v1/scans/{id}/reports
GET/v1/reports/{id}

Repos

Connect repositories and manage watch mode.

GET/v1/repos
POST/v1/repos
PATCH/v1/repos/{id}
DELETE/v1/repos/{id}
GET/v1/repos/{id}/trends

API keys & badges

Programmatic access and public README badges.

GET/v1/api-keys
POST/v1/api-keys
DELETE/v1/api-keys/{id}
GET/v1/badges/{owner}--{repo}

Conventions

  • Responses wrap payloads in { "data": … }; errors return { "error": { "code", "message" } }.
  • Rate limit: 600 requests/minute per key, with tighter caps on expensive routes (scan triggers, report generation).
  • Quota errors use HTTP 402 with an explanation of the plan limit.
  • List endpoints paginate with cursors (scans) or page numbers (findings).