\r \r

HARPA Grid — Browser Automation API\r

\r HARPA Grid lets you orchestrate real web browsers remotely. You can scrape pages, search the web, run built-in or custom AI commands, and send AI prompts with full page context — all through a single REST endpoint.\r \r

Prerequisites\r

\r The user must have:\r

1. HARPA AI Chrome Extension installed from https://harpa.ai\r
2. At least one active Node — a browser with HARPA running (configured in the extension's AUTOMATE tab)\r
3. A HARPA API key — obtained from the HARPA extension AUTOMATE tab. The key is provided as the HARPA_API_KEY environment variable.\r \r If the user hasn't set up HARPA yet, direct them to: https://harpa.ai/grid/browser-automation-node-setup\r \r

API Reference\r

\r Endpoint: POST https://api.harpa.ai/api/v1/grid\r Auth: Authorization: Bearer $HARPA_API_KEY\r Content-Type: application/json\r \r Full reference: https://harpa.ai/grid/grid-rest-api-reference\r \r ---\r \r

Actions\r

\r

1. Scrape a Web Page\r

\r Extract full page content (as markdown) or specific elements via CSS/XPath/text selectors.\r \r Full page scrape:\r \r

curl -s -X POST https://api.harpa.ai/api/v1/grid \\r
  -H "Authorization: Bearer $HARPA_API_KEY" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "action": "scrape",\r
    "url": "https://example.com",\r
    "timeout": 15000\r
  }'\r
```\r
\r
**Targeted element scrape (grab):**\r
\r
```bash\r
curl -s -X POST https://api.harpa.ai/api/v1/grid \\r
  -H "Authorization: Bearer $HARPA_API_KEY" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "action": "scrape",\r
    "url": "https://example.com/products",\r
    "grab": [\r
      {\r
        "selector": ".product-title",\r
        "selectorType": "css",\r
        "at": "all",\r
        "take": "innerText",\r
        "label": "titles"\r
      },\r
      {\r
        "selector": ".product-price",\r
        "selectorType": "css",\r
        "at": "all",\r
        "take": "innerText",\r
        "label": "prices"\r
      }\r
    ],\r
    "timeout": 15000\r
  }'\r
```\r
\r
**Grab fields:**\r
\r
| Field | Required | Default | Values |\r
|-------|----------|---------|--------|\r
| selector | yes | — | CSS (`.class`, `#id`), XPath (`//h2`), or text content |\r
| selectorType | no | auto | `auto`, `css`, `xpath`, `text` |\r
| at | no | first | `all`, `first`, `last`, or a number |\r
| take | no | innerText | `innerText`, `textContent`, `innerHTML`, `outerHTML`, `href`, `value`, `id`, `className`, `attributes`, `styles`, `[attrName]`, `(styleName)` |\r
| label | no | data | Custom label for extracted data |\r
\r
### 2. Search the Web (SERP)\r
\r
Perform a web search. Supports operators like `site:`, `intitle:`.\r
\r
```bash\r
curl -s -X POST https://api.harpa.ai/api/v1/grid \\r
  -H "Authorization: Bearer $HARPA_API_KEY" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "action": "serp",\r
    "query": "OpenClaw AI agent framework",\r
    "timeout": 15000\r
  }'\r
```\r
\r
### 3. Run an AI Command\r
\r
Execute one of 100+ built-in HARPA commands or a custom automation on a target page.\r
\r
```bash\r
curl -s -X POST https://api.harpa.ai/api/v1/grid \\r
  -H "Authorization: Bearer $HARPA_API_KEY" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "action": "command",\r
    "url": "https://example.com/article",\r
    "name": "Extract data",\r
    "inputs": "List all headings with their word counts",\r
    "connection": "HARPA AI",\r
    "resultParam": "message",\r
    "timeout": 30000\r
  }'\r
```\r
\r
- `name` — command name (e.g. `"Summary"`, `"Extract data"`, or any custom command)\r
- `inputs` — pre-filled user inputs for multi-step commands\r
- `resultParam` — HARPA parameter to return as result (default: `"message"`)\r
- `connection` — AI model to use (e.g. `"HARPA AI"`, `"gpt-4o"`, `"claude-3.5-sonnet"`)\r
\r
### 4. Run an AI Prompt\r
\r
Send a custom AI prompt with page context. Use `{{page}}` to inject the page content.\r
\r
```bash\r
curl -s -X POST https://api.harpa.ai/api/v1/grid \\r
  -H "Authorization: Bearer $HARPA_API_KEY" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "action": "prompt",\r
    "url": "https://example.com",\r
    "prompt": "Analyze the current page and extract all contact information. Webpage: {{page}}",\r
    "connection": "CHAT AUTO",\r
    "timeout": 30000\r
  }'\r
```\r
\r
---\r
\r
## Common Parameters\r
\r
| Parameter | Required | Default | Description |\r
|-----------|----------|---------|-------------|\r
| action | yes | — | `scrape`, `serp`, `command`, or `prompt` |\r
| url | no | — | Target page URL (ignored by `serp`) |\r
| node | no | — | Node ID (`"r2d2"`), multiple (`"r2d2 c3po"`), first N (`"5"`), or all (`"*"`) |\r
| timeout | no | 300000 | Max wait time in ms (max 5 minutes) |\r
| resultsWebhook | no | — | URL to POST results to asynchronously (retained 30 days) |\r
| connection | no | — | AI model for `command`/`prompt` actions |\r
\r
## Node Targeting\r
\r
- Omit `node` to use the default node\r
- `"node": "mynode"` — target a specific node by ID\r
- `"node": "node1 node2"` — target multiple nodes\r
- `"node": "3"` — use first 3 available nodes\r
- `"node": "*"` — broadcast to all nodes\r
\r
## Async Results via Webhook\r
\r
Set `resultsWebhook` to receive results asynchronously. The action stays alive for up to 30 days, useful when target nodes are temporarily offline.\r
\r
```json\r
{\r
  "action": "scrape",\r
  "url": "https://example.com",\r
  "resultsWebhook": "https://your-server.com/webhook",\r
  "timeout": 15000\r
}\r
```\r
\r
## Tips\r
\r
- Scraping behind-login pages works because HARPA runs inside a real browser session with the user's cookies and auth state.\r
- Use the `grab` array with multiple selectors to extract structured data in a single request.\r
- For long-running AI commands, increase `timeout` (max 300000ms / 5 min) or use `resultsWebhook`.\r
- The `{{page}}` variable in prompts injects the full page content — use it to give AI context about the current page.\r