Small, runnable examples for the OngsooLabs Direct API. Start with Reader to turn a public webpage into a Markdown file, then try Summary, PDF Document, or standalone Chunk.
Get a Direct API key, clone this repository, and choose one example. Each command makes a real request and can consume credits.
git clone https://github.com/OngsooLabs/api-examples.git
cd api-examples
read -rsp 'Direct API key: ' ONGSOOLABS_API_KEY; echo
export ONGSOOLABS_API_KEY
python3 examples/reader/python/read.pyOn success, open reader-output.md in your current directory. The example reads an OngsooLabs-owned public HTML input. It does not need access to your files or private content.
Try Playground · Get API Key · API Guide
| Goal | Example |
|---|---|
| Read a webpage and save Markdown | Reader cURL and options, Node.js, Python, C# |
| Summarize a webpage | Summary cURL |
| Extract a public text-layer PDF | Document cURL |
| Split supplied text into chunks | Chunk cURL |
These examples use the synchronous Direct endpoints at https://ongsoolabs.com with X-API-Key authentication. For other integrations, see the official Async jobs and Webhooks guide, MCP guide, and API channel guide. This repository currently contains synchronous examples only.
- Node.js: use the latest patch of Node.js 24 LTS.
- Python: use a supported Python 3 release, preferably 3.14; these examples require 3.12 or newer.
- C#: use the .NET 10 SDK.
- cURL snippets: Bash, cURL 7.76+ (
--fail-with-body), and Python 3.12+ (python3) for UUID creation and response checks. Do not paste Bash snippets directly into PowerShell.
There are no npm, pip, or NuGet package dependencies. Use only the runtime needed by the example you choose.
The examples read actual environment variables. .env.example is a reference and is not loaded automatically. In PowerShell, set the key without putting it in shell history:
$env:ONGSOOLABS_API_KEY = Read-Host 'Direct API key' -MaskInput
python examples/reader/python/read.py
# Alternatively: node examples/reader/javascript/read.mjs
# Alternatively: dotnet run --project examples/reader/csharp/ReaderExample.csproj-MaskInput requires PowerShell 7.1+. On Windows, use py -3 if that is your installed Python launcher; ensure it selects Python 3.12+.
The language clients accept optional READER_URL for a public HTTPS webpage. Requests always go to the fixed OngsooLabs Direct endpoint; READER_URL is the content to extract, not the API server. Keep keys on your server or local machine. Do not put them in browser code, URLs, screenshots, issues, or source files.
The Reader clients write reader-output.md only after an HTTP success, status: "success", and nonempty Markdown content. They exit nonzero for partial, failure, invalid responses, timeouts, or file errors. API and response-validation failures leave an earlier output file unchanged. Successful runs overwrite it; an interrupted or failed file write can leave it incomplete. Always check the process exit code before using existing output.
Node.js and C# use a 120-second request timeout. Python uses a 120-second blocking socket timeout, which is not an overall wall-clock deadline. cURL uses a 120-second total timeout. None of the examples automatically retries or claims that stopping the client cancels server work.
Each new language-client run creates and prints a UUID Idempotency-Key. When a timeout or connection interruption leaves the result uncertain, keep the same input and retry with that printed key:
export IDEMPOTENCY_KEY='paste_the_previously_printed_uuid_here'
python3 examples/reader/python/read.py
unset IDEMPOTENCY_KEYPowerShell equivalent: set $env:IDEMPOTENCY_KEY to the previous UUID, rerun the same example with unchanged input, then Remove-Item Env:IDEMPOTENCY_KEY. A changed request is a new operation and needs a new key. For cURL, rerun the curl command with the existing shell variable; do not rerun its UUID-generation line for the same uncertain request.
For 401, check the key; for 403, check available credits and workspace access; for 400, check the request. For 429, honor Retry-After before a deliberate retry. For other failures, consult the error and retry reference. Do not blindly submit another request with a new key after an uncertain outcome.
Generated result files and .env files are ignored by Git but remain on your machine. Review extracted content before sharing it.
Examples call the real API and may consume credits. See current pricing, the API guide, and terms for service rules. The source license does not grant API credits or change service terms.
For an example bug, open an issue with the example name, runtime version, and a minimal reproduction using owned public input. Keep credentials and private request/response data out of issues. For account or billing questions, use the support route on the OngsooLabs website.
Prepared against the public Direct guide and OpenAPI on 2026-09-07.
Authenticated end-to-end validation passed on 2026-09-07 using OngsooLabs-owned public HTML/PDF inputs and supplied sample text: all three Reader language clients saved Markdown, and all five cURL snippets succeeded (Reader basic/options, Summary, Document, and Chunk). These are point-in-time checks, not an availability guarantee.
Local failure checks use synthetic responses with Node.js 24.18.0, Python 3.12.14, and .NET SDK 10.0.301; the same runtimes passed the live client checks. JSON excerpts in the example guides are synthetic selected fields, not captured live output. Runtime patch versions above describe the test environment, not an instruction to install an older patch.
When a related public API contract changes, check the affected example and its linked guide. These local checks use synthetic responses and do not need an API key or consume credits. Run them from the repository root with the listed runtimes installed; the cURL check also needs Bash on PATH (BASH_EXE can select its executable).
node --test tests/reader.test.mjs
python3 -m unittest discover -s tests -p 'test_*.py'
dotnet run --project tests/csharp/ReaderChecks.csproj --configuration Release
python3 tests/check_curl_docs.pyPassing these checks does not replace authenticated end-to-end validation against the service before publication.
Example code and original documentation are MIT licensed.