Articles

List, fetch, generate, poll. Generation costs 1.5 credits and returns 202.

Method	Path	What
GET	/api/v1/articles	List, paginated
GET	/api/v1/articles/:id	Full article
POST	/api/v1/articles/generate	1.5 credits, write
GET	/api/v1/articles/:id/status	Poll until is_complete

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, queued, cms, needs_editing, failed, archived. Note there is no "published" value, use cms.
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://www.brainpercent.app/api/v1/articles?page=1&limit=10&status=cms" \
  -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": "cms",
      "meta_description": "Learn the latest SEO strategies and techniques for 2026...",
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-01-20T14:30:00Z",
      "project_id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
    }
  ],
  "pagination": {
    "total": 42,
    "page": 1,
    "limit": 10,
    "total_pages": 5,
    "has_more": true
  }
}

GET/api/v1/articles/:id

Returns the full article row for a single article, including the rendered content. Returns 404 if the article does not exist or is not owned by your account.

Request

curl https://www.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": "cms",
    "content": "<h2>Introduction</h2><p>Search engine optimization continues to evolve...</p>",
    "meta_description": "Learn the latest SEO strategies and techniques for 2026...",
    "project_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "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 with an initial status of 'queued'. Poll /api/v1/articles/:id/status for progress. Requires write permission and costs 1.5 credits from your single account balance. project_id is required: the project supplies the brand, business context, and output language. In the 202 body, credits_deducted is the number of articles billed and credits_remaining is how many more articles your balance covers, so check GET /api/v1/user/credits for the balance itself.

Request body

Name	Type	Required	Description
topic	string	Required	The article topic or title (3-500 characters)
project_id	uuid	Required	The project this article belongs to. Supplies the brand, business context, and output language.
keywords	string[]	Optional	Target SEO keywords (max 20 items)
tone	string	Optional	Writing tone: professional, casual, academic, conversational
word_count	integer	Optional	Target word count (300-5000) Default 800.

Request

curl -X POST https://www.brainpercent.app/api/v1/articles/generate \
  -H "Authorization: Bearer bp_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Content Marketing Strategies That Actually Convert",
    "project_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "keywords": ["content marketing", "conversion", "automation"],
    "tone": "professional",
    "word_count": 1200
  }'

202Response

{
  "success": true,
  "data": {
    "article_id": "f8c9d0e1-2345-6789-abcd-ef0123456789",
    "status": "queued",
    "job_id": "01JQ8Z3M4N5P6Q7R8S9T0U1V2W",
    "slug": "content-marketing-strategies-that-actually-convert",
    "language": "en",
    "credits_deducted": 1,
    "credits_remaining": 39,
    "estimated_time": "10-15 minutes",
    "poll_url": "/api/v1/articles/f8c9d0e1-2345-6789-abcd-ef0123456789/status"
  }
}

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

Check the generation progress of an article. Poll this endpoint after calling the generate endpoint until is_complete is true, or until the status is 'failed'. is_complete is true when the status is cms or needs_editing.

Request

curl https://www.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": "queued",
    "title": "Content Marketing Strategies That Actually Convert",
    "slug": "content-marketing-strategies-that-actually-convert",
    "progress": 65,
    "is_complete": false,
    "created_at": "2026-02-01T12:00:00Z",
    "updated_at": "2026-02-01T12:04:32Z"
  }
}

Statuses

Exactly six values. There is no published, generating, or scheduled.

Status	Meaning
draft	Exists, not live
queued	Job accepted. Poll status.
cms	Finished and live. The terminal success.
needs_editing	Finished, flagged for review. Counts as complete.
failed	Generation failed
archived	Out of the active set

Permissions

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

Errors

Status	Code	When
400	VALIDATION_ERROR	Missing topic or project_id, tone, word_count, too many keywords
402	INSUFFICIENT_CREDITS	Wallet cannot cover the article
403	FORBIDDEN	Missing write or articles scope
404	NOT_FOUND	Article or project missing, or not yours

Flow

POST /articles/generate 202, article_id, queued, poll_url.
GET poll_url until is_complete. Thirty seconds is enough.
cms or needs_editing success. failed is the other stop.
GET /articles/:id full body.

Fields

Field	Type	Where
id	uuid	every response
title	string	every response
slug	string	every response
status	string	the six values above
content	string	single article only
meta_description	string	SEO line
project_id	uuid	owner project
created_at / updated_at	datetime	ISO 8601
progress	integer	status only
is_complete	boolean	status only. true on cms or needs_editing