Scan Site

POST /api/static/sites/scan

Trigger a new scan run for a Site you already own. Use this to re-check a site after remediation or on a schedule. Requires an API key with the read-and-scan scope.

Request

Headers:

x-api-key (required): Your Rafter security API key, scope read-and-scan
Content-Type: application/json

Body: Provide exactly one of projectId or url to identify the site. Optionally restrict the scan to specific sections.

{
  "projectId": "b1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

{
  "url": "https://example.com"
}

Fields:

Field	Type	Required	Description
`projectId`	string	One of `projectId`/`url`	The site’s id
`url`	string	One of `projectId`/`url`	The site’s URL (used to look up the site)
`sections`	array of strings	No	Restrict the scan to a subset of sections: `"flight"`, `"security"`, `"dns"`. Omit to scan all sections.

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: RFabc-your-api-key-here" \
  -d '{
    "projectId": "b1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "sections": ["security", "dns"]
  }' \
  https://rafter.so/api/static/sites/scan

Response

Success (200 OK):

{
  "run": {
    "id": "r_1a2b3c4d",
    "project_id": "b1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "user_id": "u_abc123",
    "status": "running",
    "started_at": "2026-07-24T00:00:00.000+00:00",
    "finished_at": null,
    "progress_total": 0,
    "progress_done": 0,
    "created_at": "2026-07-24T00:00:00.000+00:00",
    "updated_at": "2026-07-24T00:00:00.000+00:00"
  }
}

Error (400 Bad Request — missing or ambiguous identifier):

{
  "error": "Provide exactly one of projectId or url."
}

Error (401 Unauthorized):

{
  "error": "Invalid or inactive API key."
}

Error (403 Forbidden — wrong scope):

{
  "error": "API key does not have read-and-scan scope."
}

Error (403 Forbidden — run limit reached):

{
  "error": "You have reached your scan run limit for this billing period."
}

Error (404 Not Found — not owned or doesn’t exist):

{
  "error": "Site not found."
}

The 404 response is deliberately identical whether the site doesn’t exist or simply isn’t owned by your account — this avoids leaking which domains other accounts monitor.

Error (429 Too Many Requests):

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later.",
  "retryAfter": 30
}

Error (500 Internal Server Error):

{
  "error": "An unexpected error occurred."
}

Response Fields

Field	Type	Description
`run.id`	string	Unique identifier for the scan run
`run.project_id`	string	The site’s id
`run.user_id`	string	Owning user’s id
`run.status`	string	Run status
`run.started_at`	string \| null	ISO 8601 timestamp when the run started
`run.finished_at`	string \| null	ISO 8601 timestamp when the run finished
`run.progress_total`	integer	Total number of steps in the run
`run.progress_done`	integer	Number of steps completed so far
`run.created_at`	string	ISO 8601 timestamp when the run was created
`run.updated_at`	string	ISO 8601 timestamp when the run was last updated

Rate Limiting

The API implements rate limiting to ensure fair usage:

Rate Limit: 100 requests per minute per IP address
Quota: Based on your subscription plan

Examples

JavaScript

const response = await fetch('https://rafter.so/api/static/sites/scan', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'RFabc-your-api-key-here'
  },
  body: JSON.stringify({ projectId: 'b1b2c3d4-e5f6-7890-abcd-ef1234567890' })
});

const data = await response.json();
console.log(`Run ID: ${data.run.id}`);

Python

import requests

response = requests.post(
    'https://rafter.so/api/static/sites/scan',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'RFabc-your-api-key-here'
    },
    json={'projectId': 'b1b2c3d4-e5f6-7890-abcd-ef1234567890'}
)

data = response.json()
print(f"Run ID: {data['run']['id']}")

Next Steps

Poll the Get Site endpoint with the site’s id to watch the run’s status and see the resulting findings summary once it completes.

API documentation

Endpoints

POST /api/static/sites/scan

Request

Example Request

Response

Response Fields

Rate Limiting

Examples

JavaScript

Python

Next Steps

​POST /api/static/sites/scan

​Request

​Example Request

​Response

​Response Fields

​Rate Limiting

​Examples

​JavaScript

​Python

​Next Steps

POST /api/static/sites/scan

Request

Example Request

Response

Response Fields

Rate Limiting

Examples

JavaScript

Python

Next Steps