# Quickstart

> Pick a route — the API, your editor, or your own site. Each is a few stops and ends with a check that it worked.

Source: https://docs.buildonto.dev/quickstart
Section: Start

---

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.

API30 secCall the APIOne POST, Markdown back.Editor1 minPlug into Claude CodeYour agent calls Onto itself.Your site5 minServe your siteAgents get Markdown, people get the page.

1.  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.
    
    Sign in
    
    
    ```
    export ONTO_API_KEY="onto_sk_live_YOUR_KEY"
    ```
    
2.  02
    
    ### Read a page
    
    Nothing to install. Press Run, or paste it in a terminal.
    
    
    ```
    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"}'
    ```
    
3.  ✓
    
    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 worked
    
    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](/api/errors).
    

1.  01
    
    ### Install
    
    Pick your client. Your agent gets six tools — `read_url`, `read_and_score`, `score_url`, `batch`, `map_site`, `extract_data`.
    
    Install in
    
    ![](/integrations/claude-code.png)Claude Code
    
    One command
    
    $ claude mcp add --scope user --transport http onto https://api.buildonto.dev/mcp
    
    Copy command[Docs →](https://docs.buildonto.dev/mcp/claude-code)
    
    1.  Run it in a terminal. Claude Code asks you to approve Onto on first use.
    2.  Then ask Claude Code to “read example.com with onto”.
    
2.  02
    
    ### Ask it to read a page
    
    In a new chat.
    
    
    ```
    Read https://example.com with onto and show me the Markdown.
    ```
    
3.  ✓
    
    It works when
    
    The agent calls `read_url` instead of fetching the page itself, and answers from clean Markdown.
    
    It worked
    
    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.
    

1.  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
    ```
    
2.  02
    
    ### Add your site key
    
    Register the domain in [Serve](https://app.buildonto.dev/serve/dashboard) 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.
    
    text.env.localCopy
    
    ```
    ONTO_API_KEY=onto_live_YOUR_SITE_KEY
    ```
    
3.  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.
    
    jsonpackage.jsonCopy
    
    ```
    "scripts": {
      "build": "next build && onto-next"
    }
    ```
    
4.  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
    ```
    
5.  ✓
    
    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 worked
    
    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.
    

Copy as Markdown[](/quickstart.md "Open the raw Markdown")

---
## Structured Data (JSON-LD)
```json
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "Onto Docs",
  "url": "https://docs.buildonto.dev",
  "description": "How to use Onto: serve AI agents Markdown from your Next.js site, call the Read API, connect over MCP, and read the AIO score.",
  "inLanguage": "en",
  "publisher": {
    "@type": "Organization",
    "name": "Onto",
    "url": "https://buildonto.dev"
  }
}
```