Use the Context Guardrails API to score a web page, email, file, or agent skill before an agent consumes it. Results are cached globally and reused across organizations. Each request is logged to the API key's organization.

All requests require the Bearer authentication described in the API overview. See the Context Guardrails overview for how scores are produced.

Endpoints

Method	Path	Description
GET	/context/web_page/{identifier}	Score a web page
POST	/context/email	Score a raw RFC 822 email
GET	/context/email/{identifier}	Look up a previously scored email by SHA-256
POST	/context/file	Score a text or PDF file from a public URL
GET	/context/file/{identifier}	Look up a previously scored file by SHA-256
POST	/context/skill	Statically score a skills.sh or GitHub hosted skill
GET	/context/skill/{identifier}	Look up a previously scored skill by SHA-256

For web pages, identifier is a hostname (example.com fetches https://example.com/) or a hostname plus path (example.com/docs). Hostnames are case-insensitive. Paths may include additional / segments.

For email, POST the raw message. The identifier is the lowercase SHA-256 hex digest of the raw bytes. Invalid identifiers or RFC 822 bodies return 400 invalid_request. Unknown email identifiers return 404 not_found. The raw body is never stored on the artifact or returned in responses.

For files, POST a public HTTP or HTTPS URL. The identifier is the lowercase SHA-256 hex digest of the normalized URL. Invalid URLs and unsupported file types return a dangerous result or 400 invalid_request, depending on whether validation fails before the scan starts. File bytes are never stored.

For skills, POST a skills.sh URL, a GitHub skill directory URL, or an owner/repository/skill identifier. The identifier is the lowercase SHA-256 digest of the canonical identifier. The scanner resolves the current Git commit, reads a bounded skill subtree, and never executes fetched code. The API key's organization must have an active Superagent Security GitHub App installation. Private skill repositories are rejected.

Score a web page

curl "https://superagent.sh/api/v1/context/web_page/example.com?details=true" \
  -H "Authorization: Bearer sk_live_..."

curl "https://superagent.sh/api/v1/context/web_page/example.com/docs?mode=full&details=true" \
  -H "Authorization: Bearer sk_live_..."

Score an email

curl "https://superagent.sh/api/v1/context/email?details=true" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: message/rfc822" \
  --data-binary @message.eml

curl "https://superagent.sh/api/v1/context/email/<sha256>?details=true" \
  -H "Authorization: Bearer sk_live_..."

Content-Type must be message/rfc822 or text/plain. Bodies larger than 1 MB are rejected.

Score a file

curl "https://superagent.sh/api/v1/context/file?mode=full&details=true" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  --data '{"url":"https://example.com/security-guidance.pdf"}'

curl "https://superagent.sh/api/v1/context/file/<sha256>?details=true" \
  -H "Authorization: Bearer sk_live_..."

Supported files include UTF-8 text, HTML, JSON, XML, CSV, CSS, JavaScript, Markdown, YAML, SQL, and PDFs with extractable text. Downloads are limited to 25 MB. Images, Office documents, archives, encrypted PDFs, and PDFs that require OCR are reported as unscannable instead of safe.

Score an agent skill

curl "https://superagent.sh/api/v1/context/skill?mode=full&details=true" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  --data '{"target":"https://skills.sh/vercel-labs/skills/find-skills"}'

The target may also be vercel-labs/skills/find-skills or a GitHub tree URL pointing to the skill directory. Fetching is limited to 200 files, 512 KB per file, and 2 MB total.

Query parameters

Param	Default	Description
details	false	Include sub_scores. Also includes threats even when the verdict is safe.
refresh	false	For web pages, file POST requests, and skill POST requests, if the cached record is older than 24 hours, enqueue a fresh scan and return the current record with pending_deep_scan: true. For email, pass the raw body again via POST to rescan.
tolerance	conservative	How the numeric score maps to a verdict: conservative, lenient, or yolo. The raw score does not change.
mode	omitted	If full, wait until the deep scan finishes (up to 90 seconds) and return a non-preliminary result.

Response

200 OK

{
  "data": {
    "object": "context_artifact",
    "id": "00000000-0000-4000-8000-000000000001",
    "origin": "web_page",
    "identifier": "example.com/docs",
    "url": "https://example.com/docs",
    "score": 85,
    "verdict": "safe",
    "confidence": "medium",
    "tolerance": "conservative",
    "scanned_at": "2026-08-12T12:00:00.000Z",
    "pending_deep_scan": false,
    "sub_scores": {
      "identity": 90.0,
      "behavior": 100.0,
      "content": 80.0
    },
    "threats": []
  }
}

Email artifacts use origin: "email", a 64-character SHA-256 identifier, and a synthetic url of email:<sha256>. File artifacts use origin: "file", a 64-character SHA-256 URL identifier, and the final downloaded URL. Skill artifacts use origin: "skill", a SHA-256 canonical identifier, and retain the submitted skills.sh or GitHub source URL.

A cache miss on a web page returns a preliminary identity score with pending_deep_scan: true and starts the remaining tiers in the background. Email, file, and skill POST misses behave the same. Repeat the request, or use mode=full, to read the completed result. Email, file, and skill GET requests never start a new scan.

Responses also include:

x-superagent-score: 85
x-superagent-verdict: safe
x-superagent-confidence: medium
x-superagent-tolerance: conservative

Verdicts

Verdict	Meaning
safe	Proceed
caution	Review before using
suspicious	Likely malicious
dangerous	Do not use

Tolerance only changes how the score maps to a verdict:

Score	Conservative	Lenient	Yolo
80–100	safe	safe	safe
60–79	caution	safe	safe
50–59	caution	caution	safe
40–49	suspicious	caution	safe
20–39	suspicious	suspicious	caution
0–19	dangerous	dangerous	suspicious

Lenient treats 35–59 as caution and 15–34 as suspicious. Yolo treats 40+ as safe, 20–39 as caution, and 10–19 as suspicious.

Threats

When details=true or the verdict is suspicious / dangerous, threats lists detected issues:

{
  "type": "prompt_injection",
  "severity": "critical",
  "detail": "deterministic prompt injection patterns detected in page text"
}

Email scans may also emit spf_fail, display_name_mismatch, brand_impersonation, malicious_attachment, and phishing when followed links are dangerous.

File scans may also emit file_unscannable, mime_mismatch, encoded_payload, redirect_chain, and extraction errors.

Skill scans may also emit skill_description_injection, skill_credential_parameter_extraction, skill_output_poisoning, skill_shadow_chaining_external_installation, skill_scope_violation, skill_hidden_encoded_instructions, skill_remote_execution, skill_secrets, skill_install_hooks, and skill_unscannable.

Next steps

• Context Guardrails overview
• API overview
• Runtime Guardrails