Docs
Paperboy API reference
Call Paperboy from your own code: list sites, get topics, write and publish fact-checked articles, and read performance. Base URL https://paperboyseo.com/api/v1. This page is rendered from the OpenAPI 3.1 file you can download.
New here? Start with the quickstart. Or download openapi.json.
How do I authenticate?
Authorization: Bearer pb_live_...Keys have scopes: read, write (anything that spends credits) and publish. A key can be revoked at any time in Settings. Only a hash of the key is stored.
What do errors look like?
{ "error": { "code": "payment_required", "message": "Not enough credits: this costs 12.", "request_id": "req_0a1b2c3d4e5f6a7b" } }Status codes: 401 bad key, 402 not enough credits, 403 missing scope, 404 not found, 409 conflict, 422 invalid body, 429 rate limit, 502 upstream error, 500 internal error. Every response has an X-Request-Id header.
What are the rate limits?
Reads: 120 requests a minute per key. Calls that spend credits: 20 a minute. At most three API articles run at once. A 429 carries Retry-After and X-RateLimit-Limit, -Remaining and -Reset headers.
How do I retry safely?
Send Idempotency-Key on any call that spends credits. Replaying the same key returns the first result and charges nothing.
Endpoints
GET /api/v1/me
Owner, key scopes and credit balance
Responses: 200 OK; 401 Missing, malformed or revoked API key.; 429 Rate limit reached. Retry-After says when.
GET /api/v1/sites
List your sites
Responses: 200 OK; 401 Missing, malformed or revoked API key.; 429 Rate limit reached. Retry-After says when.
GET /api/v1/sites/{id}
One site, with article counts
id(path, required)
Responses: 200 OK; 401 Missing, malformed or revoked API key.; 404 No such resource for this key's owner.; 429 Rate limit reached. Retry-After says when.
GET /api/v1/sites/{id}/topics
Stored topic suggestions
id(path, required)
Responses: 200 OK; 401 Missing, malformed or revoked API key.; 404 No such resource for this key's owner.; 429 Rate limit reached. Retry-After says when.
POST /api/v1/sites/{id}/topics
Suggest the next articles, each with the reason (1 credit per call)
id(path, required)Idempotency-Key(header): Replays with the same key return the first result and charge nothing.
Body fields: n
Responses: 200 OK; 401 Missing, malformed or revoked API key.; 402 Not enough credits.; 403 The key lacks the scope this needs.; 404 No such resource for this key's owner.; 429 Rate limit reached. Retry-After says when.
GET /api/v1/sites/{id}/articles
Articles for a site
id(path, required)status(query)limit(query)
Responses: 200 OK; 401 Missing, malformed or revoked API key.; 404 No such resource for this key's owner.; 429 Rate limit reached. Retry-After says when.
POST /api/v1/sites/{id}/articles
Write an article now (12 credits, refunded if it fails)
Returns 202 at once. The run takes a few minutes: poll GET /articles/{id} until status is published or needs_review. publish=false (the default) holds a passed article for approval.
id(path, required)Idempotency-Key(header): Replays with the same key return the first result and charge nothing.
Body fields: topictopic_idtarget_querypublish
Responses: 202 Started; 401 Missing, malformed or revoked API key.; 402 Not enough credits.; 403 The key lacks the scope this needs.; 404 No such resource for this key's owner.; 409 Conflict, for example three articles already running.; 422 The request body or query is not valid.; 429 Rate limit reached. Retry-After says when.
GET /api/v1/sites/{id}/performance
Clicks, impressions and position per day and per article
id(path, required)days(query)
Responses: 200 OK; 401 Missing, malformed or revoked API key.; 404 No such resource for this key's owner.; 429 Rate limit reached. Retry-After says when.
GET /api/v1/sites/{id}/queries
Top search queries, for the site or one article
id(path, required)article_id(query)days(query)
Responses: 200 OK; 401 Missing, malformed or revoked API key.; 404 No such resource for this key's owner.; 429 Rate limit reached. Retry-After says when.
GET /api/v1/articles
All your articles
site_id(query)status(query)limit(query)
Responses: 200 OK; 401 Missing, malformed or revoked API key.; 429 Rate limit reached. Retry-After says when.
GET /api/v1/articles/{id}
One article with its fact-check verdict and sources
id(path, required)
Responses: 200 OK; 401 Missing, malformed or revoked API key.; 404 No such resource for this key's owner.; 429 Rate limit reached. Retry-After says when.
POST /api/v1/articles/{id}/publish
Publish an article that passed the fact check (free)
Needs the publish scope. Publishes to the target the site is set up with.
id(path, required)
Responses: 200 OK; 401 Missing, malformed or revoked API key.; 403 The key lacks the scope this needs.; 404 No such resource for this key's owner.; 409 Conflict, for example three articles already running.; 429 Rate limit reached. Retry-After says when.
POST /api/v1/check
Fact check a URL or pasted text (2 credits)
Send url or markdown. Returns a verdict plus every cited claim with the sources it was checked against.
Idempotency-Key(header): Replays with the same key return the first result and charge nothing.
Body fields: urlmarkdowntitlesources
Responses: 200 OK; 401 Missing, malformed or revoked API key.; 402 Not enough credits.; 403 The key lacks the scope this needs.; 422 The request body or query is not valid.; 429 Rate limit reached. Retry-After says when.
GET /api/v1/usage
Requests and credits per key, plus the recent ledger
days(query)
Responses: 200 OK; 401 Missing, malformed or revoked API key.; 429 Rate limit reached. Retry-After says when.
Ready to read your first article?
Paste your address. In under ten minutes you read a finished, fact-checked article written for your site. Free, no card.
Prefer to run it yourself? Self-host it (repo coming soon). Using an agent? Add the MCP server.