Firehose API

Firehose 实时监控全网内容。您可在tap上创建规则（Lucene 查询），所有被爬取且匹配该规则的网页，都会通过 Server-Sent Events（SSE）流实时推送到该 tap。（URL Watch —— 即对固定页面列表进行变更追踪 —— 是另一款独立产品；详见文末文档索引。）

本文档内联覆盖了 Stream API 的常见操作，使您无需额外请求即可直接执行。如需查阅完整的 Lucene 字段语义、全部分类/类型标签列表、校验契约（validate contract）、URL Watch 功能及计费说明，请参阅文末Documentation下的相关链接——该部分文档由线上文档自动生成，始终保持最新。

认证

基础 URL：https://api.firehose.com。使用 Bearer Token 认证，共两类（均通过 Firehose 控制台发放）：

• 管理密钥（Management key）（前缀 fhm_）：用于创建、列出、更新和删除 tap；不可管理规则或开启流式连接。
• tap token（前缀 fh_）：用于管理某一个 tap 上的规则，并开启其 SSE 流。

Authorization: Bearer fh_your_tap_token

端点（Endpoints）

tap 管理 —— 使用管理密钥：

暂停 tap：向 PUT /v1/taps/:id 发送 {"status":"paused"}；恢复：发送 {"status":"active"}。
已暂停的 tap 会保留全部规则，但不再匹配任何页面，也不会推送更新；恢复后将重新激活所有规则，若超出当前套餐允许的活跃 tap 数量上限，则可能返回 422 错误。

删除 tap 是永久性操作：立即吊销该 tap 的 token，并删除其所有规则。请在删除前向用户确认——若仅需临时停用，请选择暂停而非删除。

规则与流式连接 —— 使用 tap token：

删除规则为永久性操作，匹配行为将立即停止。请在删除前向用户确认。

规则与查询

一条规则对象包含以下字段：value（Lucene 查询，必填）、tag（标签，可选，≤255 字符）、nsfw（布尔值，默认 false）、quality（布尔值，默认 true —— 自动过滤分页内容、分类/标签页及过期页面）。

查询语法基于Lucene ClassicQueryParser。默认字段为 added（插入差异块中的文本）。关键字段如下：

• 文本字段（分词、不区分大小写）：added、removed、added_anchor、removed_anchor、title
• 关键词字段（精确匹配、区分大小写）：url、domain、publish_time、page_category、page_type、language
• 数值字段（支持范围查询）：dr —— Ahrefs Domain Rating（0–100）
• 时间窗口过滤器：recent:h|d|mo —— 仅匹配发布于指定时间窗口内的页面

支持的操作符：AND、OR、NOT、"exact phrases"；在 url/domain 字段上还支持通配符（*、?）和正则表达式（/.../）—— 正则中需对 / 进行转义（即写为 \/，在 JSON 中应写作 \\/）。示例查询：

tesla AND language:en
title:tesla AND page_category:"/News" AND recent:24h
domain:techcrunch.com AND NOT url:*/tag/*

流式连接（SSE）

GET /v1/stream 推送四种事件类型：connected（连接建立）、update（命中匹配）、error（错误）、end（超时或达到限制 —— 需重连以继续接收）。其中 update 事件的 data 字段为 { tap_id, query_id, matched_at, document }，其中 document 包含：url、title、publish_time、diff.chunks[]（{ typ: "ins"|"del", text }）、page_category[]、page_types[]、language、domain_rating 和 markdown。空值或缺失字段将被省略。

示例

# 创建 tap（使用管理密钥）—— 响应中包含新生成的 tap token
curl -s -X POST -H "Authorization: Bearer $FIREHOSE_MANAGEMENT_KEY" 
  -H "Content-Type: application/json" -d '{"name":"Brand Mentions"}' 
  https://api.firehose.com/v1/taps

# 创建规则，随后列出该 tap 的所有规则（使用 tap token）
curl -s -X POST -H "Authorization: Bearer $FIREHOSE_TAP_TOKEN" 
  -H "Content-Type: application/json" -d '{"value":"ahrefs OR semrush","tag":"seo"}' 
  https://api.firehose.com/v1/rules
curl -s -H "Authorization: Bearer $FIREHOSE_TAP_TOKEN" https://api.firehose.com/v1/rules

# 开启匹配流（保持连接打开）
curl -N -H "Authorization: Bearer $FIREHOSE_TAP_TOKEN" https://api.firehose.com/v1/stream

速率限制与错误码

/v1/rules —— 每个 tap 每分钟最多 60 次请求。
/v1/stream —— 每个 tap 每分钟最多 30 个并发连接。
常见错误码：401（Token 无效或缺失）、403（资源不属于当前组织）、404（未找到）、422（校验失败）、429（超出速率限制）。

文档

完整文档。每个链接均为对应页面的原始 Markdown 文件 —— 可在任意页面 URL 后添加 .md 后缀访问。对于本文未涵盖的内容，请查阅相应页面。

入门

• 简介：Firehose 是什么、面向哪些用户、其实时流水线如何将您的规则转化为匹配网页的实时流，以及后续学习路径。
• 快速开始：约五分钟内从零起步，完成管理密钥获取、tap 创建、规则添加及流开启，获得实时匹配流。
• 核心概念：Firehose 中涉及的关键对象 —— 组织（organizations）、tap、规则（rules）、匹配项（matches）、密钥（keys）及 URL Watch —— 以及它们之间的关系。
• Stream vs URL Watch：Firehose 提供两种网页监控方式 —— Stream 对全量爬取结果应用规则匹配，URL Watch 则跟踪固定 URL 列表的变更。请根据需求选择合适方式。
• 认证：管理密钥（fhm_）与 tap token（fh_）的区别、各自权限范围、API 基础 URL，以及如何在请求中以 Bearer Token 方式传递。

Stream

• Stream 概览：Firehose 的核心产品 —— 您的规则将应用于每一次爬取结果，匹配项通过实时 SSE 流推送。适用场景与匹配逻辑说明。
• 规则与查询语法：在 tap 上执行规则的增删改查（CRUD），以及所支持的完整查询语言规范。
• 流式连接（SSE）：建立 Server-Sent Events 连接、正确传递查询参数、处理各类事件、断线后无丢失重连的最佳实践。
• 匹配数据结构（Match payload）：详解 update 事件中每个字段及所携带的页面文档结构，附带示例载荷与完整分类/类型标签列表。

URL Watch

• URL Watch 概览：按计划轮询指定 URL 列表并捕获两次爬取间的差异。何时选用 URL Watch 而非 Stream，及其工作原理。
• 创建监控项（Creating watches）：添加单个待监控 URL、设置爬取频率、预览渲染效果、检查状态，或批量导入 URL 列表。
• 差异比对与爬取历史（Diffs & crawl history）：查看某监控 URL 两次爬取间的变更详情（包括新增与删除内容），并浏览其历史爬取记录。
• 配额与限制（Quotas & limits）：各套餐每月检查次数配额、监控 URL 数量上限、最快爬取频率，以及监控项达到限制时 Firehose 的行为表现。

控制台（Dashboard）

• 实时动态流（The live feed）：在控制台中实时查看匹配项到达情况，边流式接收边人工审核，保存重要匹配项，并导出所选结果供后续分析。
• 筛选器与域名列表（Filters & domain lists）：可复用的查询片段及绑定至 tap 的域名/URL 列表，用于精细调控匹配范围 —— 同时支持 AI 辅助生成查询。

组织与权限（Organizations & Access）

• tap：tap 是拥有规则集并可从中开启流的 API token（fh_）。建议按业务场景划分独立 tap，并掌握其创建与管理方法。
• 管理密钥（Management keys）：组织级凭证（fhm_），用于编程方式创建和管理 tap —— 如何生成、权限范围及适用场景。

计费（Billing）

• 套餐与定价（Plans & pricing）：Firehose 从 Free 到 Business 的订阅层级，以及纯 API 计划 —— 各档包含功能、配额及适用客户类型。
• 计费机制（How billing works）：预付费余额、按匹配计费、月度额度三者的关系 —— 何种匹配计入账单、何种不计入，以及各项配额的关联逻辑。

API 参考（API reference）

• 管理密钥端点（Management-key endpoints）：使用组织管理密钥（fhm_）通过 HTTP 执行 tap 的列表、创建、获取、更新与吊销操作，含各接口请求/响应结构定义。
• URL Watch 端点（URL Watch endpoints）：使用组织管理密钥（fhm_）通过 HTTP 执行 URL Watch 订阅的列表、创建、更新、删除及爬取差异读取操作。
• tap token 端点（Tap-token endpoints）：使用 tap token（fh_）执行规则的增删改查及 SSE 流开启操作 —— 接口参考、参数说明与 tap 级别速率限制。
• 查询校验（Validate a query）：在保存为规则前，将 Lucene 查询提交至 query-core 进行有效性验证 —— 返回校验结果、诊断信息及编译后的查询表达式；另提供无需认证的公开接口（/v1/validate/public）供试用页面调用。
• 错误与限制（Errors & limits）：API 所有返回的 HTTP 状态码、各端点及流连接的速率限制，以及 SSE 流关闭前发出的错误事件类型。
• 代码示例（Code examples）：涵盖 tap、规则、流式连接与 URL Watch 的端到端代码片段，支持 curl、JavaScript 与 Python —— 可直接复制、粘贴并适配您自己的密钥使用。

故障排查（Troubleshooting）

• 为何没有收到匹配项？（Why am I not getting matches?）：流或控制台持续为空的常见原因 —— 爬取覆盖率不足、url: 过滤器误设、quality 过滤启用、recent: 时间窗口过窄、查询条件过于严格，或账户余额不足。
• 流连接中断或报错（Stream disconnects or errors）：流意外关闭或返回 401、402、429 等错误的原因，事件“跳过”现象的成因，以及各类异常（含连接意外中断）的恢复策略。

资源（Resources）

• 将 Firehose 与 AI Agent 结合使用（Using Firehose with AI agents）：将本文档与 Firehose API 提供给大语言模型（LLM）或编码 Agent，支持按页 Markdown、全站 llms.txt 文件及可安装的 API 技能（API skill）三种接入方式。

完整文档单文件版：llms-full.txt。