---
name: vessel
description: Use a CrawlGenie workspace to search, read, extract and act on the web from an AI agent with the fewest tokens. Read this file first; it tells you how to authenticate and which call to make for which job.
---

# CrawlGenie — browser layer for agents (skill)

CrawlGenie is a platform that runs real Chromium browsers and returns **compact, agent-ready data**:
ranked snapshots instead of HTML, markdown instead of pages, structured rows instead of browsing.

## 1. Connect

- Base URL: the `VESSEL_URL` environment variable (for example `https://crawlgenie.com`), or `http://localhost:7070` in development.
- Key: `VESSEL_API_KEY`, sent as `Authorization: Bearer <key>`. Keys are created in the dashboard under **API keys**.
- MCP: `POST <base>/mcp` (Streamable HTTP) with the same bearer header exposes every capability below as tools.
- OpenAPI: `GET <base>/openapi.json`. Dashboard: `<base>/`.

## 2. Pick the cheapest call that answers the question

| You need | Call | Why it is cheap |
|---|---|---|
| Structured rows from a known site type (jobs, reviews, places, products, posts, papers, filings, search) | `POST /v1/extractors/{id}/run {"input":{…}}` — list ids with `GET /v1/extractors` | No page reading at all; rows cost ~1–5% of browsing the pages |
| The answer to a question that lives on one page | `POST /v1/scrape {"url":…, "format":"markdown", "q":"<your question>"}` | `q` keeps only the passages that match; typically 5–15% of the page |
| A page as markdown | `POST /v1/scrape {"url":…}` | Readability-grade main content, boilerplate removed |
| A PDF or DOCX | `POST /v1/parse {"url":…}` or `/v1/scrape` with the document URL | Text layer, no rendering, no browser |
| Web search | `GET /v1/search?q=…&content=true` | Results plus markdown of the top hits in one call |
| Many pages of a site | `POST /v1/crawl {"url":…, "limit":50}` then `GET /v1/crawl/{id}` | Parallel workers, dedup, markdown per page |
| Interact: click, type, log in, paginate | `POST /v1/sessions` → `POST /v1/sessions/{id}/act` → `GET /v1/sessions/{id}/snapshot?mode=interactive` | Snapshot is a ranked list of interactive elements with refs, not the DOM |
| Something recurring with alerts | `POST /v1/watches {"kind":…, "input":…, "cron":"0 8 * * *", "webhookUrl":…}` | Server keeps state and tells you only what changed |

## 3. Rules that save tokens and failures

1. Start with `GET /v1/extractors` and `GET /v1/playbooks`: if a built-in agent covers the task, use it instead of browsing.
2. Use `mode=interactive` snapshots and `delta=true` after each action; never request raw HTML unless debugging.
3. Pass `q` on `/v1/scrape` and `/v1/sessions/{id}/text` whenever you have a specific question.
4. If a response carries `challenge` (CAPTCHA, login wall, access denied), stop retrying. Report it; a human can take over at `<base>/sessions/{id}` or a proxy pool / login profile can be attached (`session.proxy.pool`, `session.profile`).
5. Close sessions you created (`DELETE /v1/sessions/{id}`) or let the idle timeout do it.
6. Secrets are never typed by you: use `{{secret:name}}` in `fill` actions and the server substitutes them.

## 4. Minimal examples

```bash
curl -H "Authorization: Bearer $VESSEL_API_KEY" "$VESSEL_URL/v1/extractors"
curl -X POST -H "Authorization: Bearer $VESSEL_API_KEY" -H "content-type: application/json" \
  "$VESSEL_URL/v1/extractors/google_maps_places/run" -d '{"input":{"query":"dentists in Austin","max":20}}'
curl -X POST -H "Authorization: Bearer $VESSEL_API_KEY" -H "content-type: application/json" \
  "$VESSEL_URL/v1/scrape" -d '{"url":"https://example.com/pricing","q":"price per month for the team plan"}'
```

SDKs: `npm i vessel-browser-sdk` (TypeScript) · `pip install vessel-browser` (Python) · CLI: `npx vessel-browser-sdk --help`.

## 5. Remember instead of re-reading; several sources; privacy; help

- **Knowledge**: `POST /v1/knowledge {name}` once, then `POST /v1/knowledge/{id}/documents {url | urls | text | crawlId}`; later `POST /v1/knowledge/search {q}` returns the passages that answer (a few hundred tokens) instead of the sources. MCP: `knowledge_add`, `knowledge_search`.
- **Compare sources**: `POST /v1/answer {urls:[…], q}` (or `web_research {urls}`) — one budget across pages and documents.
- **Documents**: `/v1/parse` and `/v1/scrape` read PDF (text or OCR), DOCX/XLSX/PPTX, ODT/ODS/ODP, RTF, images (OCR), Google Docs/Sheets/Slides links, YouTube (captions). Options: `pages`, `granularity: "sentence"`, `redactPII`, `cache: "prefer"`.
- **Docs for you**: `GET /llms.txt`, `GET /docs/<slug>.md`, `POST /help/ask {q}` (no key) — or the `vessel_help` tool.
- **Identity**: this server can sign its navigations (Web Bot Auth, `policy.signedAgent`); sites that support it can recognise the agent instead of challenging it.