Use the Context Guardrails API to score a web page, email, file, agent skill, public GitHub MCP repository, or registry package 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 the shared scoring model, and the entity pages for web pages, email, files, agent skills, MCP repositories, and packages.

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
POST	/context/mcp	Statically score a public GitHub MCP repository
GET	/context/mcp/{identifier}	Look up a previously scored MCP repository by SHA-256
POST	/context/package	Score a registry package
GET	/context/package/{identifier}	Look up a previously scored package 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.

For MCP repositories, POST an owner/repository identifier or https://github.com/owner/repository URL with an optional .git suffix. The identifier is the lowercase SHA-256 digest of the canonical owner/repository identity. The scanner requires an active Superagent Security GitHub App installation and supports public repositories only. It reads repository contents statically and never connects to or executes the MCP server.

For packages, POST an ecosystem:name@version coordinate such as npm:lodash@4.17.21. The identifier is the lowercase SHA-256 digest of the canonical coordinate. Supported ecosystems are npm, PyPI, Go, RubyGems, and GitHub Actions. The scan uses the same supply chain pipeline as pull request dependency checks and fails closed when package intelligence cannot be collected.

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.

Score an MCP repository

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

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

The target may be owner/repository, https://github.com/owner/repository, or the same GitHub URL ending in .git. The static scan has three tiers:

1. Identity — evaluates the GitHub owner and repository.
2. Static analysis — inspects manifests, MCP configuration, tool definitions, schemas, source, scripts, secrets, install hooks, remote execution, and encoded instructions.
3. Semantic analysis — reviews tool names, descriptions, schemas, instructions, and relevant source for manipulation, output poisoning, and capability escalation.

Fetching is limited to 200 files, 512 KB per file, and 2 MB total. The scanner never opens an MCP connection or executes repository code. Materialization and scan failures fail closed, returning an mcp_unscannable dangerous result instead of a safe result.

Score a package

curl "https://superagent.sh/api/v1/context/package?mode=full&details=true" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  --data '{"target":"npm:lodash@4.17.21"}'

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

The target must be ecosystem:name@version. Aliases pip (PyPI), gem (RubyGems), and actions (GitHub Actions) are accepted. The scan has three tiers:

1. Identity — package age, downloads, maintainers, and quality signals.
2. Behavior — install hooks, network access, and other package-scoped alerts.
3. Content — LLM assessment of malicious or deceptive package behavior.

Scan failures fail closed, returning a package_unscannable dangerous result instead of a safe result.

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, skill POST requests, MCP POST requests, and package 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. MCP artifacts use origin: "mcp", a SHA-256 canonical repository identifier, and use the normalized GitHub repository URL. Package artifacts use origin: "package", a SHA-256 canonical ecosystem:name@version identifier, and store that coordinate as 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, skill, MCP, and package POST misses behave the same. Repeat the request, or use mode=full, to read the completed result. Email, file, skill, MCP, and package 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.

MCP scans may emit mcp_tool_shadowing, mcp_description_injection, mcp_instruction_injection, mcp_schema_abuse, mcp_output_poisoning, mcp_silent_capability_escalation, mcp_credential_harvesting, mcp_exfiltration, mcp_excessive_scope, mcp_hidden_encoded_instructions, mcp_remote_execution, mcp_secrets, mcp_install_hooks, and mcp_unscannable.

Package scans may emit package_network_access, package_install_hooks, package_credential_access, and package_unscannable when package intelligence or the risk assessment reports those behaviors.

Next steps

• Context Guardrails overview
• Web pages
• Email
• Files
• Agent skills
• MCP repositories
• Packages
• API overview
• Runtime Guardrails