AI READER API GUIDE

Turn web content into
AI-ready results.

Read or summarize public HTTPS content synchronously, or submit Direct async jobs and receive signed completion webhooks. Build reliable inputs for LLM, RAG, and agent workflows.

Direct API Available

AUTHENTICATION

Use your Workspace API key.

Send the one-time-revealed oslr_ key in X-API-Key. Never place the key in a URL, browser script, public repository, or support message.

CREDIT USAGE

Each successful AI Reader operation uses one credit.

Reader and Document use 1 credit on success; Summary uses 5. Async jobs reserve the same amount at submission and settle it only after the terminal result is reconciled. Partial results, failures, cancellations, and Gateway rejections use 0 credits.

REQUEST TRACKING

`X-Request-Id`

Direct responses include an opaque X-Request-Id after request preparation. Include it in a support request about that operation. Early authentication or ingress rejection may not have one.

POST RETRIES

Retry a POST request safely with Idempotency-Key.

Idempotency-Key lets the Gateway recognize the same logical POST operation when a network timeout or client interruption leaves its result uncertain. It is optional for synchronous POST endpoints and required for every async submission.

Create a new UUID D-format value or ULID for each new POST operation.
Send that value on the first request and reuse it only to retry the same operation.
Use a new value when the request changes. Reusing a key for different input returns 409 IDEMPOTENCY_KEY_CONFLICT.

Idempotency-Key Replace the value shown in each POST example with a newly generated value. Do not reuse the example value for a real request.

QUICK START

See your first Reader request flow quickly.

Use an OngsooLabs-authored static HTML input to quickly inspect the Direct API request and response shape without making a live API call.

Source URL: /examples/reader/owned-controlled-reader-source.html
Direct endpoint: POST /api/v1/reader
Authentication: X-API-Key: oslr_your_api_key
Output format: markdown

DIRECT REQUEST

POST /api/v1/reader
X-API-Key: oslr_your_api_key
Idempotency-Key: <new UUID or ULID for this POST>
Content-Type: application/json

{
  "url": "https://ongsoolabs.com/examples/reader/owned-controlled-reader-source.html",
  "mode": "generic",
  "output_format": "markdown",
  "enable_chunking": false
}

EXAMPLE RESPONSE

X-Request-Id: dgr_example_request_id

{
  "status": "success",
  "title": "OngsooLabs controlled Reader source",
  "content": {
    "format": "markdown",
    "value": "# OngsooLabs controlled Reader source\n\nThis page is an owned, controlled input..."
  },
  "usage": { "credits": 1 }
}

The source page and the sanitized contract example are maintained by OngsooLabs.

OngsooLabs Direct is publicly available. Sign in to create a Direct API key and manage credits and billing in the Dashboard. This static example does not execute an API call.

Runnable code examples · GitHub

GET

Read a webpage with query parameters

/api/v1/reader

Extract clean main content, metadata, and optional chunks from one public HTTPS webpage using URL query parameters.

Use it when: you need a simple URL-based integration, agent tool, or quick diagnostic request without a JSON body.

Usage rule 1 Direct credit per successful request Partial, failed, or Gateway-rejected requests use 0 credits.

Base URL: https://ongsoolabs.com
Limits: One public HTTPS URL per synchronous request. No login, cookies, custom headers, paywall or bot-control bypass, batch, crawl, or asynchronous job.

Request parameters

Parameter	Requirement	Default	Description
`url`	Required	`-`	Public HTTPS webpage URL.
`output_format`	Optional	`markdown`	markdown, text, or json output.
`tokenizer`	Optional	`openai`	Tokenizer estimate: openai, claude, gemini, or llama.
`enable_chunking`	Optional	`false`	Include overlapping chunks in a Reader or Document response.
`chunk_size_tokens`	Optional	`500`	Target token count for each token-based chunk.
`overlap_size_tokens`	Optional	`100`	Token overlap between adjacent chunks; must be smaller than chunk size.
`force_dynamic`	Optional	`false`	Request browser rendering for a page that requires client-side rendering; it does not bypass access controls.
`mode`	Optional	`generic`	Extraction mode: generic, article, documentation, product, or forum.
`output_content`	Optional	`true`	Controls content, metadata, tables, code blocks, images, and links in the response.
`output_metadata`	Optional	`true`	Controls content, metadata, tables, code blocks, images, and links in the response.
`output_tables`	Optional	`true`	Controls content, metadata, tables, code blocks, images, and links in the response.
`output_code_blocks`	Optional	`true`	Controls content, metadata, tables, code blocks, images, and links in the response.
`output_images`	Optional	`false`	Controls content, metadata, tables, code blocks, images, and links in the response.
`output_links`	Optional	`false`	Controls content, metadata, tables, code blocks, images, and links in the response.
`disable_css`	Optional	`null`	Optional rendering hint. Leave unset unless validating a known rendering issue.

Request example

curl --request GET \
  --url "https://ongsoolabs.com/api/v1/reader?url=https%3A%2F%2Fongsoolabs.com%2Fexamples%2Freader%2Fowned-controlled-reader-source.html&output_format=markdown&mode=article" \
  --header "X-API-Key: oslr_your_api_key"

$headers = @{
  "X-API-Key" = "oslr_your_api_key"
}
Invoke-RestMethod -Method GET `
  -Uri "https://ongsoolabs.com/api/v1/reader?url=https%3A%2F%2Fongsoolabs.com%2Fexamples%2Freader%2Fowned-controlled-reader-source.html&output_format=markdown&mode=article" `
  -Headers $headers

Response example

{
  "id": "read_example",
  "status": "success",
  "contentType": "webpage",
  "title": "OngsooLabs Reader controlled source",
  "content": {
    "format": "markdown",
    "value": "# Controlled Reader source\n\nThis page is maintained by OngsooLabs for Reader contract verification."
  },
  "usage": {
    "characters": 92,
    "tokens": 18,
    "chunks": 0,
    "credits": 1
  }
}

{
  "id": "read_example",
  "status": "partial",
  "error": {
    "code": "PARTIAL_CONTENT",
    "message": "The extracted main content did not meet the quality gate.",
    "retryable": true,
    "recommendedProfile": "standard"
  },
  "usage": {
    "characters": 0,
    "tokens": 0,
    "chunks": 0,
    "credits": 0
  }
}

This example is based on the approved API specification.

POST

Read a webpage with JSON options

/api/v1/reader

Extract clean Markdown, text, or structured JSON from one public HTTPS webpage with explicit output and chunking controls.

Use it when: you need reproducible RAG ingestion, metadata controls, dynamic-render fallback, or optional inline chunking.

Usage rule 1 Direct credit per successful request Partial, failed, or Gateway-rejected requests use 0 credits.

Base URL: https://ongsoolabs.com
Limits: One public HTTPS URL per synchronous request. Static retrieval is attempted first; force_dynamic requests browser rendering but does not bypass access controls.

Request parameters

Parameter	Requirement	Default	Description
`url`	Required	`-`	Public HTTPS webpage URL.
`output_format`	Optional	`markdown`	markdown, text, or json output.
`tokenizer`	Optional	`openai`	Tokenizer estimate: openai, claude, gemini, or llama.
`enable_chunking`	Optional	`false`	Include overlapping chunks in a Reader or Document response.
`chunk_size_tokens`	Optional	`500`	Target token count for each token-based chunk.
`overlap_size_tokens`	Optional	`100`	Token overlap between adjacent chunks; must be smaller than chunk size.
`force_dynamic`	Optional	`false`	Request browser rendering for a page that requires client-side rendering; it does not bypass access controls.
`mode`	Optional	`generic`	Extraction mode: generic, article, documentation, product, or forum.
`output`	Optional	`object defaults`	Controls content, metadata, tables, code blocks, images, and links in the response.
`disable_css`	Optional	`null`	Optional rendering hint. Leave unset unless validating a known rendering issue.

Request example

curl --request POST \
  --url "https://ongsoolabs.com/api/v1/reader" \
  --header "X-API-Key: oslr_your_api_key" \
  --header "Idempotency-Key: 00000000-0000-4000-8000-000000000000" \
  --header "Content-Type: application/json" \
  --data '{
  "url": "https://ongsoolabs.com/examples/reader/owned-controlled-reader-source.html",
  "output_format": "markdown",
  "tokenizer": "openai",
  "enable_chunking": false,
  "force_dynamic": false,
  "mode": "article"
}'

$headers = @{
  "X-API-Key" = "oslr_your_api_key"
  "Idempotency-Key" = "00000000-0000-4000-8000-000000000000"
}
$body = @'
{
  "url": "https://ongsoolabs.com/examples/reader/owned-controlled-reader-source.html",
  "output_format": "markdown",
  "tokenizer": "openai",
  "enable_chunking": false,
  "force_dynamic": false,
  "mode": "article"
}
'@
Invoke-RestMethod -Method POST `
  -Uri "https://ongsoolabs.com/api/v1/reader" `
  -Headers $headers `
  -ContentType "application/json" `
  -Body $body

{
  "url": "https://ongsoolabs.com/examples/reader/owned-controlled-reader-source.html",
  "output_format": "markdown",
  "tokenizer": "openai",
  "enable_chunking": false,
  "force_dynamic": false,
  "mode": "article"
}

Response example

{
  "id": "read_example",
  "status": "success",
  "contentType": "webpage",
  "title": "OngsooLabs Reader controlled source",
  "content": {
    "format": "markdown",
    "value": "# Controlled Reader source\n\nThis page is maintained by OngsooLabs for Reader contract verification."
  },
  "usage": {
    "characters": 92,
    "tokens": 18,
    "chunks": 0,
    "credits": 1
  }
}

{
  "id": "read_example",
  "status": "failed",
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request options are invalid.",
    "retryable": false
  },
  "usage": {
    "characters": 0,
    "tokens": 0,
    "chunks": 0,
    "credits": 0
  }
}

This example is based on the approved API specification.

POST

Read a public PDF document

/api/v1/reader/document

Convert a public HTTPS text-layer PDF URL to Markdown with optional token counting and chunking.

Use it when: you need text from a public specification, report, or paper that already contains an extractable text layer.

Usage rule 1 Direct credit per successful request Partial, failed, or Gateway-rejected requests use 0 credits.

Base URL: https://ongsoolabs.com
Limits: Maximum 10 MiB and 100 pages. Markdown only. No upload, DOCX, OCR, encrypted PDF, browser rendering, cookies, or custom headers.

Request parameters

Parameter	Requirement	Default	Description
`url`	Required	`-`	Public HTTPS URL for a PDF with an extractable text layer.
`tokenizer`	Optional	`openai`	Tokenizer estimate: openai, claude, gemini, or llama.
`enable_chunking`	Optional	`false`	Include overlapping chunks in a Reader or Document response.
`chunk_size_tokens`	Optional	`500`	Target token count for each token-based chunk.
`overlap_size_tokens`	Optional	`100`	Token overlap between adjacent chunks; must be smaller than chunk size.

Request example

curl --request POST \
  --url "https://ongsoolabs.com/api/v1/reader/document" \
  --header "X-API-Key: oslr_your_api_key" \
  --header "Idempotency-Key: 00000000-0000-4000-8000-000000000000" \
  --header "Content-Type: application/json" \
  --data '{
  "url": "https://ongsoolabs.com/examples/reader/owned-controlled-reader-document.pdf",
  "tokenizer": "openai",
  "enable_chunking": false
}'

$headers = @{
  "X-API-Key" = "oslr_your_api_key"
  "Idempotency-Key" = "00000000-0000-4000-8000-000000000000"
}
$body = @'
{
  "url": "https://ongsoolabs.com/examples/reader/owned-controlled-reader-document.pdf",
  "tokenizer": "openai",
  "enable_chunking": false
}
'@
Invoke-RestMethod -Method POST `
  -Uri "https://ongsoolabs.com/api/v1/reader/document" `
  -Headers $headers `
  -ContentType "application/json" `
  -Body $body

{
  "url": "https://ongsoolabs.com/examples/reader/owned-controlled-reader-document.pdf",
  "tokenizer": "openai",
  "enable_chunking": false
}

Response example

{
  "id": "read_document_example",
  "status": "success",
  "contentType": "document",
  "title": "OngsooLabs Reader controlled document",
  "content": {
    "format": "markdown",
    "value": "# OngsooLabs Reader controlled document\n\nThis text-layer PDF is maintained for Reader contract verification."
  },
  "usage": {
    "characters": 105,
    "tokens": 19,
    "chunks": 0,
    "credits": 1
  },
  "execution": {
    "profile": "document",
    "usedBrowser": false
  }
}

{
  "id": "read_document_example",
  "status": "failed",
  "error": {
    "code": "DOCUMENT_NO_TEXT_LAYER",
    "message": "The PDF does not contain extractable text.",
    "retryable": false
  },
  "usage": {
    "characters": 0,
    "tokens": 0,
    "chunks": 0,
    "credits": 0
  },
  "execution": {
    "profile": "document",
    "usedBrowser": false
  }
}

This example is based on the approved API specification.

POST

Split raw text into chunks

/api/v1/reader/chunk

Split supplied text into ordered overlapping token- or character-based chunks for embedding and retrieval pipelines.

Use it when: you already have source text and need deterministic chunk boundaries without fetching a URL.

Usage rule 1 Direct credit per successful request Partial, failed, or Gateway-rejected requests use 0 credits.

Base URL: https://ongsoolabs.com
Limits: Maximum 1,000,000 input characters and 2,048 output chunks. Token size 16-8,192; character size 64-65,536; overlap must be smaller than chunk size.

Request parameters

Parameter	Requirement	Default	Description
`text`	Required	`-`	Raw text to split; maximum 1,000,000 characters.
`tokenizer`	Optional	`openai`	Tokenizer estimate: openai, claude, gemini, or llama.
`use_tokens`	Optional	`true`	Use token-based chunk sizes when true; character sizes when false.
`chunk_size_tokens`	Optional	`500`	Target token count for each token-based chunk.
`overlap_size_tokens`	Optional	`100`	Token overlap between adjacent chunks; must be smaller than chunk size.
`chunk_size`	Optional	`1000`	Target character count when use_tokens is false.
`overlap_size`	Optional	`200`	Character overlap when use_tokens is false; must be smaller than chunk size.

Request example

curl --request POST \
  --url "https://ongsoolabs.com/api/v1/reader/chunk" \
  --header "X-API-Key: oslr_your_api_key" \
  --header "Idempotency-Key: 00000000-0000-4000-8000-000000000000" \
  --header "Content-Type: application/json" \
  --data '{
  "text": "OngsooLabs Reader prepares clean source text for retrieval pipelines. This controlled sample demonstrates overlapping token chunks.",
  "tokenizer": "openai",
  "use_tokens": true,
  "chunk_size_tokens": 32,
  "overlap_size_tokens": 8
}'

$headers = @{
  "X-API-Key" = "oslr_your_api_key"
  "Idempotency-Key" = "00000000-0000-4000-8000-000000000000"
}
$body = @'
{
  "text": "OngsooLabs Reader prepares clean source text for retrieval pipelines. This controlled sample demonstrates overlapping token chunks.",
  "tokenizer": "openai",
  "use_tokens": true,
  "chunk_size_tokens": 32,
  "overlap_size_tokens": 8
}
'@
Invoke-RestMethod -Method POST `
  -Uri "https://ongsoolabs.com/api/v1/reader/chunk" `
  -Headers $headers `
  -ContentType "application/json" `
  -Body $body

{
  "text": "OngsooLabs Reader prepares clean source text for retrieval pipelines. This controlled sample demonstrates overlapping token chunks.",
  "tokenizer": "openai",
  "use_tokens": true,
  "chunk_size_tokens": 32,
  "overlap_size_tokens": 8
}

Response example

[
  {
    "index": 0,
    "start_char": 0,
    "end_char": 120,
    "token_count": 24,
    "content": "OngsooLabs Reader prepares clean source text for retrieval pipelines. This controlled sample demonstrates overlapping token chunks."
  }
]

{
  "id": "read_chunk_example",
  "status": "failed",
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Chunk size or overlap is outside the supported boundary.",
    "retryable": false
  },
  "usage": {
    "characters": 0,
    "tokens": 0,
    "chunks": 0,
    "credits": 0
  }
}

This example is based on the approved API specification.

POST

Create a webpage summary

/api/v1/summary

Submit one public HTTPS webpage URL. quality is optional and currently accepts standard.

Usage rule 5 Direct credits per successful Summary request. A failed request, Reader partial result, or Gateway rejection does not settle Summary credits.

Base URL: https://ongsoolabs.com
Limits: One public HTTPS webpage per request. PDF, uploads, OCR, custom prompts, cookies, headers, and batch are not supported. Use the Direct async jobs endpoint when the result does not need to be returned in the same HTTP request.

Request body

{
  "url": "https://example.com/article",
  "quality": "standard"
}

Response example

{
  "id": "sum_example",
  "schemaVersion": "1.0",
  "apiVersion": "v1",
  "url": "https://example.com/article",
  "finalUrl": "https://example.com/article",
  "status": "success",
  "sourceType": "html",
  "title": "Example article",
  "summary": "This controlled example shows the response shape for one successful webpage summary.",
  "keywords": [
    "controlled example",
    "webpage summary"
  ],
  "quality": "standard",
  "usage": {
    "inputTokens": 128,
    "outputTokens": 42,
    "credits": 5
  },
  "execution": {
    "durationMs": 412
  }
}

Idempotency-Key Use a unique UUID D-format or ULID for each logical POST operation, and reuse it only when retrying that same operation. Reusing it with a different request returns 409.

A successful response contains a versioned Summary object with title, summary, best-effort keywords, sourceType, usage, and execution. Provider and model names are not exposed.

202

Run Reader, Document, and Summary asynchronously

POST /api/v1/{operation}/jobs

Submit work without keeping the original HTTP connection open. A successful submission returns 202 Accepted with an opaque job ID and URLs for status and result retrieval.

Use it when: the caller can poll for completion or receive a completion webhook instead of waiting for the result in the submission response.

Usage rule The synchronous credit cost is reserved, then settled once. Reader and Document reserve 1 credit; Summary reserves 5. A successful terminal result finalizes the reservation. Partial, failed, or cancelled work releases it.

Base URL: https://ongsoolabs.com
Availability: OngsooLabs Direct only. Async submission and completion webhooks are not available through third-party marketplace channels.

Async lifecycle endpoints

Method	Endpoint	Description
`POST`	`/api/v1/reader/jobs`	Submit a Reader request and receive a job ID.
`POST`	`/api/v1/reader/document/jobs`	Submit a public text-layer PDF Document request and receive a job ID.
`POST`	`/api/v1/summary/jobs`	Submit a Summary request and receive a job ID.
`GET`	`/api/v1/jobs/{jobId}`	Read the tenant-scoped job status.
`GET`	`/api/v1/jobs/{jobId}/result`	Retrieve the canonical result after Web settlement completes.
`DELETE`	`/api/v1/jobs/{jobId}`	Request cancellation while the job is queued or running.

X-API-Key is required on every lifecycle request. Idempotency-Key is required on each submission. Reuse it only for the exact same logical request.

Submit a Reader job

curl --request POST \
  --url "https://ongsoolabs.com/api/v1/reader/jobs" \
  --header "X-API-Key: oslr_your_api_key" \
  --header "Idempotency-Key: 00000000-0000-4000-8000-000000000000" \
  --header "Content-Type: application/json" \
  --data '{
  "url": "https://example.com/article",
  "output_format": "markdown"
}'

202 Accepted response

{
  "jobId": "aj_example",
  "operation": "reader",
  "status": "queued",
  "statusUrl": "/api/v1/jobs/aj_example",
  "resultUrl": "/api/v1/jobs/aj_example/result"
}

Job status lifecycle

Status	Description
`created`	The durable job was created and activation is being completed.
`queued`	The job is waiting for an execution slot.
`running`	The job is executing.
`succeeded` / `partial` / `failed` / `cancelled`	The operation reached a terminal outcome. Result retrieval may briefly remain pending while credits and webhook delivery are settled.
`reconciliation_required`	Web could not safely complete settlement. Do not submit a replacement with a new idempotency key; retry status later or contact support.

Status response

{
  "jobId": "aj_example",
  "operation": "reader",
  "status": "succeeded",
  "createdAt": "2026-09-05T00:00:00Z",
  "completedAt": "2026-09-05T00:00:08Z",
  "errorCode": null
}

JOB_FINALIZATION_PENDING The result endpoint returns HTTP 409 with retryable=true until Web settlement is complete. Retry the same result URL; do not create another job.

POST

Receive signed completion webhooks

Your verified HTTPS endpoint on port 443

Workspace owners configure one HTTPS endpoint, rotate its one-time-revealed secret, select operations and terminal events, send a signed test, and review delivery history in Dashboard Webhooks.

Open Dashboard Webhooks →

Completion events

Event	Description
`job.succeeded`	The job completed successfully and its result is available.
`job.partial`	The job completed with a partial result.
`job.failed`	The job reached a terminal failure.
`job.cancelled`	The job was cancelled.

Delivery headers

Header	Description
`X-OngsooLabs-Timestamp`	Unix time in seconds used by the signature and replay-window check.
`X-OngsooLabs-Signature`	Versioned lowercase hexadecimal HMAC-SHA-256 value in the form v1=<digest>.
`X-OngsooLabs-Event-Id`	Stable completion event ID. Use it as the receiver's idempotency key.
`X-OngsooLabs-Delivery-Id`	ID for this individual delivery attempt.

Completion payload

{
  "id": "8b8b2ac0-bb51-4fbb-91f8-3a517739f687",
  "type": "job.succeeded",
  "createdAt": "2026-09-05T00:00:09Z",
  "data": {
    "jobId": "aj_example",
    "operation": "reader",
    "status": "succeeded",
    "completedAt": "2026-09-05T00:00:08Z",
    "errorCode": null
  }
}

Signature input

signed = UTF8(timestamp + ".") || raw_request_body
expected = "v1=" + hex(HMAC-SHA256(webhook_secret, signed))

Verification: Read the request body as exact raw bytes, reject timestamps outside five minutes, calculate the signature with the active secret, compare in constant time, and deduplicate by event ID before processing.

Automatic retry: Delivery is attempted immediately and, after failures, at 1 minute, 5 minutes, 30 minutes, and 2 hours: five attempts total. Return any 2xx response within 10 seconds to acknowledge it.

Manual redelivery: History is retained for 30 days. A redelivery sends the same event through the current endpoint and secret with a new delivery ID, timestamp, and signature; it does not rerun the job or change credits. Duplicates are possible.

Network boundary: No fixed sender IP or customer IP allowlist is provided. Verify the raw-body HMAC, timestamp, and event ID on every delivery.

COMMON REFERENCE

Error and retry reference

Gateway errors use the Reader error envelope with usage.credits = 0. Reader-originated errors listed in the downloaded OpenAPI can also be returned after the Gateway accepts a request.

HTTP	Error code	Description
400	`INVALID_REQUEST`	The request or Idempotency-Key format is invalid.
401	`INVALID_API_KEY`	X-API-Key is missing, inactive, or invalid.
403	`USAGE_EXHAUSTED`	No Direct credit is currently available for the Workspace.
409	`IDEMPOTENCY_KEY_CONFLICT`	The same Idempotency-Key was used with a different method, path, or body.
413	`REQUEST_BODY_TOO_LARGE`	The request body exceeded the Direct Gateway ingress limit.
429	`RATE_LIMITED`	The ingress, credential, or Workspace limit was reached. Honor Retry-After.
503	`TEMPORARY_UNAVAILABLE`	The Gateway could not safely determine delivery or credit settlement. Retry the same operation with the same Idempotency-Key.

Retry: Retry only when error.retryable is true. Honor Retry-After on 429, and reuse the same Idempotency-Key only for the same logical Direct POST operation.

Privacy: Submit only public HTTPS webpages or public text-layer PDF URLs. Authentication, cookies, arbitrary headers, paywall bypass, file upload, OCR, DOCX, and encrypted PDFs are not supported.

Support: For a request-specific problem, send the response X-Request-Id or Reader id to support@ongsoolabs.com. Send a source URL only when support explicitly requests it through an approved path.

Turn web content intoAI-ready results.

Use your Workspace API key.

Each successful AI Reader operation uses one credit.

X-Request-Id

Retry a POST request safely with Idempotency-Key.

See your first Reader request flow quickly.

Request parameters

Request example

Response example

Request parameters

Request example

Response example

Request parameters

Request example

Response example

Request parameters

Request example

Response example

Request body

Response example

Async lifecycle endpoints

Submit a Reader job

202 Accepted response

Job status lifecycle

Status response

Completion events

Delivery headers

Completion payload

Signature input

Turn web content into
AI-ready results.

`X-Request-Id`