REST API Overview

Base URL

https://api.purgit.io/v1

The API is also accessible at:

https://purgit.io/api/v1

Both endpoints are functionally identical. Use whichever fits your infrastructure.

Authentication

All API requests require a Bearer token. Pass your API key in the Authorization header:

Authorization: Bearer purgit_live_xxxxxxxxxxxxxxxxxxxx

Getting an API Key

Sign in to your Purgit dashboard at purgit.io/dashboard.
Navigate to Settings > API Keys.
Click Create API Key, give it a name, and copy the key.

API keys are shown only once at creation time. Store them securely (e.g., in environment variables or a secrets manager).

Key Formats

| Prefix | Environment | Usage | |--------|-------------|-------| | purgit_live_* | Production | Real scans, counted against your quota | | purgit_test_* | Sandbox | For development and testing; files are processed but not counted |

Rate Limits

Rate limits depend on your plan tier:

| Tier | Requests/day | Requests/minute | Max file size | |------|-------------|-----------------|---------------| | Free | 10 | 2 | 10 MB | | Pro | 1,000 | 60 | 200 MB | | Team | 10,000 | 300 | 500 MB |

When you exceed a rate limit, the API returns HTTP 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

Rate limit status is included in every response via headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1709769600

Request Format

File uploads: Use multipart/form-data with the file in a field named file.
Other requests: Use application/json for request bodies.
Query parameters: Used for filtering and pagination on GET endpoints.

Response Format

All responses return application/json, except for file download endpoints which return the binary file with appropriate Content-Type and Content-Disposition headers.

Success Response

{
  "data": { ... },
  "requestId": "req_01HX7K9M..."
}

Error Response

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "requestId": "req_01HX7K9M..."
}

The requestId is included in every response for support and debugging purposes.

Error Codes

| HTTP Status | Code | Description | |-------------|------|-------------| | 400 | INVALID_REQUEST | Malformed request or missing required fields | | 401 | UNAUTHORIZED | Missing or invalid API key | | 403 | FORBIDDEN | Valid key but insufficient permissions | | 404 | NOT_FOUND | Resource not found | | 413 | FILE_TOO_LARGE | File exceeds your plan's size limit | | 415 | UNSUPPORTED_FORMAT | File format not supported | | 422 | POLICY_NOT_FOUND | Specified policy does not exist | | 429 | RATE_LIMITED | Too many requests; check Retry-After header | | 500 | INTERNAL_ERROR | Server error; retry or contact support |

API Versioning

The current stable version is v1. The version is included in the URL path (/v1/).

Versioning policy:

Breaking changes are only introduced in new major versions (e.g., /v2/).
Existing versions receive a minimum 12-month deprecation notice before being retired.
Non-breaking additions (new fields, new endpoints) may be added to the current version at any time.

CORS

The API supports CORS for browser-based integrations. Allowed origins are configurable per API key in the dashboard.

Next Steps

API Reference — Full endpoint documentation with curl examples.
Integrations — Node.js, Python, and GitHub Actions examples.