Public API

Authentication

Send your key in the Authorization header (or X-API-Key). Keys are scoped read and/or write, and are rate-limited per your plan.

curl https://your-domain.com/api/v1/batches \
  -H "Authorization: Bearer sp_live_xxxxxxxxxxxxxxxx"

Errors

• 401 — missing/invalid key
• 403 — key lacks the required scope
• 429 — daily request or AI-generation quota exceeded
• 409 — a batch already exists for that date + slot

List batches

GET/api/v1/batches· scope: read

Query params: page, limit, sort, category, status, date.

curl "https://your-domain.com/api/v1/batches?limit=10&sort=-createdAt" \
  -H "Authorization: Bearer sp_live_xxxx"

Create a batch

POST/api/v1/batches· scope: write

Generates content with AI and fans it out to per-platform versions.

curl -X POST https://your-domain.com/api/v1/batches \
  -H "Authorization: Bearer sp_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "motivation",
    "sub_type": "book_quote",
    "language": "nepali",
    "tone": "motivational"
  }'

Response:

{
  "data": {
    "batch": { "_id": "…", "title": "…", "category": "motivation", "status": "queued" },
    "versions": { "created": 4, "skipped": 0 },
    "review": { "ok": true, "issues": [] }
  }
}

Get a batch

GET/api/v1/batches/:id· scope: read

Returns the batch with its versions and platform posts.

List posts

GET/api/v1/posts· scope: read

Query params: page, limit, status, platform.