Table of Contents

AI Reader API

AI Reader API is built and operated by OngsooLabs and converts web pages and public text-layer PDF documents into clean AI-ready content for LLM, RAG, search, and summarization workflows.

AI Reader API is publicly available through two official access channels: RapidAPI and OngsooLabs.com. They use the same core Reader execution and response contract while keeping accounts, credentials, usage systems, billing, and entitlements separate. Official resources: Reader sample, API guide, and support.

How It Works

Web page or PDF URL -> Safe retrieval -> Content extraction -> Markdown/text/JSON output -> Usage, quality, and execution metadata

Key Features

  • AI-ready content: Converts the main page content into Markdown, text, or structured JSON suitable for AI prompts and indexing.
  • Content and title extraction: Filters common navigation, layout, and advertising noise.
  • Contracted metadata: Returns usage, quality, and execution blocks for cost, confidence, and runtime visibility.
  • Standard errors: Returns stable error codes such as INVALID_URL, UNSAFE_URL, and INVALID_REQUEST.
  • Output options: Lets callers choose whether to include optional links, images, tables, and code blocks.
  • Reader modes: Supports content-oriented modes such as article, documentation, product, forum, and generic.

Authentication

Use the credentials issued by the channel you selected:

  • RapidAPI: Send the X-RapidAPI-Key and X-RapidAPI-Host values shown in your RapidAPI dashboard.
  • OngsooLabs.com: Sign in to OngsooLabs, create a Direct API key in the Dashboard, and send it as X-API-Key.

A RapidAPI key cannot authenticate an OngsooLabs Direct request, and a Direct API key cannot authenticate a RapidAPI request. Subscription, quota, credit, billing, and entitlement state do not transfer between channels.

API Endpoints

Method RapidAPI path OngsooLabs Direct path Description
GET /v1/reader /api/v1/reader Text conversion and analysis using URL parameters
POST /v1/reader /api/v1/reader Advanced options through a JSON body
POST /v1/reader/document /api/v1/reader/document Public Beta: convert a public text-layer PDF URL to Markdown
POST /v1/reader/chunk /api/v1/reader/chunk Split text into chunks for downstream AI processing

The public prefixes and authentication headers differ by channel; the core Reader request and response behavior remains aligned. GET /v1/diagnostics is an authenticated deployment diagnostic for platform operations and is not a customer access-channel endpoint.

MCP and Agent Integration Inquiries

Native Streamable HTTP MCP access is not available through the regular RapidAPI proxy. Use the REST Reader endpoints for supported RapidAPI integrations.

RapidAPI-managed MCP use of published REST endpoints is a separate integration path; it does not forward this service's native /mcp transport. For future direct native MCP access or enterprise agent-integration inquiries, contact the provider through the RapidAPI listing with your use case and expected volume. This is a request-for-feedback channel, not a commitment that native MCP access is available or scheduled.

Quick Start: First Successful Read

  1. Create or sign in to your RapidAPI account and subscribe to an available AI Reader API plan.
  2. Copy your X-RapidAPI-Key from the RapidAPI dashboard.
  3. Run this request. It uses https://example.com/, a public page intended for integration examples.

macOS or Linux

curl --request POST \
  --url https://ai-reader-api.p.rapidapi.com/v1/reader \
  --header 'Content-Type: application/json' \
  --header 'X-RapidAPI-Host: ai-reader-api.p.rapidapi.com' \
  --header 'X-RapidAPI-Key: <your-rapidapi-key>' \
  --data '{
    "url": "https://example.com/",
    "output_format": "markdown",
    "mode": "generic",
    "enable_chunking": false
  }'

Windows PowerShell

$headers = @{
  "X-RapidAPI-Key" = "<your-rapidapi-key>"
  "X-RapidAPI-Host" = "ai-reader-api.p.rapidapi.com"
}

$body = @{
  url = "https://example.com/"
  output_format = "markdown"
  mode = "generic"
  enable_chunking = $false
} | ConvertTo-Json

$response = Invoke-RestMethod -Method Post `
  -Uri "https://ai-reader-api.p.rapidapi.com/v1/reader" `
  -Headers $headers `
  -ContentType "application/json" `
  -Body $body

$response.status
$response.content.value
$response.usage.credits
  1. A successful request returns HTTP 200, status: "success", non-empty content.value, and usage.credits: 1.

POST /v1/reader Request Example

POST /v1/reader
Content-Type: application/json
X-RapidAPI-Key: <your-rapidapi-key>
X-RapidAPI-Host: <your-rapidapi-host>

{
  "url": "https://example.com/",
  "output_format": "markdown",
  "mode": "article",
  "tokenizer": "openai",
  "output": {
    "content": true,
    "metadata": true,
    "tables": true,
    "codeBlocks": true,
    "images": false,
    "links": false
  }
}

Response Contract

GET /v1/reader and POST /v1/reader use a standardized v1 response envelope.

{
  "id": "read_abc123",
  "schemaVersion": "2026-07-12",
  "apiVersion": "v1",
  "url": "https://example.com",
  "finalUrl": "https://example.com",
  "status": "success",
  "contentType": "article",
  "title": "Example Domain",
  "language": "en",
  "content": {
    "format": "markdown",
    "value": "# Example Domain\n\nClean content..."
  },
  "metadata": {
    "canonical_url": "https://example.com/article",
    "source_name": "Example Domain",
    "published_at": "2026-07-12"
  },
  "usage": {
    "characters": 147,
    "tokens": 28,
    "chunks": 0,
    "credits": 1
  },
  "quality": {
    "version": "qv0",
    "score": null,
    "grade": null,
    "confidence": "medium",
    "signals": {
      "contentLength": 147,
      "markdownLength": 147,
      "headingCount": 1,
      "linkDensity": 0,
      "boilerplateRatio": null,
      "duplicateParagraphRatio": 0,
      "codeBlockCount": 0,
      "tableCount": 0,
      "imageCount": 0,
      "languageDetected": "en",
      "htmlToMarkdownRatio": 0.263,
      "mainContentExtractionRatio": null
    },
    "warnings": []
  },
  "execution": {
    "profile": "fast",
    "usedBrowser": false,
    "cache": "miss",
    "retryCount": 0,
    "durationMs": 842
  }
}

When output_format is json, the response uses content.article instead of content.value.

PDF Document Reader (Public Beta)

POST /v1/reader/document accepts a public HTTPS URL for a text-layer PDF and always returns Markdown. It does not accept file uploads, DOCX, OCR, encrypted PDFs, or document generation requests.

{
  "url": "https://example.com/report.pdf",
  "tokenizer": "openai",
  "enable_chunking": false
}

Every redirect is revalidated against the URL-safety policy. The beta limits downloads to 10 MB and parsing to 100 pages, does not use a browser, and returns execution.profile = "document" with usage.credits = 1 on success. A partially text-layer PDF returns available text and a PARTIAL_DOCUMENT_TEXT warning; a PDF without any extractable text returns DOCUMENT_NO_TEXT_LAYER.

metadata.canonical_url, metadata.source_name, metadata.published_at, and language are best-effort page metadata. Missing or untrusted values are omitted. published_at uses structured JSON-LD, explicit article metadata, or a <time datetime> value; it is not inferred from page text. Language is omitted when it cannot be reliably detected. Author metadata is not part of the public v1 contract.

Error Contract

Reader failures use the same versioned envelope and never charge credits.

execution.profile is internal execution metadata, not a client-controlled setting. fast reports a static path; standard reports a browser-oriented path, including dynamic site rules, force_dynamic=true, or static-to-browser fallback. When a retryable RENDER_REQUIRED error returns recommendedProfile = "standard", retry with force_dynamic=true; do not send a profile field. Successful reads keep usage.credits = 1 regardless of this metadata, browser use, or cache behavior.

{
  "id": "read_abc123",
  "schemaVersion": "2026-07-12",
  "apiVersion": "v1",
  "url": "http://127.0.0.1",
  "status": "failed",
  "error": {
    "code": "UNSAFE_URL",
    "message": "The provided URL is unsafe or targets internal network assets.",
    "retryable": false,
    "recommendedProfile": "",
    "userActionable": true
  },
  "usage": {
    "characters": 0,
    "tokens": 0,
    "chunks": 0,
    "credits": 0
  },
  "execution": {
    "profile": "fast",
    "usedBrowser": false,
    "cache": "miss",
    "retryCount": 0,
    "durationMs": 9
  }
}
  • Use mode to describe the target page type. Start with article for editorial pages and documentation for developer docs.
  • Set images and links to false when you need smaller output for token-sensitive workflows.
  • Enable tables and codeBlocks when preserving technical content matters.
Important

/v1/reader/chunk keeps its original successful array response. Failure responses use the standardized error envelope.

Credits and RapidAPI Quota

GET /v1/reader and POST /v1/reader currently use a fixed launch credit model:

  • Successful page reads return usage.credits = 1.
  • Failed page reads return usage.credits = 0.
  • Optional metadata, output format, reader mode, browser fallback, cache validation, and in-response chunking do not change the v1 launch credit value.

RapidAPI controls public request quota, enabled plans, overage pricing, bandwidth platform fees, billing, and subscription state. In the current RapidAPI configuration, the Requests object counts any endpoint call as one request.

Deployment Diagnostics

GET /v1/diagnostics is a low-cost smoke check for deployment verification. It is intended for direct platform and partner operations, not public RapidAPI traffic. It verifies API dependencies, cache behavior, TextProcessor connectivity, and Reader-to-Document-Parser reachability. When Direct Gateway is enabled, it also verifies JWKS retrieval and an ephemeral receipt claim/read/release round trip. It does not return internal service URLs, secrets, receipt identifiers or nonces, AWS identity details, Docker network details, or document content.

The endpoint does not scrape an external webpage. Direct-only checks are safely skipped when Direct Gateway is explicitly disabled.

GET /v1/diagnostics
X-RapidAPI-Proxy-Secret: <proxy-secret>

Successful diagnostics return HTTP 200 with status = ok. If any check fails, the endpoint returns HTTP 503 with status = needs_attention; the failing check also uses status = needs_attention.

{
  "status": "ok",
  "checkedAtUtc": "2026-07-07T00:00:00Z",
  "durationMs": 24,
  "checks": [
    { "name": "api_pipeline", "status": "ok", "message": "API routing and controller execution are available.", "durationMs": 0 },
    { "name": "reader_service", "status": "ok", "message": "Reader service dependency is registered.", "durationMs": 0 },
    { "name": "configuration", "status": "ok", "message": "Required deployment configuration is present.", "durationMs": 0 },
    { "name": "cache", "status": "ok", "message": "Cache read/write round trip succeeded.", "durationMs": 2 },
    { "name": "direct_jwks", "status": "ok", "message": "Direct Gateway JWKS contains an approved signing key.", "durationMs": 8 },
    { "name": "direct_receipt_store", "status": "ok", "message": "Direct receipt store write/read/delete round trip succeeded.", "durationMs": 3 },
    { "name": "text_processor", "status": "ok", "message": "TextProcessor token count check succeeded.", "durationMs": 22 },
    { "name": "document_parser", "status": "ok", "message": "Document Parser worker health check succeeded.", "durationMs": 4 }
  ]
}
Note

This service processes pages requested by the caller. Callers are responsible for complying with the terms of service, robots policies, copyright rules, and applicable laws of each target website.

See the Legal and Operational Policy for caller responsibility, logging boundaries, cache policy, and abuse controls.