API Documentation

Base URL: https://api.rustypaper.com

Authentication

Free tier requires no key (10 req/min). For higher limits, pass your API key as a query parameter:

curl "https://api.rustypaper.com/articles?api_key=ap_YOUR_KEY"

Get a key on your account page. Authorization: Bearer header also works.

Endpoints

Endpoint	Description
GET /	Top stories — bucketed homepage feed (events shape)
GET /articles	Latest stories
GET /articles/:slug	Full article: body, summary, sources, media
GET /s/:shortId	Short URL — resolves to /articles/:slug
GET /search?q=QUERY	Full-text search
GET /business	Business section (today, max 10)
GET /politics	Politics section (today, max 10)
GET /sports	Sports section (today, max 10)
GET /obscure	Obscure section (today, max 10)
GET /trending	Trending section (today, max 10)
GET /tech	Tech section (today, max 10)
GET /ai	AI section (today, max 10)
GET /science	Science section (today, max 10)
GET /topics?tags=a,b,c	Topics by tag — max 5 tags, today, max 10
GET /geo/us	Geo: Us (today, max 10)
GET /geo/middle_east	Geo: Middle East (today, max 10)
GET /geo/europe	Geo: Europe (today, max 10)
GET /geo/asia	Geo: Asia (today, max 10)
GET /geo/africa	Geo: Africa (today, max 10)
GET /geo/americas	Geo: Americas (today, max 10)
GET /geo/international	Geo: International (today, max 10)
GET /sources	Source counts (today)
GET /sitemap.xml	XML sitemap
GET /llms.txt	Machine-readable site index

Parameters

Parameter	Description
?api_key=KEY	API key authentication
?format=json	JSON response (default)
?format=text	Plain text response
?format=markdown	Markdown response
?page=N	Pagination (default: 1)
?limit=N	Items per page (default: 20, max: 100)
?tags=a,b,c	On /topics: comma-separated tags (max 5)
?since=all	Remove the default 24h time window

Response Shape

List endpoints return:

{
  "items": [
    {
      "slug": "uuid",
      "shortId": "Ae",
      "title": "...",
      "summary": "...",
      "publishedAt": "2026-03-20T...",
      "tags": ["oil", "iran"],
      "hasEvent": true,
      "sources": [...],
      "categories": ["business", "politics"],
      "sourceCount": 3
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 500, "pages": 25 }
}

Article detail returns:

{
  "slug": "uuid",
  "shortId": "Ae",
  "title": "...",
  "summary": "...",
  "body": "Full article text...",
  "tags": ["oil", "iran"],
  "sources": [{ "source_name": "reuters", "title": "...", "url": "..." }],
  "metadata": {
    "who": "...", "what": "...", "where": "...",
    "entities": { "people": [], "orgs": [], "places": [] }
  }
}

Rate Limits

Tier	Rate	Features
Free	10/min	Headlines, search, categories
Pro	100/min	Full articles, semantic search
Enterprise	1,000/min	Bulk access, priority support

Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Examples

# Latest stories
curl https://api.rustypaper.com/articles

# Search
curl "https://api.rustypaper.com/search?q=iran+oil"

# Business section
curl https://api.rustypaper.com/business

# Topics by tag (max 5)
curl "https://api.rustypaper.com/topics?tags=oil,iran"

# US geo
curl https://api.rustypaper.com/geo/us

# Politics in plain text
curl "https://api.rustypaper.com/politics?format=text"

# With API key
curl "https://api.rustypaper.com/articles?api_key=ap_YOUR_KEY"

# Full article
curl https://api.rustypaper.com/articles/SLUG

For Agents

Add RustyPaper as a skill:

npx skills add rustypaper/rustypaper

Or read the machine-readable spec:

curl https://api.rustypaper.com/llms.txt