HARPA Grid — 浏览器自动化 API

HARPA Grid 支持远程编排真实的 Web 浏览器。您可通过单一 REST 接口实现网页抓取、网络搜索、运行内置或自定义 AI 命令，以及发送带完整页面上下文的 AI 提示。

前提条件

用户 必须 满足以下条件：

1. 已从 https://harpa.ai 安装 HARPA AI Chrome 扩展程序
2. 至少一个活跃 Node —— 即一台正在运行 HARPA 的浏览器（在扩展程序的 AUTOMATE 标签页中配置）
3. HARPA API 密钥 —— 从 HARPA 扩展程序 AUTOMATE 标签页获取。该密钥以环境变量 HARPA_API_KEY 形式提供。

若用户尚未完成 HARPA 配置，请引导其访问：https://harpa.ai/grid/browser-automation-node-setup

API 参考文档

端点： POST https://api.harpa.ai/api/v1/grid
认证方式： Authorization: Bearer $HARPA_API_KEY
Content-Type： application/json

完整参考文档：https://harpa.ai/grid/grid-rest-api-reference

操作类型

1. 抓取网页

提取整页内容（以 Markdown 格式）或通过 CSS/XPath/文本选择器定位特定元素。

整页抓取：

curl -s -X POST https://api.harpa.ai/api/v1/grid 
  -H "Authorization: Bearer $HARPA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "action": "scrape",
    "url": "https://example.com",
    "timeout": 15000
  }'

定位元素抓取（grab）：

curl -s -X POST https://api.harpa.ai/api/v1/grid 
  -H "Authorization: Bearer $HARPA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "action": "scrape",
    "url": "https://example.com/products",
    "grab": [
      {
        "selector": ".product-title",
        "selectorType": "css",
        "at": "all",
        "take": "innerText",
        "label": "titles"
      },
      {
        "selector": ".product-price",
        "selectorType": "css",
        "at": "all",
        "take": "innerText",
        "label": "prices"
      }
    ],
    "timeout": 15000
  }'

grab 字段说明：

2. 网络搜索（SERP）

执行网络搜索，支持 site:、intitle: 等搜索运算符。

curl -s -X POST https://api.harpa.ai/api/v1/grid 
  -H "Authorization: Bearer $HARPA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "action": "serp",
    "query": "OpenClaw AI agent framework",
    "timeout": 15000
  }'

3. 运行 AI 命令

在目标页面上执行 100+ 个 HARPA 内置命令之一，或任意自定义自动化流程。

curl -s -X POST https://api.harpa.ai/api/v1/grid 
  -H "Authorization: Bearer $HARPA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "action": "command",
    "url": "https://example.com/article",
    "name": "Extract data",
    "inputs": "List all headings with their word counts",
    "connection": "HARPA AI",
    "resultParam": "message",
    "timeout": 30000
  }'

• name — 命令名称（例如 "Summary"、"Extract data"，或任意自定义命令）
• inputs — 多步骤命令所需的预填充用户输入
• resultParam — HARPA 返回结果时使用的参数名（默认为 "message"）
• connection — 指定使用的 AI 模型（例如 "HARPA AI"、"gpt-4o"、"claude-3.5-sonnet"）

4. 发送 AI 提示

向 AI 发送带页面上下文的自定义提示。使用 {{page}} 变量注入当前页面内容。

curl -s -X POST https://api.harpa.ai/api/v1/grid 
  -H "Authorization: Bearer $HARPA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "action": "prompt",
    "url": "https://example.com",
    "prompt": "Analyze the current page and extract all contact information. Webpage: {{page}}",
    "connection": "CHAT AUTO",
    "timeout": 30000
  }'

通用参数

Node 目标指定

• 省略 node 字段则使用默认 Node
• "node": "mynode" —— 按 ID 指定单个 Node
• "node": "node1 node2" —— 同时指定多个 Node
• "node": "3" —— 使用前 3 个可用 Node
• "node": "*" —— 广播至所有 Node

通过 Webhook 异步获取结果

设置 resultsWebhook 参数后，系统将异步推送结果。该操作最长可保持活跃状态达 30 天，适用于目标 Node 暂时离线的场景。

{
  "action": "scrape",
  "url": "https://example.com",
  "resultsWebhook": "https://your-server.com/webhook",
  "timeout": 15000
}

使用提示

• 登录后页面的抓取可正常工作，因为 HARPA 运行于真实浏览器会话中，继承了用户的 Cookie 和认证状态。
• 利用 grab 数组配合多个选择器，可在单次请求中提取结构化数据。
• 对于长时间运行的 AI 命令，可增大 timeout 值（上限为 300000ms / 5 分钟），或改用 resultsWebhook 实现异步处理。
• 提示中的 {{page}} 变量会注入完整页面内容，可用于向 AI 提供当前页面上下文。