Projects

Brand, language, and context for every generate. List and fetch only. There is no POST.

GET/api/v1/projects

Returns a paginated list of your projects with their business context. Supports filtering by status and searching by business name.

Query parameters

Name	Type	Required	Description
page	integer	Optional	Page number for pagination Default 1.
limit	integer	Optional	Number of results per page (1-100) Default 20.
status	string	Optional	Filter by project status. Free-form string, not a fixed enum. Real values include active, completed, ready, pending, generating.
search	string	Optional	Search projects by business_name (case-insensitive partial match)

Request

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

200Response

{
  "success": true,
  "data": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "business_name": "Northwind Analytics",
      "business_website": "https://northwind-analytics.com",
      "business_language": "English",
      "location": "Austin, TX",
      "expert_in": "Product analytics for B2B SaaS teams",
      "status": "active",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-28T12:00:00Z"
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "business_name": "Mercado Verde",
      "business_website": "https://mercadoverde.es",
      "business_language": "Spanish",
      "location": "Madrid, Spain",
      "expert_in": "Sustainable grocery delivery",
      "status": "ready",
      "created_at": "2026-01-10T09:30:00Z",
      "updated_at": "2026-01-25T16:45:00Z"
    }
  ],
  "pagination": {
    "total": 5,
    "page": 1,
    "limit": 10,
    "total_pages": 1,
    "has_more": false
  }
}

GET/api/v1/projects/:id

Returns the full business context for a single project: everything from the list response plus the audience profile, tone of voice, and offer structure used to shape generated content.

Query parameters

Name	Type	Required	Description
id	uuid	Required	The unique identifier of the project

Request

curl https://www.brainpercent.app/api/v1/projects/d290f1ee-6c54-4b01-90e6-d701748f0851 \
  -H "Authorization: Bearer bp_your_key"

200Response

{
  "success": true,
  "data": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "business_name": "Northwind Analytics",
    "business_website": "https://northwind-analytics.com",
    "business_language": "English",
    "language_code": "en",
    "location": "Austin, TX",
    "expert_in": "Product analytics for B2B SaaS teams",
    "status": "active",
    "project_status": "active",
    "avatar_icp": "Heads of Product at 50 to 300 person B2B SaaS companies",
    "avatar_niche": "Product-led growth teams without a dedicated data analyst",
    "tone_voice": "Direct, evidence-led, no hype",
    "tone_style": "Short paragraphs, concrete numbers, one idea per section",
    "structure_usp": "Answers product questions in seconds without SQL",
    "structure_main_offer": "Self-serve analytics workspace, 14-day trial",
    "structure_key_products": "Funnels, retention cohorts, session replay",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-28T12:00:00Z"
  }
}

Statuses

status is a free-form string, not a closed enum. Values seen in production include active, completed, ready, pending, generating.

Fields

The first block is on both list and detail. The rest is only on GET /projects/:id.

Field	Returned by	Meaning
id	both	Pass as project_id when generating
business_name	both	What search matches
business_website	both	Primary site
business_language	both	Language of generated copy
location	both	Where the business operates
expert_in	both	Authority
status	both	Free-form
created_at, updated_at	both	ISO 8601
language_code	single	Short language code
avatar_icp	single	Ideal customer
avatar_niche	single	Audience niche
tone_voice	single	Brand voice
tone_style	single	Writing style
structure_usp	single	USP
structure_main_offer	single	Main offer
structure_key_products	single	Products or services
project_status	single	Underlying status field

Generation

Article generate project_id is required.
Social generate optional. Falls back to the active project.
List articles GET /articles?project_id=
List social GET /social/content?project_id=

Filter

Request	Returns
GET /projects?status=active	status exactly active
GET /projects?status=completed	status exactly completed
GET /projects?search=northwind	business_name contains northwind
GET /projects	all