Articles

Create, list, and manage AI-generated SEO articles.

The Articles API lets you programmatically generate long-form SEO content, retrieve existing articles, and monitor generation progress. All endpoints require a valid API key. Article generation is asynchronous — start a job with the generate endpoint, then poll the status endpoint until completion.

Method	Endpoint	Description
`GET`	/api/v1/articles	List articles (paginated, filterable)
`GET`	/api/v1/articles/:id	Get a single article with full content
`POST`	/api/v1/articles/generate	Generate an article (40 credits, write permission)
`GET`	/api/v1/articles/:id/status	Check article generation status

GET/api/v1/articles

Returns a paginated list of your articles. Supports filtering by status, project, and search query. Results are sorted by creation date descending by default.

Query Parameters

Name	Type	Required	Description
page	integer	Optional	Page number (1-indexed)(default: `1`)
limit	integer	Optional	Results per page (1-100)(default: `20`)
status	string	Optional	Filter by status: draft, published, scheduled, generating, failed
project_id	uuid	Optional	Filter by project ID
search	string	Optional	Search articles by title (case-insensitive partial match)
sort	string	Optional	Sort field: created_at, updated_at, title(default: `created_at`)
order	string	Optional	Sort order: asc, desc(default: `desc`)

Request

curl "https://brainpercent.app/api/v1/articles?page=1&limit=10&status=published" \
  -H "Authorization: Bearer bp_your_key"

200Response

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "The Complete Guide to SEO in 2026",
      "slug": "complete-guide-seo-2026",
      "status": "published",
      "meta_description": "Learn the latest SEO strategies and techniques for 2026...",
      "word_count": 2450,
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-01-20T14:30:00Z",
      "project_id": null
    }
  ],
  "pagination": {
    "total": 42,
    "page": 1,
    "limit": 10,
    "total_pages": 5,
    "has_more": true
  }
}

GET/api/v1/articles/:id

Returns full details for a single article, including the rendered HTML content, metadata, and associated project information.

Request

curl https://brainpercent.app/api/v1/articles/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer bp_your_key"

200Response

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "The Complete Guide to SEO in 2026",
    "slug": "complete-guide-seo-2026",
    "status": "published",
    "content": "<h2>Introduction</h2><p>Search engine optimization continues to evolve...</p>",
    "meta_description": "Learn the latest SEO strategies and techniques for 2026...",
    "keywords": [
      "SEO",
      "search engine optimization",
      "2026"
    ],
    "tone": "professional",
    "length": "long",
    "language": "en",
    "word_count": 2450,
    "project_id": null,
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-01-20T14:30:00Z"
  }
}

POST/api/v1/articles/generate

Start asynchronous article generation. Returns the new article ID and an initial status of 'generating'. Poll /api/v1/articles/:id/status for progress updates. Requires write permission and costs 40 credits per generation.

Request Body

Name	Type	Required	Description
topic	string	Required	The article topic or title (3-500 characters)
keywords	string[]	Optional	Target SEO keywords (max 20 items, each up to 100 chars)
tone	string	Optional	Writing tone: professional, casual, academic, conversational(default: `professional`)
length	string	Optional	Target article length: short (~800 words), medium (~1500 words), long (~2500 words)(default: `medium`)
language	string	Optional	ISO 639-1 language code for the generated content(default: `en`)
project_id	uuid	Optional	Assign the generated article to an existing project

Request

curl -X POST https://brainpercent.app/api/v1/articles/generate \
  -H "Authorization: Bearer bp_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "AI-Powered Content Marketing Strategies",
    "keywords": ["AI marketing", "content strategy", "automation"],
    "tone": "professional",
    "length": "long"
  }'

202Response

{
  "success": true,
  "data": {
    "article_id": "f8c9d0e1-2345-6789-abcd-ef0123456789",
    "status": "generating",
    "credits_used": 40,
    "estimated_time_seconds": 45
  }
}

GET/api/v1/articles/:id/status

Check the generation progress of an article. Returns the current status, progress percentage, and timestamps. Poll this endpoint after calling the generate endpoint until the status reaches 'published', 'draft', or 'failed'.

Request

curl https://brainpercent.app/api/v1/articles/f8c9d0e1-2345-6789-abcd-ef0123456789/status \
  -H "Authorization: Bearer bp_your_key"

200Response

{
  "success": true,
  "data": {
    "article_id": "f8c9d0e1-2345-6789-abcd-ef0123456789",
    "status": "generating",
    "title": "AI-Powered Content Marketing Strategies",
    "progress": 65,
    "steps_completed": [
      "outline",
      "research",
      "drafting"
    ],
    "current_step": "drafting",
    "created_at": "2026-02-01T12:00:00Z",
    "updated_at": "2026-02-01T12:00:32Z"
  }
}

Article Statuses

Articles progress through the following statuses during their lifecycle:

Status	Description
`generating`	Article is currently being generated. Poll the status endpoint for progress.
`draft`	Generation complete. Article is saved as a draft and ready for review.
`published`	Article has been published and is publicly accessible.
`scheduled`	Article is scheduled for future publication.
`failed`	Generation failed. Check the error field in the article response for details.

Permissions & Scopes

Each endpoint requires specific API key permissions and the articles scope.

Endpoint	Permission	Scope
GET /api/v1/articles	`read`	`articles`
GET /api/v1/articles/:id	`read`	`articles`
POST /api/v1/articles/generate	`write`	`articles`
GET /api/v1/articles/:id/status	`read`	`articles`

Error Responses

Common error responses for article endpoints:

Status	Code	When
400	`VALIDATION_ERROR`	Missing topic, invalid tone/length, keywords exceeding limits
402	`INSUFFICIENT_CREDITS`	Balance below 40 credits when calling generate
403	`FORBIDDEN`	API key lacks write permission or articles scope
404	`NOT_FOUND`	Article ID does not exist or is not owned by your account

Generation Flow

Article generation is asynchronous. The typical flow is:

1. POST /articles/generate → Returns 202 with article_id + status: "generating"

2. GET /articles/:id/status → Poll until status changes (5-second intervals recommended)

3. Status transitions: generating → draft (success) or failed (error)

4. GET /articles/:id → Retrieve the complete article once ready

Response Field Reference

Fields returned in article responses:

Field	Type	Description
id	uuid	Unique article identifier
title	string	Generated article title
slug	string	URL-friendly version of the title
status	string	Current status: generating, draft, published, scheduled, failed
content	string	HTML content of the article (only in single article responses)
meta_description	string	SEO meta description
keywords	string[]	Target SEO keywords used in generation
tone	string	Writing tone: professional, casual, academic, conversational
length	string	Target length: short, medium, long
language	string	ISO 639-1 language code
word_count	integer	Total word count of the generated article
project_id	uuid \| null	Associated project ID, if assigned
created_at	datetime	ISO 8601 creation timestamp
updated_at	datetime	ISO 8601 last update timestamp