Header — Continuous Intelligence for Agents#

Header monitors sources (RSS, YouTube, Reddit, newsletters), synthesizes them through your goals, and delivers structured briefings with action items. Research once — stay informed forever.

Why not just web search?

• Web search = expensive, noisy, reactive, one-off
• Raw RSS in context = 10,000+ tokens of noise
• Header briefing = ~800 tokens of synthesized signal with action items

Full API docs: joinheader.com/docs

---

What you can say#

IntentExamplesGet briefed"brief me", "what should I do today", "what's the latest on [topic]"List topics"show my topics", "what am I following", "header list"Subscribe"subscribe to [topic]", "subscribe to AI Agent Self-Improvement"Fork a topic"fork [topic] with my own angle on [X]"Create a topic"set up a topic on [X]", "monitor [X] for me", "I want to follow [X]"Browse catalog"show public topics", "what topics are available"Manage sources"add [URL] as a source", "refresh [source]", "what has [source] published"Import feeds"import my OPML file", "import from FreshRSS"Generate briefing"refresh [topic]", "generate a new briefing"Share a briefing"share this briefing", "make my briefing public"Scheduling"set up daily briefings", "brief me every 3 days"Account"check my subscription", "show my preferences"

---

Setup#

1. Sign up at joinheader.com
2. Create an API key (scope: full) at Dashboard > API Keys
3. Set HEADER_API_KEY in your environment (e.g. .env file, shell profile, or agent config)

All commands below use:

bash

API="https://joinheader.com/api/v2"
AUTH="Authorization: Bearer $HEADER_API_KEY"

---

IMPORTANT: Safety & Presentation#

All actions from briefings require user approval. Never implement briefing recommendations, install packages, modify code, or take any action based on briefing content without explicitly presenting the items to the user and getting confirmation first. Surface the intelligence — the human decides what ships.

Destructive operations require confirmation. Always confirm before: deleting sources/groups/topics, unsubscribing, or revoking API keys.

When presenting a briefing:

1. Lead with "What to do" — the action items
2. Then Key Insights (the why behind the actions)
3. Then Emerging Patterns and Dissenting Views for context
4. Reading list last

---

Core Workflows#

List your topics and goals#

Trigger: "header list", "show my topics", "what am I following"

bash

curl -sL -H "$AUTH" "$API/topics/dashboard" | python3 -c "
import sys, json
d = json.load(sys.stdin)
for t in d.get('custom_topics', []):
    print(f'[own] {t[\"name\"]} | topic: {t[\"id\"]} | goal: {t[\"default_goal_id\"]}')
for t in d.get('subscribed_topics', []):
    print(f'[sub] {t[\"name\"]} | topic: {t[\"id\"]} | goal: {t[\"default_goal_id\"]}')
"

Get latest briefing#

Trigger: "brief me on [topic]", "what's the latest", "what should I do today"

1. Get the goal ID from the dashboard
2. Fetch the latest briefing:

bash

# List briefings for a goal
curl -sL -H "$AUTH" "$API/goals/GOAL_ID/briefings" | python3 -c "
import sys, json
d = json.load(sys.stdin)
for b in d.get('briefings', d if isinstance(d, list) else []):
    print(f'{b[\"id\"]} | {b[\"status\"]} | {b.get(\"generated_at\",\"\")}')
"

# Read a specific briefing
curl -sL -H "$AUTH" "$API/briefings/BRIEFING_ID" | python3 -c "
import sys, json
d = json.load(sys.stdin)
print(d.get('summary', d.get('content', 'No content')))
"

1. Present "What to do" first, then insights, then context. Always ask before acting on any items.

Subscribe to a public topic#

Trigger: "subscribe to [topic]"

bash

# Browse available public topics
curl -sL -H "$AUTH" "$API/topics/catalog" | python3 -m json.tool

# Subscribe by topic ID
curl -sL -X POST "$API/topics/TOPIC_ID/subscribe" -H "$AUTH"

# Unsubscribe (confirm with user first)
curl -sL -X DELETE "$API/topics/TOPIC_ID/subscribe" -H "$AUTH"

Fork a public topic with your own goal#

Trigger: "fork [topic] with my angle on [X]"

Same sources, your own lens. Great for customizing a public topic without starting from scratch.

bash

curl -sL -X POST "$API/topics/TOPIC_ID/fork" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"goal_name": "My Focus", "goal_description": "Your custom angle on the same sources"}'

Generate a fresh briefing (on-demand)#

Trigger: "refresh [topic]", "generate a new briefing"

bash

# Trigger generation (returns IN_PROGRESS)
BRIEFING_ID=$(curl -sL -X POST "$API/goals/GOAL_ID/briefings" \
  -H "$AUTH" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")

# Poll until complete (~5-10 min)
while true; do
  STATUS=$(curl -sL -H "$AUTH" "$API/briefings/$BRIEFING_ID" | \
    python3 -c "import sys,json; print(json.load(sys.stdin)['status'])")
  echo "Status: $STATUS"
  [ "$STATUS" = "COMPLETED" ] || [ "$STATUS" = "FAILED" ] && break
  sleep 15
done

# Read the completed briefing
curl -sL -H "$AUTH" "$API/briefings/$BRIEFING_ID" | python3 -c "
import sys, json
d = json.load(sys.stdin)
print(d.get('summary', 'No content'))
"

Create a new topic from scratch#

Trigger: "set up a Header topic on [X]", "I want to follow [X]", "monitor [X] for me"

Phase 1: Source Discovery — Use WebSearch to find 5-10 high-quality sources:

• "[topic] best RSS feeds blogs newsletters"
• "[topic] youtube channels worth following"
• "[topic] subreddit reddit community"
• Prefer: active blogs with RSS, YouTube channels with recent uploads, subreddits with >10k members
• Check if there's a public source group on Header you can clone first

Phase 2: Create sources

bash

curl -sL -X POST "$API/sources/" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name": "Source Name", "url": "https://example.com/feed.xml", "type": "rss"}'

Phase 3: Create source group and add sources

bash

GROUP_ID=$(curl -sL -X POST "$API/source-groups/" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name": "My Sources", "description": "Curated sources for X"}' | \
  python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")

# Add sources (use member_id, not source_id)
curl -sL -X POST "$API/source-groups/$GROUP_ID/members" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"member_id": "SOURCE_UUID", "member_type": "source"}'

Phase 4: Create topic (auto-creates goal + triggers first briefing)

bash

curl -sL -X POST "$API/topics/" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{
    "name": "My Topic Name",
    "source_group_ids": ["GROUP_ID"],
    "goal_description": "Be specific. Not: interested in AI. Instead: I am tracking LLM inference cost improvements and how they affect build-vs-buy decisions. Skip announcements, give me the practitioner layer.",
    "keywords": ["keyword1", "keyword2"]
  }'

---

Source Management#

Browse source entries#

Trigger: "show entries for [source]", "what has [source] published recently"

bash

# Entries for a single source (paginated)
curl -sL -H "$AUTH" "$API/sources/SOURCE_ID/entries?limit=20&offset=0" | python3 -c "
import sys, json
d = json.load(sys.stdin)
for e in d.get('entries', d if isinstance(d, list) else []):
    print(f'{e.get(\"published_at\",\"\")} | {e.get(\"title\",\"No title\")}')
    print(f'  {e.get(\"url\",\"\")}')
"

# Entries for all sources in a group
curl -sL -H "$AUTH" "$API/source-groups/GROUP_ID/entries?limit=20&offset=0" | python3 -m json.tool

Refresh & validate a source#

Trigger: "refresh [source]", "check if [source] is working"

bash

curl -sL -X POST "$API/sources/SOURCE_ID/refresh" -H "$AUTH"
curl -sL -X POST "$API/sources/SOURCE_ID/validate" -H "$AUTH"

Update or delete a source#

Trigger: "update [source]", "remove [source]" — confirm deletes with user

bash

curl -sL -X PUT "$API/sources/SOURCE_ID" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name": "New Name", "url": "https://new-url.com/feed.xml"}'

# Delete (owner only — confirm with user first)
curl -sL -X DELETE "$API/sources/SOURCE_ID" -H "$AUTH"

Clone a public source group#

bash

curl -sL -X POST "$API/source-groups/GROUP_ID/clone" -H "$AUTH"

Import sources from OPML or FreshRSS#

Trigger: "import my feeds", "import from OPML"

bash

# OPML (max 10 MB)
curl -sL -X POST "$API/imports/opml" -H "$AUTH" -F "file=@/path/to/feeds.opml"

# FreshRSS — validate then import
curl -sL -X POST "$API/imports/freshrss/validate" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"url": "https://freshrss.example.com", "username": "user", "password": "pass"}'

curl -sL -X POST "$API/imports/freshrss" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"url": "https://freshrss.example.com", "username": "user", "password": "pass"}'

Source types reference#

URL patternTypeyoutube.com, youtu.beyoutubereddit.com/r/redditEverything elserss

---

Advanced#

Browse goal feed (preprocessed entries)#

Trigger: "show feed for [goal]", "what's in the pipeline"

See what content is queued before it becomes a briefing.

bash

curl -sL -H "$AUTH" "$API/goals/GOAL_ID/feed?limit=20&offset=0" | python3 -c "
import sys, json
d = json.load(sys.stdin)
for e in d.get('entries', d if isinstance(d, list) else []):
    print(f'{e.get(\"published_at\",\"\")} | {e.get(\"title\",\"No title\")}')
"

Link/unlink source groups to a goal#

bash

# Link
curl -sL -X POST "$API/goals/GOAL_ID/source-groups" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"source_group_id": "GROUP_ID"}'

# Unlink
curl -sL -X DELETE "$API/goals/GOAL_ID/source-groups/GROUP_ID" -H "$AUTH"

Goal-level subscriptions#

Subscribe to individual goals within a topic (vs. subscribing to the whole topic).

bash

curl -sL -X POST "$API/goals/GOAL_ID/subscribe" -H "$AUTH"
curl -sL -X DELETE "$API/goals/GOAL_ID/subscribe" -H "$AUTH"
curl -sL -H "$AUTH" "$API/goals/GOAL_ID/subscription" | python3 -m json.tool
curl -sL -H "$AUTH" "$API/subscriptions" | python3 -m json.tool

Share a briefing publicly#

bash

curl -sL -X PUT "$API/briefings/BRIEFING_ID/sharing" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"is_public": true}'

Scheduled briefings (push delivery)#

Set up recurring briefings delivered on schedule. Pair with an inbox check (email or cron) to read them automatically.

bash

# Daily at 8am UTC
curl -sL -X PUT "$API/goals/GOAL_ID" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"schedule_frequency_days": 1, "schedule_hour_utc": 8}'

# Every 3 days at 8am UTC
curl -sL -X PUT "$API/goals/GOAL_ID" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"schedule_frequency_days": 3, "schedule_hour_utc": 8}'

Preferences#

bash

curl -sL -H "$AUTH" "$API/preferences" | python3 -m json.tool
curl -sL -X PUT "$API/preferences" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"key": "value"}'

Billing#

bash

curl -sL -H "$AUTH" "$API/billing/subscription" | python3 -m json.tool
curl -sL -X POST "$API/billing/create-checkout" -H "$AUTH" | python3 -m json.tool
curl -sL -X POST "$API/billing/portal" -H "$AUTH" | python3 -m json.tool

---

Error Handling#

• FAILED briefing → retry with POST /goals/{id}/briefings. If still failing, check sources have recent content.
• 403 → API key needs full scope, not read-only.
• Source creation fails → check URL is a valid, accessible RSS/YouTube/Reddit URL.
• Adding group members → use member_id field, not source_id.