Documentation

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

// Response
{
  "id": "src_abc123",
  "name": "Hacker News",
  "type": "rss",
  "url": "https://news.ycombinator.com/rss",
  "is_active": true,
  "is_private": false,
  "metadata": {},
  "owner_id": "user_xyz",
  "last_ingested": null,
  "created_at": "2026-03-19T12:00:00Z"
}

// POST /api/v2/sources/preview
// Detect source type and fetch name before creating
{
  "url": "https://news.ycombinator.com/rss"
}

// Response
{
  "url": "https://news.ycombinator.com/rss",
  "name": "Hacker News",
  "type": "rss"
}

// POST /api/v2/sources/batch
// Create multiple sources at once, optionally adding them to a group
{
  "sources": [
    { "url": "https://news.ycombinator.com/rss", "type": "rss", "name": "Hacker News" },
    { "url": "https://feeds.arstechnica.com/arstechnica/index", "type": "rss", "name": "Ars Technica" }
  ],
  "source_group_id": "sg_abc123"  // optional — auto-adds created sources to this group
}

// Response
{
  "results": [
    { "url": "https://news.ycombinator.com/rss", "source_id": "src_abc123" },
    { "url": "https://feeds.arstechnica.com/...", "source_id": "src_def456" }
  ]
}

// Two-phase flow: ask Header to propose sources for a goal, then commit
// the selected ones into a canonical per-topic group.

// POST /api/v2/sources/recommend
{
  "topic_name": "AI Research",
  "goal_description": "Track notable AI research papers and industry announcements.",
  "existing_source_group_ids": ["sg_abc123"]  // skip sources already in these groups
}

// Response — verified cards + a signed envelope to echo back on /commit
{
  "recommendation_id": "rec_01H...",
  "cards": [
    {
      "name": "Import AI",
      "url": "https://jack-clark.net/",
      "feed_url": "https://jack-clark.net/feed/",
      "source_type": "rss",
      "why_relevant": "Weekly AI research summary from a longtime practitioner.",
      "signals": { "posting_cadence": "weekly", "last_post_date": "2026-04-18" },
      "quality_score": 0.87
    }
  ],
  "envelope": "eyJ...",
  "signature": "3f9c..."
}

// POST /api/v2/sources/recommend/commit
// Echo the envelope + signature from /recommend and the URLs you want.
{
  "envelope": "eyJ...",
  "signature": "3f9c...",
  "selected_card_urls": ["https://jack-clark.net/"]
}

// Response — sources are attached to a canonical "{topic} - Recommended sources" group
{
  "group_id": "sg_xyz789",
  "created_source_ids": ["src_new456"]
}

// POST /api/v2/source-groups/{group_id}/members
// member_id can be a source ID or another group ID (for nesting)
{
  "member_id": "src_abc123"
}

// Response: 204 No Content

// POST /api/v2/source-groups/{group_id}/members/bulk
{
  "member_ids": ["src_abc123", "src_def456", "sg_nested789"]
}

// Response
{
  "added_count": 2,
  "already_members": 1,
  "added_ids": ["src_abc123", "src_def456"],
  "skipped_cycles": []
}

// GET /api/v2/source-groups/{group_id}/members
// Response
{
  "members": [
    { "id": "src_abc123", "name": "Hacker News", "type": "rss" },
    { "id": "sg_nested789", "name": "AI Sources", "type": "source_group" }
  ],
  "total": 2,
  "expanded_source_count": 5  // total leaf sources including nested groups
}

// 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"
}

// 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"]
}

// PUT /api/v2/goals/{goal_id}
// All fields are optional — only include what you want to change.
{
  "description": "Updated focus on transformer architectures",
  "keywords": ["transformers", "attention"],
  "schedule_enabled": true,
  "schedule_frequency_days": 3,
  "schedule_hour": 8,
  "source_group_ids": ["sg_abc123", "sg_def456"]
}

// POST /api/v2/goals/{goal_id}/source-groups
{
  "source_group_id": "sg_abc123"
}

// Response: 204 No Content

// POST /api/v2/goals/{goal_id}/briefings
// All fields are optional. Omit body entirely for defaults.
{
  "max_entries": 5,   // optional: limit number of source entries
  "max_age_days": 7   // optional: only include entries from last N days
}

// Response: 201 — poll GET /briefings/{id} until status is COMPLETED
{
  "id": "br_xyz789",
  "goal_id": "goal_abc123",
  "status": "IN_PROGRESS",
  "created_at": "2026-02-26T12:00:00Z",
  "estimated_duration_seconds": 90,  // static estimate fixed at create time — does NOT count down; compute remaining as estimate - (now - created_at)
  "source_count": 12          // sources the estimate was based on (both null on briefings predating this field)
}

// PUT /api/v2/briefings/{briefing_id}/sharing
{
  "is_public": true
}

// Response
{
  "briefing_id": "br_xyz789",
  "is_public": true,
  "share_url": "https://joinheader.com/briefings/br_xyz789"
}

// POST /api/v2/imports/opml
// Content-Type: multipart/form-data
// Fields:
//   file: .opml or .xml file (max 10 MB)
//   source_group_id: (optional) add imported sources to this group
//   new_group_name: (optional) create a new group for imported sources

// Response
{
  "imported_count": 12,
  "failed_count": 1,
  "total_feeds": 13,
  "source_ids": ["src_abc123", "..."],
  "failures": [{ "title": "Bad Feed", "url": "...", "error": "..." }],
  "source_group_id": "sg_abc123"
}

// POST /api/v2/imports/freshrss/validate
{
  "url": "https://freshrss.example.com",
  "username": "admin",
  "api_password": "your-api-password"
}

// POST /api/v2/imports/freshrss
{
  "url": "https://freshrss.example.com",
  "username": "admin",
  "api_password": "your-api-password",
  "category_mode": "single_group",  // "single_group" | "per_category"
  "group_name": "My FreshRSS Feeds"     // optional: name for the new group
}

// PUT /api/v2/preferences
{
  "briefing_length": "long"  // "standard" | "long"
}

// Free user, trial unused — eligible to start a trial
{
  "status": "free",
  "tier": "free",                          // "free" | "paid" | "poweruser"
  "trial_started_at": null,
  "trial_ends_at": null,
  "trial_used": false,                  // lifetime "trial consumed" flag
  "trial_active": false,                // true while inside the 15-day window
  "can_start_trial": true,             // gates the /trial/start CTA
  "needs_tier_flip_acknowledgment": false,
  "tier_flip_kind": null,                 // "trial_expired" | "pro_lapsed" | null
  "can_upgrade": true,
  "can_manage": false
}

// Empty request body. Auth: Bearer <clerk-jwt|hdr_sk_...>

// 200 — trial started; same response shape as GET /subscription
{
  "status": "free",
  "tier": "paid",
  "trial_started_at": "2026-05-08T19:00:00Z",
  "trial_ends_at": "2026-05-23T19:00:00Z",
  "trial_used": true,
  "trial_active": true,
  "can_start_trial": false,
  "needs_tier_flip_acknowledgment": false,
  "tier_flip_kind": null,
  "can_upgrade": true,
  "can_manage": false
}

// 409 — trial already consumed (one per email, lifetime)
{
  "detail": {
    "error_code": "TRIAL_ALREADY_USED",
    "message": "You've already used your free trial."
  }
}

// 409 — caller is already on a paid tier
{
  "detail": {
    "error_code": "ALREADY_PAID",
    "message": "You're already on a paid plan."
  }
}

// POST /api/v2/api-keys
{
  "name": "My Integration",
  "scope": "read"  // "read" (GET only) | "full" (all methods)
}

// Response: 201 — save the secret, it is only shown once
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Integration",
  "scope": "read",
  "key_prefix": "hdr_sk_abc1",
  "secret": "hdr_sk_abc123...full_key_here",
  "created_at": "2026-03-19T12:00:00Z"
}

// POST /api/v2/experiments — re-sent on every edit; idempotent on client_key
{
  "v": 1,
  "client_key": "<installation_id>:<experiment_id>",  // upsert key
  "submitted_at": "2026-05-28T21:44:36Z",
  "experiment": {
    "kind": "model-swap",            // harness-change | model-swap | generic
    "description": "Opus vs Sonnet on triage",
    "status": "analyzed"          // defined | run | analyzed | merged
  },
  "result": null                 // the A/B result object once status ≥ analyzed
}

// Response: 201 created (200 on a later update). The client surfaces "url".
{
  "id": "exp_srv_abc123",
  "client_key": "<installation_id>:<experiment_id>",
  "url": "https://joinheader.com/experiments/exp_srv_abc123",
  "status": "stored"
}