API Reference

The Firmreader API is a REST API that lets you create posts, manage channels, and query analytics programmatically.

Base URL

https://api.firmreader.com/v1

Every request requires an API key in the Authorization header:

curl https://api.firmreader.com/v1/posts \
  -H "Authorization: Bearer fr_live_abc123"

API keys are created in Settings > API Keys. Each key has a scope that limits what it can access:

Scope	Permissions
`posts:read`	List and retrieve posts
`posts:write`	Create, update, and delete posts
`channels:read`	List and retrieve channels
`channels:write`	Create, update, and delete channels
`analytics:read`	Query engagement metrics

Rate limit headers are included in every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1708790400

All errors follow a consistent format:

{
  "error": {
    "code": "invalid_request",
    "message": "The channel_id field is required.",
    "param": "channel_id"
  }
}

HTTP Status	Meaning
400	Bad request — check your parameters
401	Unauthorized — invalid or missing API key
403	Forbidden — API key lacks required scope
404	Not found — resource doesn't exist
429	Rate limited — slow down
500	Server error — try again later

List endpoints return paginated results. Use cursor and limit parameters:

curl "https://api.firmreader.com/v1/posts?limit=20&cursor=post_abc123" \
  -H "Authorization: Bearer fr_live_abc123"

The response includes a next_cursor field. When it's null, you've reached the end.

{
  "data": [...],
  "next_cursor": "post_xyz789",
  "has_more": true
}