Scan Endpoint
Submit a URL for scanning and receive a full Zeodyn Score™ with dimension breakdown, sub-check details, and recommendations.
POST /api/v1/scan
Submit a single URL for scanning. The scan runs synchronously and returns the complete result in the response.
Request
curl -X POST https://zeodyn.com/api/v1/scan \
-H "Authorization: Bearer zd_live_xxxxx" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com"}'Request body
| Field | Type | Required | Description |
|---|---|---|---|
| url | string | Yes | The URL to scan. Must be a valid, publicly accessible HTTP or HTTPS URL. |
Response
A successful scan returns 200 OK with the full scan result:
Response (200 OK)
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"url": "https://example.com",
"score": 72,
"band": "Strong Foundation",
"dimensions": [
{
"id": "discovery-access",
"name": "Discovery & Access",
"score": 85,
"weightLabel": "High",
"subChecks": [
{
"name": "Robots.txt allows AI agents",
"passed": true,
"score": 100,
"details": "Robots.txt permits crawling by AI agents"
}
],
"recommendations": [
{
"text": "Add an AI agent sitemap",
"priority": "medium",
"impact": "moderate"
}
]
}
],
"recommendations": [
{
"text": "Add JSON-LD Product schema markup",
"priority": "high",
"impact": "major",
"dimension": "structured-data"
}
],
"scannedAt": "2026-02-22T10:30:00.000Z"
}Response fields
| Field | Type | Description |
|---|---|---|
| id | string (UUID) | Unique scan identifier |
| url | string | The URL that was scanned |
| score | number (1–100) | Overall Zeodyn Score™ |
| band | string | Score band label (e.g. “Strong Foundation”) |
| dimensions | array | Per-dimension scores, sub-checks, and recommendations |
| recommendations | array | Aggregated recommendations sorted by priority |
| scannedAt | string (ISO 8601) | Timestamp of the scan |
API scans return standard rule-based recommendations. AI-enhanced recommendations are available in the dashboard only.
Error responses
| Status | Meaning |
|---|---|
| 400 | Invalid URL or missing request body |
| 401 | Missing or invalid API key |
| 429 | Rate limit exceeded |
| 502 | Target site could not be reached |
See the error handling section for the full error response format.