API reference

Code examples

End-to-end snippets for taps, rules, streaming, and URL Watch in curl, JavaScript, and Python — copy, paste, and adapt them to your own keys.

View as Markdown

Set your tokens first:

export FIREHOSE_MGMT_KEY=fhm_your_management_key
export FIREHOSE_TAP_TOKEN=fh_your_tap_token

curl

# 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"}'
 
# Create a rule (tap token)
curl -s -X POST https://api.firehose.com/v1/rules \
  -H "Authorization: Bearer $FIREHOSE_TAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": "title:tesla AND page_category:\"/News\" AND recent:24h", "tag": "market-news"}'
 
# Stream matches
curl -N "https://api.firehose.com/v1/stream?timeout=60" \
  -H "Authorization: Bearer $FIREHOSE_TAP_TOKEN"

URL Watch (curl)

# 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}'
 
# List your watches
curl -s https://api.firehose.com/v1/url-watch \
  -H "Authorization: Bearer $FIREHOSE_MGMT_KEY"

See URL Watch endpoints for the full request and response shapes.

JavaScript (Node)

// 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));

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"])