API Reference

Integrate ShipReady audits into your CI/CD, dashboards, and AI agents. Base URL: https://shipready.app

Authentication

All API endpoints require a Bearer token in the Authorization header. Generate keys at Dashboard → API Keys (Agency plan required).

curl -H "Authorization: Bearer sk_live_..." https://shipready.app/api/v1/scan

Rate Limits

REST Endpoints

POST /api/v1/scan

Submit a URL for a ShipReady audit. Returns the scan ID immediately; poll GET /api/scan/:id for results.

Request body

{
  "url": "https://example.com",       // required
  "goal": "seo"                        // optional: seo | security | ai_visibility | full (default: full)
}

Response 200

{ "id": "7f3d9..." }

curl example

curl -X POST https://shipready.app/api/v1/scan \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","goal":"full"}'

GET /api/scan/:id

Poll scan status and retrieve results. No auth required for anonymous scans.

Response 200

{
  "id": "7f3d9...",
  "status": "done",           // pending | running | running_fast | running_deep | enriching | done | error
  "results": {
    "totalScore": 82,
    "performance": { "score": 91, "issues": [...] },
    "seo": { "score": 78, "issues": [...] },
    // ... security, mobile, ai_visibility, accessibility
  }
}

curl example

curl https://shipready.app/api/scan/7f3d9... \
  -H "Authorization: Bearer sk_live_..."

GET /api/badge/:domain

Returns an SVG badge with the domain's latest public score. Requires badge_enabled = true on the scan.

curl https://shipready.app/api/badge/example.com

Markdown embed

![ShipReady score](https://shipready.app/api/badge/example.com)

MCP JSON-RPC Tools

ShipReady exposes a JSON-RPC 2.0 MCP endpoint at POST /api/mcp. Use it with Claude Code, Cursor, or any MCP-compatible client to run audits from within your editor.

# Claude Code: add to settings.json under mcpServers
{
  "shipready": {
    "command": "npx",
    "args": ["mcp-client", "https://shipready.app/api/mcp"],
    "env": { "SHIPREADY_API_KEY": "sk_live_..." }
  }
}

Error Codes