API

API Reference

The Bloomberry API is a REST API that powers the Bloomberry web app and enables programmatic access to all core features. All endpoints return JSON.

Base URL

https://scintillating-clarity-production-ef70.up.railway.app

The base URL is set via the NEXT_PUBLIC_BACKEND_URL environment variable. See Environment Variables for setup.

Authentication

All authenticated endpoints require a Clerk session token in the Authorization header.

Authentication header

Authorization: Bearer <clerk-session-token>

The Bloomberry frontend obtains this token automatically via Clerk's getToken() helper. For direct API access, obtain a session token from your Clerk dashboard.

Writer API

Method	Endpoint	Description	Auth
`POST`	`/api/writer/generate`	Generate content from a concept	✓
`POST`	`/api/writer/generate-stream`	Stream content generation (SSE)	—
`POST`	`/api/writer/preview`	Preview generation without saving	✓
`POST`	`/api/writer/parse-intent`	Parse intent from rough concept	✓
`POST`	`/api/writer/extract-text`	Extract text from uploaded file	✓

POST /api/writer/generate

Generates content from a concept. Supports all 6 output formats.

Request body

{
  "concept": "Why most founders under-invest in personal brand",
  "formats": ["linkedin", "x"],
  "style": "natural",
  "sessionId": "sess_abc123"
}

Response

{
  "sessionId": "sess_abc123",
  "outputs": {
    "linkedin": {
      "content": "Most founders spend years...",
      "wordCount": 280,
      "estimatedReadTime": "1 min"
    },
    "x": {
      "content": "Thread: Why founders under-invest in personal brand

1/ ...",
      "tweets": ["Why founders...", "Most believe..."]
    }
  },
  "tokensUsed": 1240,
  "model": "gemini-1.5-pro"
}

POST /api/writer/generate-stream

Streams generation output using Server-Sent Events (SSE). Supported by both authenticated and unauthenticated users (unauthenticated users receive 1 free generation).

Example SSE connection

"color:#79c0ff">curl -X POST https://scintillating-clarity-production-ef70.up.railway.app/api/writer/generate-stream \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"concept": "Your concept here", "formats": ["linkedin"]}' \
  --no-buffer

Sessions API

Method	Endpoint	Description	Auth
`GET`	`/api/writer/sessions`	List all writer sessions	✓
`POST`	`/api/writer/sessions`	Create a new session	✓
`GET`	`/api/writer/sessions/:id`	Get a specific session	✓
`PUT`	`/api/writer/sessions/:id`	Update session content	✓
`DELETE`	`/api/writer/sessions/:id`	Delete a session	✓

Knowledge API

Method	Endpoint	Description	Auth
`GET`	`/api/knowledge`	List all knowledge base entries	✓
`POST`	`/api/knowledge`	Add a knowledge base entry	✓
`DELETE`	`/api/knowledge/:id`	Delete a knowledge entry	✓
`POST`	`/api/knowledge/match`	Semantic match entries to a prompt	✓
`POST`	`/api/knowledge/extract`	Auto-extract entries from text	✓

Brand Kit API

Method	Endpoint	Description	Auth
`GET`	`/api/brand-kit`	Get brand kit for current user	✓
`PUT`	`/api/brand-kit`	Update brand kit	✓
`POST`	`/api/brand-kit/upload-logo`	Upload logo file	✓

Scheduler API

Method	Endpoint	Description	Auth
`GET`	`/api/scheduler/posts`	List scheduled posts	✓
`POST`	`/api/scheduler/posts`	Schedule a post	✓
`PUT`	`/api/scheduler/posts/:id`	Update scheduled post	✓
`DELETE`	`/api/scheduler/posts/:id`	Cancel scheduled post	✓
`GET`	`/api/scheduler/queue`	Get posting queue	✓

Billing API

Method	Endpoint	Description	Auth
`POST`	`/api/billing/checkout`	Create Stripe checkout session	✓
`POST`	`/api/billing/portal`	Open Stripe customer portal	✓
`POST`	`/api/billing/webhook`	Stripe webhook receiver	—
`GET`	`/api/billing/usage`	Get current usage stats	✓

Error handling

All errors follow a consistent format:

Error response

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly chat limit reached. Upgrade to Pro for unlimited chats.",
    "statusCode": 429
  }
}

Status	Code	Meaning
`400`	`INVALID_REQUEST`	Malformed request body or missing required fields
`401`	`UNAUTHORIZED`	Missing or invalid authentication token
`403`	`FORBIDDEN`	Authenticated but insufficient permissions
`429`	`QUOTA_EXCEEDED`	Monthly usage limit reached
`429`	`RATE_LIMITED`	Too many requests in a short period
`500`	`INTERNAL_ERROR`	Server error — reported automatically

Edit this page on GitHub