Documentation

POST /v1/read

POST /v1/read api-key · read #

Fetch a URL and return clean extracted text. Tries the cache first, then HTTP, then an isolated headless browser for JS-heavy pages.

Request

FieldTypeDescription
urlstringrequiredThe page URL to read (http/https).
maxCharsintegeroptionalCap on returned characters (default 200,000).
format'markdown' | 'text'optionalExtraction format — markdown keeps structure, text is plain.
forceBrowserbooleanoptionalSkip the HTTP attempt and render in the isolated browser directly.

Example

curl -X POST https://agw.orcanox.xyz/v1/read \
  -H "Authorization: Bearer agw_…" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

Response

json
{
  "url": "https://example.com",
  "finalUrl": "https://example.com/",
  "status": 200,
  "title": "Example Domain",
  "content": "This domain is for use in illustrative examples…",
  "contentType": "text/html; charset=UTF-8",
  "chars": 1256,
  "truncated": false,
  "blocks": 5,
  "linkCharsRatio": 0.12,
  "contentKind": "article",
  "fetchedVia": "http",
  "method": "http",
  "tookMs": 41,
  "renderReason": null,
  "cached": true,
  "latencyMs": 42
}

Errors

StatuscodeExample
400bad_request{"code":"bad_request","message":"invalid url"}
502fetch_failed{"code":"fetch_failed","message":"upstream returned 404"}
504fetch_timeout{"code":"fetch_timeout","message":"deadline exceeded"}