API Documentation

Integrate PreShip scanning into your workflow with our REST API. Automate accessibility, security, and performance checks in your CI/CD pipeline.

Getting Started

The PreShip API is organized around REST. It accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

Base URL: https://api.preship.dev/api

Authentication

All API requests require a Bearer token in the Authorization header. You can generate API keys from your dashboard under Settings > API Keys.

Create a Scan

Start a new scan by sending a POST request with the target URL and desired checks.

POST /v1/scans

bash

curl -X POST https://api.preship.dev/api/scans \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.vercel.app",
    "checks": ["accessibility", "security", "performance"]
  }'

Scan Response

When the scan completes, you will receive a response with scores and violation counts.

json

{
  "id": "scan_abc123",
  "status": "completed",
  "url": "https://your-app.vercel.app",
  "score": 72,
  "accessibility": 58,
  "security": 89,
  "performance": 71,
  "violations": 23,
  "fixable": 18,
  "created_at": "2026-03-16T14:30:00Z",
  "completed_at": "2026-03-16T14:30:28Z"
}

Get Scan Details

Retrieve detailed results for a specific scan by its ID.

GET /v1/scans/:id

bash

curl https://api.preship.dev/api/scans/scan_abc123 \
  -H "Authorization: Bearer sk_live_..."

List Scans

Retrieve a paginated list of your scans.

GET /v1/scans

bash

curl "https://api.preship.dev/api/scans?limit=10&offset=0" \
  -H "Authorization: Bearer sk_live_..."

Webhooks

Configure a webhook URL in your dashboard to receive real-time notifications when scans complete.

json

// POST to your webhook URL
{
  "event": "scan.completed",
  "data": {
    "id": "scan_abc123",
    "score": 72,
    "violations": 23
  }
}

Rate Limits

API rate limits depend on your plan. Rate limit headers are included in every response.

Plan	Requests/min	Scans/month
Free	10	5
Pro	60	100
Team	120	500
Business	300	Unlimited

Error Codes

PreShip uses conventional HTTP response codes. Codes in the 2xx range indicate success, 4xx indicate client errors, and 5xx indicate server errors.

Code	Description
200	Success
201	Scan created successfully
400	Bad request - invalid parameters
401	Unauthorized - invalid or missing API key
403	Forbidden - insufficient permissions
404	Not found - scan or resource does not exist
429	Rate limit exceeded
500	Internal server error