Quickstart[01]

Quickstart

Pick a route. Each is a few stops and ends with a check that it worked — the others stay out of your way.

API · 30 sec

Call the API

01
Get a key
Sign in, then put the key in your shell. Paste it into the key chip at the top and every command here fills in.
Sign in and grab a key — every example below fills itself in.
One Onto account across the dashboard, docs and site. Free tier is 1,000 reads a month and takes no card.
```
export ONTO_API_KEY="onto_sk_live_YOUR_KEY"
```

Read a page

Nothing to install. Press Run, or paste it in a terminal.

POST /v1/read[curl]

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/pricing"}'

It works when
The response has a markdown field of readable text, and stats.reduction_percent says how much of the page was markup.
It didn’t work
401? The key is missing its Bearer prefix, or $ONTO_API_KEY was in single quotes and never expanded.
Every error carries a stable code — see Error codes.
NextRaw Markdown: Accept: text/markdown →Score it too: /v1/read-and-score →Give an agent the web →

Editor · 1 min

Plug into Claude Code

01
Install
Pick your client. Your agent gets six tools — read_url, read_and_score, score_url, batch, map_site, extract_data.
Install in
One command
$ claude mcp add --scope user --transport http onto https://api.buildonto.dev/mcp
Docs →
Run it in a terminal. Claude Code asks you to approve Onto on first use.
Then ask Claude Code to “read example.com with onto”.

Ask it to read a page

In a new chat.

Read https://example.com with onto and show me the Markdown.

It works when
The agent calls read_url instead of fetching the page itself, and answers from clean Markdown.
It didn’t work
The tools never show up? The config is in the wrong place — clients ignore a file they can’t find, silently. Check the path in step 1, then restart the client.
On ChatGPT or Claude on the web? They can’t run a local process — pick Paste a URL in step 1 and sign in when asked.
NextEvery client’s setup →The remote connector →Index a whole site →

Your site · 5 min

Serve your site

01
Install and scaffold
init writes onto.config.ts, middleware.ts and .env.local — skipping any that already exist.
```
npm install @ontosdk/next
npx onto-next init
```
02
Add your site key
Register the domain in Serve for its key. The variable is ONTO_API_KEY, but the value is the site’s own key — not a Read key. Set baseUrl in onto.config.ts to your real origin too.
.env.local
```
ONTO_API_KEY=onto_live_YOUR_SITE_KEY
```
03
Add the build step
After next build, onto-next writes a clean .md of every page into public/.onto/ and syncs the list to your dashboard.
package.json
```
"scripts": {
  "build": "next build && onto-next"
}
```
04
Build and deploy
The CLI prints how many pages it extracted, then deploy as usual. None extracted means the build step didn’t run.
```
npm run build
```
✓
It works when
A request with an agent’s user-agent comes back as Markdown. In a browser, add ?onto to any URL to see what agents get.
```
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
```
It didn’t work
Still HTML? Either the build step didn’t run — check public/.onto/ has files — or the middleware matcher excludes the route.
Had a middleware.ts already? init leaves it alone — call ontoMiddleware(req, ontoConfig) from yours.
“Sync skipped: Invalid API Key”? That’s a Read key in ONTO_API_KEY; it needs the site key.
NextSee which agents visit →How it works →Audit a site →

Quickstart

Get a key

Read a page

Install

Ask it to read a page

Install and scaffold

Add your site key

Add the build step

Build and deploy