Overview
safe_fetch_url
$0.01 USDC
MCP: safe_fetch_url
SDK: safeFetchUrl()
Fetches a public URL, extracts clean readable markdown, and flags prompt-injection patterns before an AI agent reads it.
POST /v1/safe-fetch-url
POST /x402/v1/safe-fetch-url
When an agent should use it
- Read a public webpage before summarizing it in an agent workflow.
- Extract clean text from an external source while preserving a content hash.
- Screen fetched content for prompt-injection risk signals before passing it to another tool.
Input fields
Schema ref: #/components/schemas/SafeFetchUrlInput
| Field | Required | Type | Description |
|---|
url |
required |
string |
Public HTTP or HTTPS URL to fetch. Localhost, private IPs, link-local addresses, embedded credentials, unsafe redirects, and non-http(s) schemes are rejected. |
output |
optional |
string |
Response format for safe_fetch_url. Allowed values: markdown, text, or html_excerpt. Defaults to markdown. |
maxBytes |
optional |
integer |
Optional maximum response bytes to read, from 1,000 to 2,000,000. Use this to keep large pages bounded. |
includeLinks |
optional |
boolean |
When true, keep useful links in extracted markdown where available. Defaults to true. |
includeInjectionScan |
optional |
boolean |
When true, include deterministic prompt-injection risk signals for fetched content. Defaults to true. |
Output fields
Schema ref: #/components/schemas/SafeFetchUrlOutput
| Field | Required | Type | Description |
|---|
url |
required |
string |
Public HTTP or HTTPS URL to fetch. Localhost, private IPs, link-local addresses, embedded credentials, unsafe redirects, and non-http(s) schemes are rejected. |
finalUrl |
required |
string |
Final URL after safe redirects. Null only on schemas that explicitly allow null when a final URL could not be established. |
title |
required |
string,null |
Page title when one can be extracted. Null means no title was found. |
cleanMarkdown |
optional |
string |
Readable markdown extracted from the fetched page. Present when markdown output is requested. |
cleanText |
optional |
string |
Plain text extracted from the fetched page. Present when text output is requested. |
contentHash |
required |
string |
Hash of the returned or captured content for comparison, caching, and lightweight audit trails. |
riskLevel |
required |
string |
Low, medium, or high risk signal derived from deterministic checks. It is not a guarantee that content is safe or malicious. |
detectedInjectionPatterns |
required |
array |
Prompt-injection pattern identifiers found in fetched content. Empty array means no configured pattern matched. |
metadata |
required |
object |
Fetch metadata including status code, content type, fetch timestamp, and byte length. |
curl example
curl -s https://primitive402.dev/v1/safe-fetch-url \
-H 'content-type: application/json' \
-d '{
"url": "https://example.com",
"output": "markdown"
}' | jq
TypeScript SDK example
import { createNano402Client } from "@nano402/api/sdk";
const client = createNano402Client({
baseUrl: "https://primitive402.dev"
});
const result = await client.safeFetchUrl({
"url": "https://example.com",
"output": "markdown"
});
console.log(result);
Example response snippet
{
"finalUrl": "https://example.com",
"contentHash": "sha256:...",
"riskLevel": "low"
}
Safety notes
- All requested URLs are checked with SSRF protection before fetching.
- External content may still be unsafe to pass directly into an agent.
- Response content is truncated and hashed; Primitive402 does not guarantee content safety.
Common errors
400 invalid_request: request body failed validation.402 payment_required: the x402 route was called without a valid payment header.429: rate limit exceeded.500 internal_error: unexpected server error.