API Documentation

Programmatic access to newsletter intelligence data

Authentication

All API requests require an API key sent via the Authorization header.

curl -H "Authorization: Bearer sk_live_your_key_here" \
https://newsletterinsights.io/api/v1/newsletters

Generate API keys in Settings → API Keys.

Rate Limits

TierDaily LimitPrice
Free100 requests$0/mo
Pro5,000 requests$49/mo
Enterprise50,000 requests$299/mo

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Endpoints

GET/api/v1/newsletters

List and search newsletters with pagination.

Parameters

pagenumberPage number (default: 1)
per_pagenumberResults per page (default: 20, max: 100)
searchstringSearch by name, author, description
categorystringFilter by category
platformstringFilter by platform (e.g. substack, beehiiv)
min_subscribersnumberMinimum subscriber count
max_subscribersnumberMaximum subscriber count
sort_bystringSort field: subscribers, name, growth_week, created_at
sort_directionstringasc or desc (default: desc)

Example

curl -H "Authorization: Bearer sk_live_..." \
https://newsletterinsights.io/api/v1/newsletters?search=AI&per_page=2

Response

{
  "data": [
    {
      "slug": "the-ai-report",
      "name": "The AI Report",
      "platform": "substack",
      "category": "Technology",
      "subscriber_count": 45000,
      "growth_rate_week": 2.3
    }
  ],
  "meta": { "total": 142, "page": 1, "per_page": 2, "has_more": true }
}
GET/api/v1/newsletters/:slug

Get full details for a single newsletter by slug.

Example

curl -H "Authorization: Bearer sk_live_..." \
https://newsletterinsights.io/api/v1/newsletters/the-ai-report

Response

{
  "data": {
    "slug": "the-ai-report",
    "name": "The AI Report",
    "platform": "substack",
    "category": "Technology",
    "subscriber_count": 45000,
    "free_subscribers": 40000,
    "paid_subscribers": 5000,
    "growth_rate_week": 2.3,
    "growth_rate_month": 8.1
  }
}
GET/api/v1/newsletters/:slug/snapshots

Get subscriber history over time. Days capped by tier: free=30, pro=90, enterprise=365.

Parameters

daysnumberNumber of days of history (default: 30)

Example

curl -H "Authorization: Bearer sk_live_..." \
https://newsletterinsights.io/api/v1/newsletters/the-ai-report/snapshots?days=7

Response

{
  "data": [
    {
      "date": "2026-02-12",
      "total_subscribers": 45000,
      "free_subscribers": 40000,
      "paid_subscribers": 5000
    }
  ]
}
GET/api/v1/newsletters/:slug/sponsors

Get sponsors detected in a newsletter.

Example

curl -H "Authorization: Bearer sk_live_..." \
https://newsletterinsights.io/api/v1/newsletters/the-ai-report/sponsors

Response

{
  "data": [
    {
      "sponsor_name": "Acme Corp",
      "sponsor_domain": "acme.com",
      "placement_type": "primary",
      "confidence": 0.95,
      "detected_at": "2026-02-01T00:00:00Z"
    }
  ]
}
GET/api/v1/categories

List all newsletter categories with counts.

Example

curl -H "Authorization: Bearer sk_live_..." \
https://newsletterinsights.io/api/v1/categories

Response

{
  "data": [
    {
      "category": "Technology",
      "newsletter_count": 842,
      "total_subscribers": 12500000,
      "subcategories": ["AI/ML", "Crypto", "SaaS"]
    }
  ]
}
GET/api/v1/categories/:slug/benchmarks

Get percentile benchmarks (subscribers, growth, engagement) for a category.

Example

curl -H "Authorization: Bearer sk_live_..." \
https://newsletterinsights.io/api/v1/categories/technology/benchmarks

Response

{
  "data": {
    "category": "Technology",
    "subscriber_benchmarks": {
      "p25": 1200, "p50": 5400,
      "p75": 22000, "p90": 85000
    },
    "growth_benchmarks": {
      "p25": 0.5, "p50": 1.8,
      "p75": 4.2, "p90": 9.1
    },
    "newsletter_count": 842
  }
}
GET/api/v1/sponsors

List and search sponsors with pagination.

Parameters

pagenumberPage number (default: 1)
per_pagenumberResults per page (default: 20, max: 100)
searchstringSearch by name or domain
categorystringFilter by category
sort_bystringSort field: total_placements, name, created_at
sort_directionstringasc or desc (default: desc)

Example

curl -H "Authorization: Bearer sk_live_..." \
https://newsletterinsights.io/api/v1/sponsors?search=stripe

Response

{
  "data": [
    {
      "id": "abc-123",
      "name": "Stripe",
      "domain": "stripe.com",
      "total_placements": 247
    }
  ],
  "meta": { "total": 1, "page": 1, "per_page": 20, "has_more": false }
}
GET/api/v1/sponsors/:id

Get sponsor details with placement history.

Example

curl -H "Authorization: Bearer sk_live_..." \
https://newsletterinsights.io/api/v1/sponsors/abc-123

Response

{
  "data": {
    "id": "abc-123",
    "name": "Stripe",
    "domain": "stripe.com",
    "total_placements": 247,
    "placements": [
      {
        "newsletter": { "name": "The AI Report", "slug": "the-ai-report" },
        "placement_type": "primary",
        "detected_at": "2026-02-01T00:00:00Z"
      }
    ]
  }
}

Error Responses

Errors return a consistent JSON format:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Newsletter not found"
  }
}
401Missing or invalid API key
404Resource not found
429Rate limit exceeded
500Internal server error
Get monthly newsletter intelligence — trends, top movers, new opportunities