Quickstart

Prerequisites

A SafeURL account (sign up at the dashboard)
An API key with SCAN_WRITE scope

1. Get an API key

In the dashboard, create an API key with the SCAN_WRITE scope. Copy the key — it's shown only once.

sk_live_xxxxxxxxxxxxxxxxxxxx

2. Submit a scan

curl -X POST https://api.safeurl.ai/v1/scans \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com" }'

Response:

{
  "id": "job_01j...",
  "url": "https://example.com",
  "state": "QUEUED",
  "createdAt": "2025-01-01T00:00:00.000Z"
}

3. Poll for the result

Scans are async. Poll until state is COMPLETED or FAILED:

curl https://api.safeurl.ai/v1/scans/job_01j... \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx"

Or stream state transitions in real time:

curl -N https://api.safeurl.ai/v1/scans/job_01j.../events \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx"

4. Interpret the result

A completed scan looks like this:

{
  "id": "job_01j...",
  "url": "https://example.com",
  "state": "COMPLETED",
  "result": {
    "riskScore": 12,
    "confidence": 0.94,
    "categories": ["safe"],
    "reasoning": "The page is a standard placeholder site with no deceptive content, malicious scripts, or suspicious redirects.",
    "indicators": []
  }
}

Risk score guide

Score	Meaning
0–20	Safe
21–50	Low risk / suspicious
51–75	High risk
76–100	Malicious

Category	Description
`safe`	No threats detected
`phishing`	Credential harvesting or impersonation
`malware`	Malicious downloads or drive-by scripts
`scam`	Fraud, fake prizes, advance-fee
`suspicious`	Unusual signals but not confirmed malicious
`adult_content`	Explicit content

Next steps

Batch scanning — scan up to 50 URLs in one request
TypeScript integration — type-safe client example
Go SDK — native Go client