POST /v1/map

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

ℹ

Plan, then act. Map a site to see what's there, then feed the URLs you want into /v1/batch or /v1/read. Discovery is sitemap-first (/sitemap.xml, including one level of sitemap-index expansion), falling back to on-page links.

Endpoint

http

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

Request body

urlstringrequiredBase URL of the site to map.

limitnumberoptionalMax URLs to return (default 100, max 1000).

Response

Success (200): a flat list of same-origin URLs and the discovery source ("sitemap" or "links").

json

{
  "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), UNAUTHORIZED (401), NO_RESULTS (404), RATE_LIMITED (429), PAYMENT_REQUIRED (402). See error codes.

Examples

cURL:

bash

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 }'