API Documentation

The CodeSec API is organized around REST. It has predictable resource-oriented URLs, returns JSON, and uses standard HTTP verbs and status codes.

Authentication

Authenticate requests with your secret API key, sent as a bearer token in the Authorization header. Create and manage keys on the API Keys page. All requests must be made over HTTPS.

Authorization: Bearer YOUR_API_KEY

Base URL

All endpoints are relative to the production base URL:

https://api.codesec.me

Errors

CodeSec uses conventional HTTP status codes. Codes in the 2xx range indicate success, 4xx indicate a client error, and 5xx indicate a server error. Error responses include a machine-readable error code and a human-readable message.

{
  "error": "unauthorized",
  "message": "Invalid API key"
}

400	Bad request — invalid parameters
401	Unauthorized — missing or invalid API key
404	Not found — the resource does not exist
429	Too many requests — rate limit exceeded
500	Server error — something went wrong on our end

Endpoints

POST/v1/scans

Create a scan

Queues a new security scan for the given target. Returns immediately with a scan id you can poll for status and results.

Request body

{
  "target": "https://example.com",
  "scan_type": "full"
}

Example request

curl -X POST https://api.codesec.me/v1/scans \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":"https://example.com","scan_type":"full"}'

Response

{
  "scan_id": "scan_123",
  "status": "queued"
}

GET/v1/scans/{scan_id}

Get scan status

Retrieves the current status and metadata for a scan.

Parameters

scan_id

path · string · required

The id returned when the scan was created.

Example request

curl -X GET https://api.codesec.me/v1/scans/{scan_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "scan_id": "scan_123",
  "status": "running",
  "target": "https://example.com",
  "progress": 42,
  "created_at": "2026-06-03T10:00:00Z"
}

GET/v1/scans/{scan_id}/results

Get scan results

Returns the findings discovered by a scan. Available incrementally while the scan runs and in full once it completes.

Parameters

`scan_id` path · string · required	The scan id.
`severity` query · string	Filter findings by minimum severity.One of: info, low, medium, high, critical

Example request

curl -X GET https://api.codesec.me/v1/scans/{scan_id}/results \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "scan_id": "scan_123",
  "status": "completed",
  "score": 87,
  "findings": [
    {
      "id": "fnd_1",
      "title": "Missing Content-Security-Policy header",
      "severity": "medium",
      "confidence": "high",
      "category": "headers"
    }
  ]
}

GET/v1/scans

List scans

Lists scans for the authenticated account, newest first.

Parameters

`limit` query · integer	Maximum number of scans to return (1–100).
`status` query · string	Filter by scan status.One of: queued, running, completed, failed

Example request

curl -X GET https://api.codesec.me/v1/scans \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "scan_id": "scan_123",
      "status": "completed"
    }
  ],
  "has_more": false
}

GET/v1/usage

Get usage

Returns the current billing period's usage and remaining quota for the authenticated account.

Example request

curl -X GET https://api.codesec.me/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "plan": "pro",
  "scans_used": 128,
  "scans_limit": 500,
  "period_start": "2026-06-01T00:00:00Z",
  "period_end": "2026-07-01T00:00:00Z"
}

Rate limits

Rate limits scale with your plan. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. Exceeding a limit returns 429 with a retry_after value.

Plan	Scans / month	Requests / min	Concurrent
Free	10	30	1
Pro	500	120	5
Business	5,000	600	20
Enterprise	Custom	Custom	Custom