A single page, a site corpus and an authenticated workflow are different jobs. Forcing them through the same long-lived browser makes the integration harder to operate.
Start from scope and state.
| Need | Primitive | Why |
|---|---|---|
| One known URL | /v1/scrape | One bounded render and extraction result. |
| Many pages on one origin | /v1/crawl | Depth, page and path limits stay explicit. |
| Clicks or form input | /v1/browse | Actions are ordered, metered and observable. |
| Login state across calls | /v1/sessions | The encrypted cookie jar stays server-side. |
| Find content in a crawl | /v1/search | Search remains private to its crawl owner. |
Keep each request bounded.
curl https://www.crawlvolt.com/v1/crawl \\
-H "Authorization: Bearer $CRAWLVOLT_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{
"url": "https://docs.example.com",
"max_pages": 25,
"max_depth": 2,
"include_paths": ["/guides/**"]
}'The crawl stays on the exact origin, skips binary assets and applies include filters before excludes. Successful pages use the same output model and page quota as scrape.
Escalate capability only when the workflow needs it.
Selection rule
Scrape before crawl. Crawl before browse. Add a persistent session only when state must survive across requests.
This ordering minimizes browser time, narrows failure scope and makes retries easier to reason about.