Quickstart

Two paths — start with the one that matches what you're building.

ℹ

Need an API key? Sign up at app.buildonto.dev/signup — you get a Read API key on the Free tier (1k requests / month) the moment you land on /read/keys.

Read API — 60 seconds

Call POST https://api.buildonto.dev/v1/read with any public URL. Get back clean Markdown plus extraction stats. No SDK needed.

bash

# Read any public URL as clean Markdown
curl -X POST https://api.buildonto.dev/v1/read \
  -H "Authorization: Bearer $ONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://stripe.com"}'

Add Accept: text/markdown to get raw Markdown back instead of JSON. Add "fresh": true to the body to bypass the 1-hour cache. See the full /v1/read reference for the response schema.

◈

Need scoring too? Use /v1/read-and-score to get Markdown + AIO score + hallucination risk in one request.

Serve SDK — 5 minutes

Install @ontosdk/next on your Next.js site. AI bots get clean Markdown; humans get your full HTML. No code changes to your pages.

Install the SDK

Add the package to your Next.js project.

bash

npm install @ontosdk/next

Wire the build script

Update package.json so onto-next runs after your Next build. It walks your compiled HTML and writes clean .md siblings into public/.onto/.

package.json

"scripts": {
  "build": "next build && onto-next"
}

Add Edge middleware

Create middleware.ts at your project root (or update existing). The Onto middleware detects bot User-Agents, rewrites their requests to the matching .md payload, and falls through for human traffic.

middleware.ts

import { ontoMiddleware as middleware } from '@ontosdk/next/middleware';

export { middleware };

export const config = {
  matcher: ['/((?!api|_next|.*\\..*).*)'],
};

Connect to the Control Plane (optional)

Free site analytics + per-route context injection (Pro). Add the per-site API key from /serve/settings in your dashboard. Without this, the SDK still serves clean Markdown — you just don't get analytics or injection.

.env.local

ONTO_API_KEY=onto_site_xxxx
# Optional: pin the Control Plane URL. Defaults to api.buildonto.dev.
ONTO_API_URL=https://api.buildonto.dev

Build & deploy

Build the site. The Onto CLI prints a per-route reduction report and syncs the manifest to the dashboard so /serve/routes shows what bots actually receive.

bash

npm run build

# [Onto] Processed 12 pages. Total Size: 4.2MB → 38.1KB
# [Onto] Syncing manifest with Control Plane...
# ✓ Control Plane sync successful (12 files)

Verify it works

From any terminal, send a request with a bot User-Agent. Your site should respond withContent-Type: text/markdown and X-Onto-Matched: true:

bash

curl -sI -A 'GPTBot/1.0' https://yoursite.com/pricing

# Content-Type: text/markdown; charset=utf-8
# X-Onto-Bot: GPTBot (OpenAI)
# X-Onto-Matched: true

◈

Test mode in your browser: append ?onto to any URL on your deployed site to see the Markdown payload a bot would receive.