> For clean Markdown of this page, append .md to its URL. For the complete documentation index, see https://www.superagent.sh/llms.txt.


Score web pages, email, messages, files, agent skills, public GitHub MCP repositories, and registry packages through the REST API.

# Context Guardrails

Use the Context Guardrails API to score a web page, email, message, 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.

PII and PHI use cases are excluded. Classify and filter content before sending request bodies or URLs to this API.

All requests require the Bearer authentication described in the [REST API](https://www.superagent.sh/docs/api). See the [Context Guardrails overview](https://www.superagent.sh/docs/security-workers/agent-guardrails/context) for the shared scoring model, and the entity pages for [web pages](https://www.superagent.sh/docs/security-workers/agent-guardrails/web-and-files), [email](https://www.superagent.sh/docs/security-workers/agent-guardrails/email-and-messages), [messages](https://www.superagent.sh/docs/security-workers/agent-guardrails/email-and-messages), [files](https://www.superagent.sh/docs/security-workers/agent-guardrails/web-and-files), [agent skills](https://www.superagent.sh/docs/security-workers/agent-guardrails/extensions-and-packages), [MCP repositories](https://www.superagent.sh/docs/security-workers/agent-guardrails/extensions-and-packages), and [packages](https://www.superagent.sh/docs/security-workers/agent-guardrails/extensions-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/message` | Score text and outbound HTTPS links from an SMS or WhatsApp message |
| `GET` | `/context/message/{identifier}` | Look up a previously scored message 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 messages, `POST` provider-neutral JSON. The identifier is the lowercase SHA-256 hex digest of the canonical channel, text, and link fields. Invalid JSON or empty text returns `400 invalid_request`. Unknown message identifiers return `404 not_found`. Message scans cover text and outbound HTTP or HTTPS links only. Media and attachments are not scanned. The submitted text 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

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

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

## Score a message

```bash
curl "https://superagent.sh/api/v1/context/message?mode=full&details=true" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  --data '{
    "text": "Review https://login.example.net/reset",
    "channel": "sms",
    "links": ["https://login.example.net/reset"]
  }'
```

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

`text` is required and must be a non-empty string. `channel` is an optional label such as `sms` or `whatsapp`. `links` is an optional array of outbound HTTP or HTTPS URLs, up to 50. URLs in the text are also extracted. The endpoint is intended for SMS and WhatsApp. It scans text and outbound links, not media or attachments.

Identity is not scored. The identity sub-score is a neutral compatibility value with zero weight, and completed message confidence is capped at `medium`. Bodies larger than 1 MB are rejected.

## Score an email

Submit raw RFC 822 bytes for the full email scan:

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

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

Raw email uses `Content-Type: message/rfc822` or `text/plain`. Bodies larger than 1 MB are rejected.

## Score a file

```bash
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"}'
```

```bash
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

```bash
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

```bash
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"}'
```

```bash
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

```bash
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"}'
```

```bash
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 and message, file, skill, MCP, or 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, submit 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`

```json
{
  "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>`. Message artifacts use `origin: "message"`, a SHA-256 identifier derived from the canonical JSON, and a synthetic `url` of `message:<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, message, file, skill, MCP, and package `POST` misses behave the same. Repeat the request, or use `mode=full`, to read the completed result. Email, message, file, skill, MCP, and package `GET` requests never start a new scan.

Responses also include:

```text
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:

```json
{
  "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.

Message scans may also emit `prompt_injection`, `exfiltration`, `social_engineering`, `credential_harvesting`, `encoded_payload`, 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

- [Understand Context Guardrails](https://www.superagent.sh/docs/security-workers/agent-guardrails/context)
- [Protect email and messages](https://www.superagent.sh/docs/security-workers/agent-guardrails/email-and-messages)
- [Subscribe to context events with Webhooks](https://www.superagent.sh/docs/webhooks)

---
Source: https://www.superagent.sh/docs/api/context-guardrails
Index: https://www.superagent.sh/llms.txt