Skip to content
Brainpercent LogoAPI Docs
Dashboard

Quick Start

Get up and running with the Brainpercent API in under 5 minutes.

Step 1: Create an API Key

Go to Developer Settings in your dashboard and create a new API key. Copy the key, it is shown exactly once.

Key creation is session-authenticated, so the dashboard is the only place to do it. You cannot create a key using another key.

Step 2: Make Your First Request

Let's list your articles to verify everything works:

curl https://www.brainpercent.app/api/v1/articles \
  -H "Authorization: Bearer bp_your_api_key_here"

Step 3: Check the Response

A successful response returns your articles with pagination metadata:

200Response
{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "10 SEO Tips for 2026",
      "slug": "10-seo-tips-2026",
      "status": "cms",
      "meta_description": "Discover the top SEO strategies for 2026...",
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-20T14:00:00Z",
      "project_id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "total_pages": 1,
    "has_more": false
  },
  "meta": {
    "timestamp": "2026-02-01T00:00:00Z"
  }
}

A finished, published article has status cms. There is no published status, so ?status=published returns nothing. The full list is draft, queued, cms, needs_editing, failed, archived.

Step 4: Generate an Article

Article generation needs a project_id. The project carries your brand, business context, and output language. Grab one from GET /api/v1/projects (projects are created in the app, not through the API). Generation costs 1.5 credits and takes 10 to 15 minutes.

# 1. Find a project to generate under
curl https://www.brainpercent.app/api/v1/projects \
  -H "Authorization: Bearer bp_your_api_key_here"

# 2. Generate, passing that project's id
curl -X POST https://www.brainpercent.app/api/v1/articles/generate \
  -H "Authorization: Bearer bp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "The Future of AI in Content Marketing",
    "project_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "keywords": ["AI", "content marketing", "SEO"],
    "tone": "professional",
    "word_count": 1200
  }'
202Generation started
{
  "success": true,
  "data": {
    "article_id": "550e8400-e29b-41d4-a716-446655440001",
    "status": "queued",
    "job_id": "01JQ8Z3M4N5P6Q7R8S9T0U1V2W",
    "slug": "the-future-of-ai-in-content-marketing",
    "language": "en",
    "credits_deducted": 1,
    "credits_remaining": 49,
    "estimated_time": "10-15 minutes",
    "poll_url": "/api/v1/articles/550e8400-e29b-41d4-a716-446655440001/status"
  },
  "meta": {
    "timestamp": "2026-02-01T00:00:00Z"
  }
}

Poll GET /api/v1/articles/:id/status until is_complete is true, then fetch the article.

Step 5: Generate Social Content

Create social posts from any URL. You get back one content_id covering every requested platform, not one per platform. Cost is 0.6 credits per platform, so X plus LinkedIn is 1.2 credits.

curl -X POST https://www.brainpercent.app/api/v1/social/generate \
  -H "Authorization: Bearer bp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://www.brainpercent.app/articles/the-future-of-ai-in-content-marketing",
    "platforms": ["twitter", "linkedin"],
    "source_type": "blog",
    "angle": "Lead with the measurable result"
  }'
202Social content generation started
{
  "success": true,
  "data": {
    "content_id": "d5b2f9c3-a0e4-5f8b-c6d7-2e3f4a5b6c7d",
    "status": "generating",
    "platforms": [
      "twitter",
      "linkedin"
    ],
    "credits_deducted": 2,
    "credits_remaining": 47,
    "poll_url": "/api/v1/social/content/d5b2f9c3-a0e4-5f8b-c6d7-2e3f4a5b6c7d"
  }
}

Poll GET /api/v1/social/content/:id. While the job runs, platforms is an array of the requested platform names. Once it finishes, platforms becomes an object keyed by platform whose values are the captions. Images live in image_urls.

Step 6: Check Your Credit Balance

Credits are the unit of account, 1 credit equals $1.00 of balance. One balance covers every content type. Check what is left:

curl https://www.brainpercent.app/api/v1/user/credits \
  -H "Authorization: Bearer bp_your_api_key_here"
200Credit balance
{
  "success": true,
  "data": {
    "available_credits": 47,
    "subscription_credits": 50,
    "purchased_credits": 0,
    "credits_used_this_month": 3,
    "plan": "Lite",
    "current_period_end": "2026-03-01T00:00:00Z"
  }
}

Step 7: Monitor API Usage

Track your API requests and rate limit status:

curl https://www.brainpercent.app/api/v1/user/usage \
  -H "Authorization: Bearer bp_your_api_key_here"

Next Steps