Firehose

https://docs.firehose.com
Admin
Firehose monitors the web in real time, allowing users to create rules and receive matching crawled...
Tokens:51,372
Snippets:554
Trust Score:6.2
Update:4 months ago
Show doc for...
Tokens:
Raw
### Create Rule Body Example

Source: https://docs.firehose.com/api-reference/tap-token-endpoints.md

Example JSON body for creating a new rule, specifying the query value, tag, and quality settings.

```json
{ "value": "tesla OR \"electric vehicle\"", "tag": "ev", "nsfw": false, "quality": true }
```

--------------------------------

### Create Tap Response Example

Source: https://docs.firehose.com/skill.md

Example JSON response when creating a tap, including tap ID, name, token prefix, and creation timestamp. The full token is also returned.

```json
{
    "data": { "id": "uuid", "name": "Brand Mentions", "token_prefix": "fh_abc", "created_at": "..." },
    "token": "fh_the_full_tap_token"
}
```

--------------------------------

### List Taps Response Example

Source: https://docs.firehose.com/api-reference/management-key-endpoints.md

Example JSON response when listing taps, showing tap details including ID, name, token, and creation timestamp.

```json
{
  "data": [
    {
      "id": "uuid",
      "name": "Brand Mentions",
      "token": "fh_full_tap_token",
      "token_prefix": "fh_abc",
      "rules_count": 3,
      "last_used_at": null,
      "created_at": "2026-02-27T00:00:00+00:00"
    }
  ]
}
```

--------------------------------

### JavaScript Stream Example

Source: https://docs.firehose.com/skill.md

Example of how to stream data using JavaScript (Node.js or browser with EventSource polyfill).

```javascript
const EventSource = require('eventsource'); // npm install eventsource

const es = new EventSource('https://api.firehose.com/v1/stream', {
    headers: { Authorization: `Bearer ${process.env.FIREHOSE_TAP_TOKEN}` },
});

es.addEventListener('update', (event) => {
    const { query_id, matched_at, document } = JSON.parse(event.data);
    console.log(`[${matched_at}] Rule ${query_id}: ${document.url}`);
});

es.addEventListener('error', (event) => {
    console.error('Stream error:', event.data);
});
```

--------------------------------

### Example Stream Rule Syntax

Source: https://docs.firehose.com/llms-full.txt

This example shows the syntax for a Firehose Stream rule, combining keywords like 'title', 'page_category', and 'recent' to define matching criteria.

```text
Rule:  title:tesla AND page_category:"/News" AND recent:24h
```

--------------------------------

### Stream Firehose Data with Node.js

Source: https://docs.firehose.com/skill.md

This Node.js example uses the 'eventsource' npm package to connect to the Firehose stream and listen for 'update' events. Ensure you have the package installed and FIREHOSE_TAP_TOKEN set.

```javascript
// Note: native EventSource does not support custom headers.
// Use the 'eventsource' npm package or fetch-based SSE for auth support.
const EventSource = require('eventsource'); // npm install eventsource

const es = new EventSource('https://api.firehose.com/v1/stream', {
    headers: { Authorization: `Bearer ${process.env.FIREHOSE_TAP_TOKEN}` },
});

es.addEventListener('update', (event) => {
    const { query_id, matched_at, document } = JSON.parse(event.data);
    console.log(`[${matched_at}] Rule ${query_id}: ${document.url}`);
});

es.addEventListener('error', (event) => {
    console.error('Stream error:', event.data);
});
```

--------------------------------

### List Taps Response Example

Source: https://docs.firehose.com/skill.md

Example JSON response when listing taps, including tap ID, name, token prefix, rule count, and timestamps.

```json
{
    "data": [
        {
            "id": "uuid",
            "name": "Brand Mentions",
            "token": "fh_full_tap_token",
            "token_prefix": "fh_abc",
            "rules_count": 3,
            "last_used_at": null,
            "created_at": "2026-02-27T00:00:00+00:00"
        }
    ]
}
```

--------------------------------

### Example Rule and Match Flow

Source: https://docs.firehose.com/stream/overview.md

Illustrates a sample rule and the process of evaluating crawled pages against active rules to produce a match event.

```text
Rule:  title:tesla AND page_category:"/News" AND recent:24h
          │
          ▼
Every crawled page is evaluated against all active rules on the tap
          │
          ▼
Match ──▶ update event on GET /v1/stream
```

--------------------------------

### AI Query Generation Example

Source: https://docs.firehose.com/dashboard/filters.md

An example of AI-generated query from a plain-language description, including exclusion of pagination pages.

```text
"EV news in English, last 24h, no pagination"
        │  generate
        ▼
title:"electric vehicle" AND language:"en" AND recent:24h
  AND NOT url:/.*\/page\/[0-9]+.*/
```

--------------------------------

### Basic Query Syntax Examples

Source: https://docs.firehose.com/stream/rules.md

Demonstrates basic Firehose query syntax for searching indexed fields. Queries are evaluated against indexed fields extracted from crawled pages.

```text
tesla                        # "tesla" anywhere in added content (default field)
title:tesla                  # "tesla" in the title
"quick brown fox"            # exact phrase in content
title:"breaking news"        # exact phrase in title
```

--------------------------------

### Stream Event Example

Source: https://docs.firehose.com/get-started/quickstart

Example of a connected event followed by an update event from the Firehose stream. The update event contains details about the matched page, including its URL, title, and content diff.

```text
event: connected
data: {}

id: 0-43368
event: update
data: {"query_ids":["1"],"matched_at":"2026-02-13T08:06:32Z","tap_id":"1","document":{"url":"https://example.com/news/tesla-q4-earnings","title":"Tesla Q4 earnings beat expectations","publish_time":"2026-02-13T07:58:11","diff":{"chunks":[{"typ":"ins","text":"Tesla reported record Q4 deliveries…"}]},"page_category":["/News"],"page_types":["/Article"],"language":"en"}}
```

--------------------------------

### URL and Domain Filtering Examples

Source: https://docs.firehose.com/stream/rules.md

Shows how to filter search results by URL and domain using exact, wildcard, and regex matching. Remember to escape forward slashes in URLs with `\/`.

```text
url:"https://example.com/news/article-1"   # exact
domain:techcrunch.com                       # exact domain
url:*\/category\/*                          # wildcard: contains /category/
url:/.*\/page\/[0-9]+.*/                     # regex: pagination URLs
```

```text
title:tesla AND language:"en"
  AND NOT url:/.*\/page\/[0-9]+.*
  AND NOT url:*\/category\/*
  AND NOT url:*\/tag\/*
```

--------------------------------

### Add a rule

Source: https://docs.firehose.com/get-started/quickstart

Rules are written in Firehose query syntax. This example matches pages whose content mentions Tesla, published in the last 24 hours.

```APIDOC
## POST /v1/rules

### Description
Adds a rule to filter the stream content. Rules are written in Firehose query syntax.

### Method
POST

### Endpoint
https://api.firehose.com/v1/rules

### Parameters
#### Request Body
- **value** (string) - Required - The rule definition in Firehose query syntax.
- **tag** (string) - Optional - A tag to associate with the rule.
```

--------------------------------

### Firehose API Authentication Headers

Source: https://docs.firehose.com/get-started/authentication.md

Examples of how to format the Authorization header for management keys and tap tokens.

```text
Authorization: Bearer fhm_your_management_key
Authorization: Bearer fh_your_tap_token
```

--------------------------------

### List, Create, Get, Update, and Delete Tap Rules

Source: https://docs.firehose.com/llms-full.txt

These are the basic HTTP methods for managing rules associated with a tap. Use POST to create new rules with specified values, tags, and quality settings. Use GET to retrieve a specific rule by its ID. Use PUT for partial updates and DELETE to remove a rule.

```text
GET    /v1/rules        # list
POST   /v1/rules        # create
GET    /v1/rules/:id    # get
PUT    /v1/rules/:id    # update (partial)
DELETE /v1/rules/:id    # delete (204)
```

--------------------------------

### Boolean Operator Examples

Source: https://docs.firehose.com/stream/rules.md

Illustrates the use of boolean operators AND, OR, and NOT for constructing complex queries. Ensure at least one positive term is included in the query.

```text
java AND programming
title:tesla OR added:"electric vehicle"
title:tesla AND NOT malware    # tesla, excluding pages that mention malware
title:tesla AND added:earnings
removed:"old feature"          # term appeared in deleted content
```

--------------------------------

### Download Whole-Site Documentation

Source: https://docs.firehose.com/resources/ai-agents.md

Use curl to download the entire documentation as a single file. This is useful for providing a comprehensive knowledge base to an agent.

```bash
curl https://docs.firehose.com/llms-full.txt
```

--------------------------------

### Stream Error Event Example

Source: https://docs.firehose.com/api-reference/errors-and-limits.md

An example of an error event received from the SSE stream. This format is used for errors occurring during an active stream connection.

```text
event: error
data: {"message":"No rules configured. Create rules first via POST /v1/rules."}
```

--------------------------------

### List Rules

Source: https://docs.firehose.com/stream/rules.md

Use this endpoint to retrieve all rules associated with a tap. Ensure you have your tap token for authentication.

```bash
curl -s https://api.firehose.com/v1/rules \
  -H "Authorization: Bearer $FIREHOSE_TAP_TOKEN"
```

--------------------------------

### Set Environment Variables

Source: https://docs.firehose.com/api-reference/examples.md

Set your Firehose management and tap tokens as environment variables before running other commands.

```bash
export FIREHOSE_MGMT_KEY=fhm_your_management_key
export FIREHOSE_TAP_TOKEN=fh_your_tap_token
```

--------------------------------

### Get Rule

Source: https://docs.firehose.com/skill.md

Retrieves a specific rule by its ID.

```APIDOC
## GET /v1/rules/:id

### Description
Retrieves a specific rule by its ID.

### Method
GET

### Endpoint
/v1/rules/:id

### Parameters
#### Path Parameters
- **id** (string) - Required: The ID of the rule to retrieve.
```

--------------------------------

### Create a Tap (curl)

Source: https://docs.firehose.com/api-reference/examples.md

Use the management key to create a new tap. This operation returns a tap token.

```bash
# Create a tap (management key) — returns a tap token
curl -s -X POST https://api.firehose.com/v1/taps \
  -H "Authorization: Bearer $FIREHOSE_MGMT_KEY" \
  -H "Content-Type: application/json" -d '{"name": "Brand Mentions"}'
```

--------------------------------

### Get tap

Source: https://docs.firehose.com/api-reference/management-key-endpoints.md

Retrieves details for a specific tap identified by its ID.

```APIDOC
## GET /v1/taps/:id

### Description
Retrieves details for a specific tap identified by its ID.

### Method
GET

### Endpoint
/v1/taps/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the tap to retrieve.
```

--------------------------------

### Get Rule by ID

Source: https://docs.firehose.com/skill.md

Retrieve a specific rule by its ID. Requires a tap token.

```http
GET /v1/rules/:id
```

--------------------------------

### Get Specific Rule

Source: https://docs.firehose.com/api-reference/tap-token-endpoints.md

Retrieves a specific rule by its ID. Requires a tap token.

```text
GET    /v1/rules/:id
```

--------------------------------

### Enumerate and Provision Taps with Management Key

Source: https://docs.firehose.com/organizations/management-keys.md

Use a management key to list existing taps and their tokens, or to provision new taps via the API. Ensure the Authorization header includes your management key.

```bash
# Enumerate taps (and their full tokens)
curl -s https://api.firehose.com/v1/taps -H "Authorization: Bearer $FIREHOSE_MGMT_KEY"
```

```bash
# Provision a new tap
curl -s -X POST https://api.firehose.com/v1/taps \
  -H "Authorization: Bearer $FIREHOSE_MGMT_KEY" \
  -H "Content-Type: application/json" -d '{"name": "Brand mentions"}'
```

--------------------------------

### Create a URL Watch (curl)

Source: https://docs.firehose.com/api-reference/examples.md

Use the management key to create a URL watch. This schedules a crawl for a specific URL at a given frequency.

```bash
# Create a watch (management key) — crawl https://example.com/pricing every 6 hours
curl -s -X POST https://api.firehose.com/v1/url-watch \
  -H "Authorization: Bearer $FIREHOSE_MGMT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/pricing", "frequency_minutes": 360}'
```

--------------------------------

### Get Tap Request

Source: https://docs.firehose.com/api-reference/management-key-endpoints.md

Use this endpoint to retrieve details for a specific tap by its ID.

```text
GET /v1/taps/:id
```

--------------------------------

### Create a new URL watch subscription

Source: https://docs.firehose.com/api-reference/url-watch-endpoints.md

Use this endpoint to create a new subscription for monitoring a URL. Both 'url' and 'frequency_minutes' are required. The 'url' must be a valid URL, and 'frequency_minutes' must be an allowed value for your plan. A '201' response indicates success, with the first crawl queued immediately.

```text
POST /v1/url-watch
Content-Type: application/json

{ "url": "https://example.com/pricing", "frequency_minutes": 360 }
```

--------------------------------

### Management Key API Operations

Source: https://docs.firehose.com/skill.md

Examples of using a management key to interact with Firehose API for managing taps.

```APIDOC
## List Taps
### Description
Lists all available taps associated with your account.
### Method
GET
### Endpoint
/v1/taps

## Create Tap
### Description
Creates a new tap. Returns a tap token which is used to manage rules and stream data.
### Method
POST
### Endpoint
/v1/taps
### Request Body
- **name** (string) - Required - The name of the tap.
### Request Example
```json
{
  "name": "Brand Mentions"
}
```

## Revoke Tap
### Description
Revokes an existing tap.
### Method
DELETE
### Endpoint
/v1/taps/{TAP_UUID}
### Parameters
#### Path Parameters
- **TAP_UUID** (string) - Required - The unique identifier of the tap to revoke.
```

--------------------------------

### Stream Matches (JavaScript)

Source: https://docs.firehose.com/api-reference/examples.md

Stream data matches using the EventSource API in Node.js. Ensure you have the 'eventsource' package installed.

```javascript
// Native EventSource can't send headers — use the `eventsource` package.
import EventSource from 'eventsource'; // npm install eventsource

const es = new EventSource('https://api.firehose.com/v1/stream', {
  headers: { Authorization: `Bearer ${process.env.FIREHOSE_TAP_TOKEN}` },
});

es.addEventListener('update', (event) => {
  const { query_ids, matched_at, document } = JSON.parse(event.data);
  console.log(`[${matched_at}] rules ${query_ids.join(', ')}: ${document.url}`);
});

es.addEventListener('error', (event) => console.error('stream error:', event.data));
```

--------------------------------

### Firehose Pipeline Overview

Source: https://docs.firehose.com/get-started/introduction.md

This diagram illustrates the basic flow of the Firehose pipeline: rule creation, page evaluation, and streaming matches.

```text
You create rules ──▶ Firehose evaluates every crawled page ──▶ Matches stream to you (SSE)
```

--------------------------------

### Tap Token API Operations

Source: https://docs.firehose.com/skill.md

Examples of using a tap token to interact with Firehose API for managing rules and streaming data.

```APIDOC
## List Rules
### Description
Lists all rules associated with the tap.
### Method
GET
### Endpoint
/v1/rules

## Create Rule
### Description
Creates a new rule for the tap.
### Method
POST
### Endpoint
/v1/rules
### Request Body
- **value** (string) - Required - The rule condition (e.g., a keyword, phrase, or field-specific query).
- **tag** (string) - Required - A tag to associate with the rule.
- **quality** (boolean) - Optional - Whether to enable quality filtering (defaults to true).
### Request Example
```json
{
  "value": "ahrefs",
  "tag": "brand"
}
```
```json
{
  "value": "title:tesla AND page_category:\"/News\"",
  "tag": "market-news"
}
```
```json
{
  "value": "title:tesla AND recent:24h",
  "tag": "market-raw",
  "quality": false
}
```

## Get Rule
### Description
Retrieves a specific rule by its ID.
### Method
GET
### Endpoint
/v1/rules/{RULE_ID}
### Parameters
#### Path Parameters
- **RULE_ID** (string) - Required - The unique identifier of the rule.

## Update Rule
### Description
Updates an existing rule.
### Method
PUT
### Endpoint
/v1/rules/{RULE_ID}
### Parameters
#### Path Parameters
- **RULE_ID** (string) - Required - The unique identifier of the rule.
### Request Body
- **tag** (string) - Optional - The new tag for the rule.
### Request Example
```json
{
  "tag": "new-tag"
}
```

## Delete Rule
### Description
Deletes a specific rule by its ID.
### Method
DELETE
### Endpoint
/v1/rules/{RULE_ID}
### Parameters
#### Path Parameters
- **RULE_ID** (string) - Required - The unique identifier of the rule.

## Stream Matching Pages
### Description
Streams matching pages in real-time. The connection remains open until closed by the client or server.
### Method
GET
### Endpoint
/v1/stream
### Query Parameters
- **timeout** (integer) - Optional - The timeout in seconds for the stream connection.
### Response Example
(Data is streamed as Server-Sent Events)

## Stream with Timeout
### Description
Streams matching pages with a specified timeout.
### Method
GET
### Endpoint
/v1/stream?timeout={TIMEOUT}
### Query Parameters
- **timeout** (integer) - Required - The timeout in seconds for the stream connection.
```

--------------------------------

### Open the Stream

Source: https://docs.firehose.com/get-started/quickstart

Open a stream of matching web pages using your tap token. This command connects to the Firehose stream endpoint and receives events.

```bash
curl -N https://api.firehose.com/v1/stream \
  -H "Authorization: Bearer $FIREHOSE_TAP_TOKEN"
```

--------------------------------

### Example Firehose Payload

Source: https://docs.firehose.com/stream/match-payload.md

This JSON object represents a typical payload received from the Firehose stream, including document metadata and matched information.

```json
{
  "query_ids": ["1"],
  "matched_at": "2026-02-13T08:06:32.123456Z",
  "tap_id": "1",
  "document": {
    "url": "https://example.com/page",
    "title": "Example Page",
    "publish_time": "2026-02-13T08:06:32",
    "diff": { "chunks": [{ "typ": "ins", "text": "New content added…" }] },
    "page_category": ["/News"],
    "page_types": ["/Article"],
    "language": "en",
    "domain_rating": 78
  }
}
```

--------------------------------

### Stream Matches (Python)

Source: https://docs.firehose.com/api-reference/examples.md

Stream data matches using Python's urllib.request. This example decodes and parses incoming data lines.

```python
import json, os, urllib.request

req = urllib.request.Request(
    "https://api.firehose.com/v1/stream",
    headers={"Authorization": f"Bearer {os.environ['FIREHOSE_TAP_TOKEN']}"},
)

with urllib.request.urlopen(req) as resp:
    for line in resp:
        line = line.decode().strip()
        if line.startswith("data: "):
            data = json.loads(line[6:])
            if "document" in data:
                print("matched:", data["document"]["url"])
```

--------------------------------

### Manage Firehose Rules with curl

Source: https://docs.firehose.com/skill.md

These curl commands demonstrate how to list, create, update, and delete rules using your tap token. Set the FIREHOSE_TAP_TOKEN environment variable before use.

```bash
# List rules
curl -s -H "Authorization: Bearer $FIREHOSE_TAP_TOKEN" https://api.firehose.com/v1/rules

# Create a simple rule
curl -s -X POST -H "Authorization: Bearer $FIREHOSE_TAP_TOKEN" -H "Content-Type: application/json" -d '{"value": "ahrefs", "tag": "brand"}' https://api.firehose.com/v1/rules

# Create a rule with field-specific query
curl -s -X POST -H "Authorization: Bearer $FIREHOSE_TAP_TOKEN" -H "Content-Type: application/json" -d '{"value": "title:tesla AND page_category:\"/News\"", "tag": "market-news"}' https://api.firehose.com/v1/rules

# Get a single rule
curl -s -H "Authorization: Bearer $FIREHOSE_TAP_TOKEN" https://api.firehose.com/v1/rules/1

# Update a rule
curl -s -X PUT -H "Authorization: Bearer $FIREHOSE_TAP_TOKEN" -H "Content-Type: application/json" -d '{"tag": "new-tag"}' https://api.firehose.com/v1/rules/1

# Create a rule with recency filter and quality disabled
curl -s -X POST -H "Authorization: Bearer $FIREHOSE_TAP_TOKEN" -H "Content-Type: application/json" \
  -d '{"value": "title:tesla AND recent:24h", "tag": "market-raw", "quality": false}' \
  https://api.firehose.com/v1/rules

# Delete a rule
curl -s -X DELETE -H "Authorization: Bearer $FIREHOSE_TAP_TOKEN" https://api.firehose.com/v1/rules/1
```

--------------------------------

### Example Subcategories

Source: https://docs.firehose.com/stream/match-payload.md

This list shows a sample of subcategories within the Firehose content classification system. These hierarchical labels are used in the `page_category` and `page_types` fields.

```text
/Arts_and_Entertainment/Celebrities_and_Entertainment_News
/Arts_and_Entertainment/Comics_and_Animation
/Arts_and_Entertainment/Comics_and_Animation/Anime_and_Manga
/Arts_and_Entertainment/Comics_and_Animation/Cartoons
/Arts_and_Entertainment/Comics_and_Animation/Comics
/Arts_and_Entertainment/Entertainment_Industry
/Arts_and_Entertainment/Entertainment_Industry/Film_and_TV_Industry
/Arts_and_Entertainment/Entertainment_Industry/Recording_Industry
/Arts_and_Entertainment/Events_and_Listings
/Arts_and_Entertainment/Events_and_Listings/Bars,_Clubs_and_Nightlife
/Arts_and_Entertainment/Events_and_Listings/Concerts_and_Music_Festivals
/Arts_and_Entertainment/Events_and_Listings/Event_Ticket_Sales
/Arts_and_Entertainment/Events_and_Listings/Expos_and_Conventions
/Arts_and_Entertainment/Events_and_Listings/Film_Festivals
/Arts_and_Entertainment/Events_and_Listings/Food_and_Beverage_Events
/Arts_and_Entertainment/Events_and_Listings/Live_Sporting_Events
/Arts_and_Entertainment/Events_and_Listings/Movie_Listings_and_Theater_Showtimes
/Arts_and_Entertainment/Fun_and_Trivia
/Arts_and_Entertainment/Fun_and_Trivia/Flash-Based_Entertainment
/Arts_and_Entertainment/Fun_and_Trivia/Fun_Tests_and_Silly_Surveys
/Arts_and_Entertainment/Humor
/Arts_and_Entertainment/Humor/Funny_Pictures_and_Videos
/Arts_and_Entertainment/Humor/Live_Comedy
/Arts_and_Entertainment/Humor/Political_Humor
/Arts_and_Entertainment/Humor/Spoofs_and_Satire
/Arts_and_Entertainment/Movies
/Arts_and_Entertainment/Movies/Action_and_Adventure_Films
/Arts_and_Entertainment/Movies/Animated_Films
/Arts_and_Entertainment/Movies/Bollywood_and_South_Asian_Films
/Arts_and_Entertainment/Movies/Classic_Films
/Arts_and_Entertainment/Movies/Comedy_Films
/Arts_and_Entertainment/Movies/Cult_and_Indie_Films
/Arts_and_Entertainment/Movies/DVD_and_Video_Shopping
/Arts_and_Entertainment/Movies/Documentary_Films
/Arts_and_Entertainment/Movies/Drama_Films
/Arts_and_Entertainment/Movies/Family_Films
/Arts_and_Entertainment/Movies/Horror_Films
/Arts_and_Entertainment/Movies/Movie_Memorabilia
/Arts_and_Entertainment/Movies/Movie_Reference
/Arts_and_Entertainment/Movies/Musical_Films
/Arts_and_Entertainment/Movies/Romance_Films
/Arts_and_Entertainment/Movies/Science_Fiction_and_Fantasy_Films
/Arts_and_Entertainment/Movies/Thriller,_Crime_and_Mystery_Films
/Arts_and_Entertainment/Music_and_Audio
/Arts_and_Entertainment/Music_and_Audio/CD_and_Audio_Shopping
/Arts_and_Entertainment/Music_and_Audio/Classical_Music
/Arts_and_Entertainment/Music_and_Audio/Country_Music
/Arts_and_Entertainment/Music_and_Audio/Dance_and_Electronic_Music
/Arts_and_Entertainment/Music_and_Audio/Experimental_and_Industrial_Music
/Arts_and_Entertainment/Music_and_Audio/Folk_and_Traditional_Music
/Arts_and_Entertainment/Music_and_Audio/Jazz_and_Blues
/Arts_and_Entertainment/Music_and_Audio/Music_Art_and_Memorabilia
/Arts_and_Entertainment/Music_and_Audio/Music_Education_and_Instruction
/Arts_and_Entertainment/Music_and_Audio/Music_Equipment_and_Technology
/Arts_and_Entertainment/Music_and_Audio/Music_Reference
/Arts_and_Entertainment/Music_and_Audio/Music_Streams_and_Downloads
/Arts_and_Entertainment/Music_and_Audio/Music_Videos
/Arts_and_Entertainment/Music_and_Audio/Podcasts
/Arts_and_Entertainment/Music_and_Audio/Pop_Music
/Arts_and_Entertainment/Music_and_Audio/Radio
/Arts_and_Entertainment/Music_and_Audio/Religious_Music
/Arts_and_Entertainment/Music_and_Audio/Rock_Music
/Arts_and_Entertainment/Music_and_Audio/Soundtracks
```

--------------------------------

### Accessing Raw Markdown

Source: https://docs.firehose.com/llms-full.txt

Append .md to any Firehose documentation URL to get the raw Markdown version of the page. This is useful for LLMs and coding agents.

```text
https://docs.firehose.com/stream/rules
https://docs.firehose.com/stream/rules.md   ← raw Markdown
```

--------------------------------

### List URL Watches (curl)

Source: https://docs.firehose.com/api-reference/examples.md

List all existing URL watches associated with your account using the management key.

```bash
# List your watches
curl -s https://api.firehose.com/v1/url-watch \
  -H "Authorization: Bearer $FIREHOSE_MGMT_KEY"
```

--------------------------------

### List Rules

Source: https://docs.firehose.com/llms-full.txt

Retrieves a list of all rules configured for the tap.

```APIDOC
## GET /v1/rules

### Description
Retrieves a list of all rules configured for the tap.

### Method
GET

### Endpoint
/v1/rules

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of rules to return.
- **offset** (string) - Optional - The offset to start retrieving rules from.

### Response
#### Success Response (200)
- **rules** (array) - A list of rule objects.
  - **value** (string) - The query string for the rule.
  - **tag** (string) - An optional tag for the rule.
  - **nsfw** (boolean) - Indicates if the rule is NSFW.
  - **quality** (boolean) - Indicates if the rule is considered high quality.

#### Response Example
{
  "rules": [
    {
      "value": "tesla OR \"electric vehicle\"",
      "tag": "ev",
      "nsfw": false,
      "quality": true
    }
  ]
}
```

--------------------------------

### URL Watch List Response Structure

Source: https://docs.firehose.com/api-reference/url-watch-endpoints.md

Example JSON response structure for listing URL Watch subscriptions, showing details of a single active watch.

```json
{
  "data": [
    {
      "id": "uuid",
      "url": "https://example.com/pricing",
      "frequency_minutes": 360,
      "status": "active",
      "change_count": 4,
      "last_checked_at": "2026-06-08T09:00:00+00:00",
      "created_at": "2026-06-01T00:00:00+00:00"
    }
  ]
}
```

--------------------------------

### Billing Logic Summary

Source: https://docs.firehose.com/billing/how-billing-works.md

This logic outlines how the balance is calculated, how matches are debited, and the consequence of the balance reaching zero.

```text
balance = sum of remaining credit across active grants
match delivered on /v1/stream ──▶ debit $0.005 from balance
balance hits $0 ──▶ new stream connections return 402
```

--------------------------------

### Create Rule

Source: https://docs.firehose.com/skill.md

Create a new rule with specified parameters. Requires a tap token.

```http
POST /v1/rules
Content-Type: application/json

{ "value": "ahrefs OR semrush", "tag": "seo-tools" }
```

```json
{
    "data": { "id": "3", "value": "ahrefs OR semrush", "tag": "seo-tools" }
}
```

--------------------------------

### Access Raw Markdown for a Page

Source: https://docs.firehose.com/resources/ai-agents.md

Append .md to any URL to get the raw Markdown version of a page. This is useful for feeding individual page content to LLMs.

```text
https://docs.firehose.com/stream/rules.md
```
Tokens:
Raw