# POST /v1/map

> Discover a site's URLs — fast and cheap, without reading any pages.

Source: https://docs.buildonto.dev/api/map
Section: Read API

---

POST /v1/map\[01\]

## POST /v1/map

Discover a site's URLs without reading any pages. 1 credit per call.

**Plan, then act.** Map a site to see what's there, then feed the URLs you want into [/v1/batch](/api/batch) or [/v1/read](/api/read). Discovery reads `/sitemap.xml` at the site root. If that file is a sitemap index, Onto reads up to the first 3 nested sitemaps. Otherwise it falls back to the links on the start page.

The sitemap is always read at the root, whatever path you pass. `Sitemap:` lines in robots.txt are ignored. Each discovery fetch has an 8-second timeout and fails silently. Only URLs on the same host are kept; the scheme is not compared.

### Endpoint

\[02\]


```
POST https://api.buildonto.dev/v1/map
Authorization: Bearer onto_sk_live_YOUR_KEY
Content-Type: application/json
```

### Request body

\[03\]

urlstringreq

URL of the site to map. The links fallback reads this page.

limitnumber

Max URLs to return (default 100, max 1,000).

### Response

\[04\]

**Success (200):** `status`, `url`, the discovery `source` (`"sitemap"` or `"links"`), `count`, a flat list of same-host `urls`, and `cache`. With the links fallback, the start URL is always the first entry.

**Cached for 1 hour**, keyed on `limit` plus `url`. There is no `fresh` option. A cache hit still costs 1 credit.


```
{
  "status": "success",
  "url": "https://nodejs.org",
  "source": "sitemap",
  "count": 100,
  "urls": [
    "https://nodejs.org/en/download",
    "https://nodejs.org/en/blog",
    "https://nodejs.org/api/fs.html"
  ],
  "cache": { "hit": false, "ttl_seconds": 3600 }
}
```

**Errors:** `INVALID_URL` (400, also private or internal hosts), `UNAUTHORIZED` (401), `NO_RESULTS` (404 — in practice this does not happen, because you get at least the start URL), `RATE_LIMITED` (429), `CONCURRENT_LIMIT` (429), `PAYMENT_REQUIRED` (402). See [error codes](/api/errors).

### Examples

\[05\]

cURL:


```
curl -X POST https://api.buildonto.dev/v1/map \
  -H "Authorization: Bearer $ONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://nodejs.org", "limit": 100 }'
```

Copy as Markdown[](/api/map.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"
  }
}
```