Docs API Reference
Developer v1.0 15 min read

API Reference

The BrandStory.AI REST API lets you integrate AI content generation into your own applications. All requests use standard HTTP methods and return JSON responses.

Base URL
https://api.brandstory.ai/v1

REST API

Standard HTTP methods with JSON request/response bodies

API Key Auth

Secure authentication via Bearer token in request headers

Webhooks

Real-time event notifications for async content generation

Authentication

All API requests must include your API key in the Authorization header as a Bearer token.

Getting Your API Key

  1. 1 Log in to your BrandStory.AI account
  2. 2 Navigate to Settings → API & Integrations
  3. 3 Click "Generate New API Key"
  4. 4 Copy and securely store your key — it won't be shown again
Example Request 
# Using cURL
curl -X POST https://api.brandstory.ai/v1/content/blog \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "AI content marketing trends 2025",
    "wordCount": 1200,
    "tone": "professional"
  }'
Security: Never expose your API key in client-side code. Always make API calls from your server.

Rate Limits

Rate limits vary by plan. Exceeding limits returns a 429 Too Many Requests response.

Plan Requests / min Words / month Concurrent
Free 10 RPM 5,000 1
Starter 60 RPM 50,000 5
Pro 300 RPM Unlimited 20
Business 1,000 RPM Unlimited 100

Content Generation

Generate high-quality AI content using these endpoints.

POST /content/blog

Generate Blog Post

Create a full SEO-optimized blog post with headings, subheadings, and body content.

Request Body

Parameter Type Required Description
topic string Required Blog post topic or title
wordCount integer Optional Target word count (500–5000, default: 1000)
tone string Optional professional | friendly | confident | storytelling
keywords array Optional SEO keywords to include naturally
includeOutline boolean Optional Return outline alongside full post (default: false)

Request

{
  "topic": "AI in healthcare 2025",
  "wordCount": 1500,
  "tone": "professional",
  "keywords": [
    "AI diagnostics",
    "medical AI"
  ],
  "includeOutline": true
}

Response 200 OK

{
  "id": "cnt_9x2kd7m",
  "title": "AI in Healthcare...",
  "outline": ["Introduction", ...],
  "content": "# AI in Healthcare\n...",
  "wordCount": 1487,
  "seoScore": 94,
  "createdAt": "2025-02-19T..."
}
POST /content/social

Generate Social Media Post

Create platform-optimized posts for Instagram, LinkedIn, Twitter/X, Facebook, and TikTok.

Request

{
  "topic": "product launch announcement",
  "platform": "instagram",
  "style": "viral",
  "includeHashtags": true,
  "includeEmojis": true,
  "count": 3
}

Response 200 OK

{
  "posts": [
    {
      "id": "post_4k9f2a",
      "content": "🚀 Big news!...",
      "hashtags": ["#launch",...],
      "charCount": 218
    }
  ],
  "platform": "instagram"
}

Supported Platforms

instagram linkedin twitter facebook tiktok pinterest
POST /content/humanize

Humanize AI Text

Transform AI-generated content into natural, human-sounding text that bypasses AI detection.

Request

{
  "text": "The utilization of AI...",
  "level": "high",
  "preserveTone": true
}

Response 200 OK

{
  "original": "The utilization...",
  "humanized": "Using AI has become...",
  "humanScore": 98,
  "aiScore": 2
}

Scheduling

Schedule and manage posts programmatically.

POST /schedule/post — Schedule a post for future publishing
GET /schedule/posts — List all scheduled posts
PUT /schedule/posts/:id — Update a scheduled post
DELETE /schedule/posts/:id — Cancel a scheduled post

Webhooks

Receive real-time notifications when content generation completes or posts are published.

Supported Events

content.generated
post.published
post.failed
quota.limit_reached 
// Example webhook payload
{
  "event": "content.generated",
  "timestamp": "2025-02-19T10:30:00Z",
  "data": {
    "id": "cnt_9x2kd7m",
    "type": "blog",
    "status": "completed",
    "wordCount": 1487
  }
}

Error Codes

All errors return a JSON body with error and message fields.

Status Code Description
200OKRequest succeeded
400BAD_REQUESTInvalid or missing parameters
401UNAUTHORIZEDInvalid or missing API key
403FORBIDDENFeature not available on your plan
429RATE_LIMITEDRate limit exceeded — retry after delay
500SERVER_ERRORInternal server error — contact support

SDKs & Libraries

JavaScript / Node.js

npm install @brandstory/sdk
Available

Python

pip install brandstory-ai
Available

PHP

Coming soon
Coming Soon

Start Building with the API

Get your API key and start integrating in minutes.

Get Your API Key Contact Dev Support