Documentation

Learn how Header works and explore the API for building integrations.

What is Header

In the era of AI, the expectations on knowledge workers are expanding across domains, but the time to learn hasn't kept up. Current tools help you consume more content — none help you actually improve how you or your agents work.

Header is a continuous learning system that turns information into behavior change. You define what you want to learn, connect the sources you trust, and Header synthesizes relevant insights from hundreds of sources into focused briefings you can act on.

Topics

When you create a topic, a default goal is created automatically with it. You can add more goals later to analyze the same sources from different angles. For example, an "AI Research" topic could have one goal tracking inference performance and another tracking safety research — same sources, different perspectives.

Public topics appear in the catalog for other users to discover. They can subscribe to receive the default goal's briefings, or fork the topic to create their own copy with a custom goal.

Goals

Goals are the unit that owns briefings. When a briefing is generated, Header pulls content from the goal's source groups, filters it through your relevance criteria, and synthesizes a focused digest. A single topic can have multiple goals, each producing its own briefings from a different perspective on the same content.

Sources

Sources are shared resources — any user can add a source, and all users benefit from the cached content. You organize sources into source groups to control which content flows into which goals.

Source Groups

OPML Import

OPML (Outline Processor Markup Language) is a standard XML format used by RSS readers to export and import feed subscriptions. If you use an RSS reader like Feedly, Inoreader, or NetNewsWire, you can export your feeds as an OPML file and import them directly into Header.

During import, each feed in the OPML file becomes a source, and the folder structure is preserved as source groups. Upload the file through the web interface or use the Imports API.

FreshRSS Import

If you run a self-hosted FreshRSS instance, Header can connect to it directly via the Google Reader-compatible API. Provide your FreshRSS instance URL, username, and API password, and Header will import your feeds and categories.

You can import into a single group or create one group per FreshRSS category. Validate your credentials first with the validate endpoint before running the full import.

Briefings

Briefings can be generated on-demand via the API or web interface, or scheduled to run automatically (daily, weekly, etc.) with results delivered by email. You can also make briefings public and share them with a link, or subscribe to other users' public topics to receive their briefings.

API Overview

Base URL

https://joinheader.com/api/v2

Authentication

All API requests require a Bearer token issued by Clerk. Include it in the Authorization header:

Authorization: Bearer <your-clerk-session-token>

OpenAPI Schema

The full machine-readable API specification is available at /api/v2/openapi.json. Use it with any OpenAPI-compatible client or code generator.

Sources

Create Source

// POST /api/v2/sources
{
  "name": "Hacker News",
  "url": "https://news.ycombinator.com/rss",
  "type": "rss"
}

Source Groups

Topics

Create Topic

// POST /api/v2/topics
// Creates a topic with a default goal and triggers the first briefing.
{
  "name": "AI Research",
  "source_group_ids": ["sg_abc123"],
  "goal_description": "Advances in local LLM inference on consumer hardware",
  "keywords": ["llama.cpp", "quantization"]
}

// Response:
{
  "topic": { /* TopicResponse */ },
  "first_briefing_id": "br_xyz789"
}

Fork Topic

// POST /api/v2/topics/{topic_id}/fork
// Creates your own copy of a public topic with a custom goal.
{
  "goal_name": "Safety Research Focus",
  "goal_description": "Track AI safety papers and alignment research",
  "keywords": ["alignment", "RLHF", "interpretability"]
}

Goals

Create Goal

// POST /api/v2/goals
{
  "name": "Local LLM Inference",
  "description": "Advances in running language models on consumer hardware",
  "keywords": ["llama.cpp", "quantization", "GGUF"],
  "relevance_questions": [
    "Does this discuss running models locally?",
    "Are there benchmarks for consumer GPUs?"
  ],
  "source_group_ids": ["sg_abc123"]
}

Briefings

Generate Briefing

// POST /api/v2/goals/{goal_id}/briefings
// Returns 201 with briefing in IN_PROGRESS status.
// Poll GET /briefings/{id} until status is COMPLETED.

// Response:
{
  "id": "br_xyz789",
  "goal_id": "goal_abc123",
  "status": "IN_PROGRESS",
  "created_at": "2026-02-26T12:00:00Z"
}

Imports

Subscriptions

Subscribe to public topics or individual goals to receive their briefings. Topic-level subscriptions are available under Topics. Goal-level subscriptions below allow more granular control.

Preferences

Billing

API Keys

Self-managed API keys allow programmatic access without Clerk session tokens. Only available for paid/poweruser tier subscribers. Keys have a scope that controls which HTTP methods are allowed: read (GET only) or full (all methods).