API Reference
Integrate ShipCheck scans into your CI/CD pipeline, deploy scripts, or custom tooling. The v1 API lets you trigger scans, poll for completion, retrieve full reports programmatically, and fetch the latest Skills Pack download.
General scan/report API access requires a Pro plan. Skills Pack download keys are available from Settings → API Keys on Builder+ plans.
Authentication
Authenticated endpoints use a bearer API key sent in the Authorization header. Keys are prefixed with sc_ and can be created from your dashboard settings. General scan/report keys remain Pro-only, while the Skills Pack download route accepts a scoped download key on Builder+.
Header format
Authorization: Bearer sc_your_api_key_here
Keep your API key secret. If compromised, revoke it immediately from Settings and generate a new one.
Base URL
https://shipcheckhq.com
All endpoint paths in this documentation are relative to this base URL.
Quick Start
Run a complete scan in four steps:
1. List your verified sites
curl -s https://shipcheckhq.com/api/v1/sites \ -H "Authorization: Bearer sc_your_key"
2. Trigger a scan
curl -s -X POST https://shipcheckhq.com/api/v1/scans \
-H "Authorization: Bearer sc_your_key" \
-H "Content-Type: application/json" \
-d '{"targetUrl": "https://yoursite.com", "mode": "DEEP"}'The response includes a scan.id — save it for the next steps.
3. Wait for completion
curl -s https://shipcheckhq.com/api/v1/scans/SCAN_ID/wait?timeoutMs=120000 \ -H "Authorization: Bearer sc_your_key"
This blocks until the scan finishes or the timeout expires.
4. Fetch the report
# Full JSON report curl -s https://shipcheckhq.com/api/v1/scans/SCAN_ID/report \ -H "Authorization: Bearer sc_your_key" # AI-readable markdown export curl -s https://shipcheckhq.com/api/v1/scans/SCAN_ID/export/ai \ -H "Authorization: Bearer sc_your_key"
/api/v1/sites
List all verified sites belonging to the authenticated user.
Response
200 OK
{
"sites": [
{
"id": "clx...",
"url": "https://yoursite.com",
"displayName": "My App",
"scanProfile": "LIVE_SAAS",
"verificationStatus": "VERIFIED",
"createdAt": "2026-02-20T10:30:00.000Z"
}
]
}Example
curl -s https://shipcheckhq.com/api/v1/sites \ -H "Authorization: Bearer sc_your_key"
/api/v1/scans
Trigger a new scan on a verified site. You can identify the site by siteId or targetUrl.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| siteId | string | No | ID of a verified site. Provide this OR targetUrl. |
| targetUrl | string | No | URL of a verified site. ShipCheck resolves it to the matching site. Provide this OR siteId. |
| mode | string | No | Scan mode: "STARTER" (default) or "DEEP". DEEP requires Builder plan or higher. |
Response
201 Created
{
"scan": {
"id": "clx...",
"status": "QUEUED",
"mode": "DEEP"
}
}Errors
400 — Neither siteId nor targetUrl provided
403 — DEEP mode on Free plan
404 — No verified site found for the given identifier
429 — Monthly scan limit exceeded
Example
curl -s -X POST https://shipcheckhq.com/api/v1/scans \
-H "Authorization: Bearer sc_your_key" \
-H "Content-Type: application/json" \
-d '{"targetUrl": "https://yoursite.com", "mode": "DEEP"}'/api/v1/scans
List recent scans for the authenticated user, sorted by most recent first.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | number | No | Max results to return (default: 20, max: 100). |
Response
200 OK
{
"scans": [
{
"id": "clx...",
"targetUrl": "https://yoursite.com",
"mode": "DEEP",
"status": "COMPLETE",
"overallGrade": "B+",
"totalFindings": 5,
"criticalFindings": 0,
"highFindings": 1,
"mediumFindings": 2,
"lowFindings": 2,
"gateResult": { "passed": false, "reason": "1 HIGH finding" },
"queuedAt": "2026-03-01T10:00:00.000Z",
"completedAt": "2026-03-01T10:02:30.000Z"
}
]
}Example
curl -s "https://shipcheckhq.com/api/v1/scans?limit=5" \ -H "Authorization: Bearer sc_your_key"
/api/v1/scans/{id}/wait
Block until a scan reaches a terminal state (COMPLETE, FAILED, or CANCELED) or the timeout expires. Use this instead of polling GET /api/v1/scans in a loop.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| timeoutMs | number | No | Max time to wait in milliseconds (default: 120000, max: 600000). |
Response
Returns the scan object with its current status. If the timeout expires before the scan completes, the response still returns HTTP 200 with the current (non-terminal) status.
200 OK
{
"id": "clx...",
"status": "COMPLETE",
"targetUrl": "https://yoursite.com",
"mode": "DEEP",
"overallGrade": "B+",
"totalFindings": 5,
"criticalFindings": 0,
"highFindings": 1,
"mediumFindings": 2,
"lowFindings": 2,
"gateResult": { "passed": false, "reason": "1 HIGH finding" },
"completedAt": "2026-03-01T10:02:30.000Z",
"durationMs": 150000
}Example
curl -s "https://shipcheckhq.com/api/v1/scans/SCAN_ID/wait?timeoutMs=120000" \ -H "Authorization: Bearer sc_your_key"
/api/v1/scans/{id}/report
Fetch the full scan report as structured JSON. Includes every finding with details, security strengths, and the gate result. Only available after the scan completes.
Response
200 OK
{
"scan": {
"id": "clx...",
"targetUrl": "https://yoursite.com",
"mode": "DEEP",
"status": "COMPLETE",
"overallGrade": "B+",
"completedAt": "2026-03-01T10:02:30.000Z",
"durationMs": 150000
},
"counts": {
"total": 5,
"critical": 0,
"high": 1,
"medium": 2,
"low": 2
},
"findings": [
{
"id": "clx...",
"ruleId": "missing-csp",
"title": "Missing Content-Security-Policy header",
"severity": "HIGH",
"category": "Security",
"confidence": "high",
"description": "No CSP header found on...",
"remediation": "Add a Content-Security-Policy...",
"evidence": { "items": [...] },
"fingerprint": "abc123...",
"detectionType": "RUNTIME",
"status": "ACTIVE"
}
],
"findingsBySeverity": {
"critical": [],
"high": [...],
"medium": [...],
"low": [...]
},
"strengths": [
{
"id": "clx...",
"title": "HTTPS Enforced",
"description": "All traffic redirects to HTTPS.",
"status": "pass"
}
],
"gateResult": {
"passed": false,
"reason": "1 HIGH finding"
}
}Errors
404 — Scan not found
403 — Scan belongs to another user
409 — Scan is not yet complete (still QUEUED or RUNNING)
Example
curl -s https://shipcheckhq.com/api/v1/scans/SCAN_ID/report \ -H "Authorization: Bearer sc_your_key"
/api/v1/scans/{id}/export/ai
Download the scan report as AI-readable markdown. This format is optimized for pasting into AI coding assistants (Cursor, Claude, ChatGPT) to get actionable remediation guidance.
Response
Returns Content-Type: text/markdown with the full report as a markdown document.
Errors
404 — Scan not found or no export available
403 — Scan belongs to another user
409 — Scan is not yet complete
Example
curl -s https://shipcheckhq.com/api/v1/scans/SCAN_ID/export/ai \ -H "Authorization: Bearer sc_your_key" \ -o report.md
/api/v1/skills-pack/download
Download the latest ShipCheck Skills Pack zip. Browser users can download from the dashboard with a valid session. Terminal agents can authenticate with a scoped Skills Pack download key created in Settings.
Builder, Pro, and Enterprise session users can download from the dashboard. A bearer key must be scoped for Skills Pack downloads — general scan/report API keys will not work here.
Response
Returns Content-Type: application/zip with the latest Skills Pack archive as an attachment.
Errors
401 — Missing, invalid, or wrong-scope API key when no valid session exists
403 — Logged-in user is on a plan below Builder
404 — Latest Skills Pack zip is unavailable on the server
Example
curl -sL -H "Authorization: Bearer $SKILLS_PACK_API_KEY" \ "https://shipcheckhq.com/api/v1/skills-pack/download" -o skills-pack-latest.zip
/api/v1/skills-pack/check
Public — no authentication required
Check whether the installed Skills Pack version is up to date. Returns the latest available version, release date, and a changelog of all versions newer than the installed one. This endpoint is designed for AI coding agents to call programmatically.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| version | string | Yes | The currently installed Skills Pack version (e.g. "2.0.0-v9"). Use "0.0.0" to get all versions. |
Response
200 OK
{
"installed": "2.0.0-v8",
"latest": "2.0.0-v9",
"updateAvailable": true,
"released": "2026-03-01",
"url": "https://shipcheckhq.com/skills-pack",
"changelog": [
{
"version": "2.0.0-v9",
"date": "2026-03-01",
"highlights": [
"Runtime-agnostic deploy script",
"Skills Pack version check API"
]
}
]
}Errors
400 — Missing required query parameter: version
Example
curl -s "https://shipcheckhq.com/api/v1/skills-pack/check?version=2.0.0-v8"
Error Codes
All error responses return a JSON object with an error field describing the issue.
| Status | Meaning |
|---|---|
| 400 | Bad request — missing or invalid parameters |
| 401 | Unauthorized — missing or invalid API key |
| 403 | Forbidden — resource belongs to another user, or plan restriction |
| 404 | Not found — resource does not exist |
| 409 | Conflict — scan is not yet complete (for /report and /export/ai) |
| 429 | Rate limited — monthly scan quota exceeded |
Error response format
{
"error": "Description of what went wrong"
}Rate Limits
Scan creation is limited by your plan tier. These limits apply per calendar month.
| Plan | Scans / Month | API Access |
|---|---|---|
| Free | 5 | No |
| Builder | 30 | No |
| Pro | Unlimited | Yes |
Read-only endpoints (list sites, list scans, report, export, wait) are not rate-limited beyond standard infrastructure protections.
Scan Modes
STARTER
Passive security checks — header analysis, transport security, cookie configuration, SEO, and performance. Available on all plans. Completes in under a minute.
DEEP
Everything in STARTER plus active security testing — authentication probing, payment flow analysis, database version posture, and broader crawling. Requires Builder plan or higher. Takes 2–5 minutes depending on site size.