SDKs & Resources

class BrainpercentClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    // Always www. The apex host 307-redirects and most clients
    // drop the POST body when they follow it.
    this.baseUrl = 'https://www.brainpercent.app/api/v1';
  }

  async request(path, options = {}) {
    const response = await fetch(`${this.baseUrl}${path}`, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
        ...options.headers,
      },
    });
    return response.json();
  }

  // Projects (read only; projects are created in the app)
  listProjects(params = {}) {
    return this.request(`/projects?${new URLSearchParams(params)}`);
  }

  getProject(id) {
    return this.request(`/projects/${id}`);
  }

  // Articles
  listArticles(params = {}) {
    return this.request(`/articles?${new URLSearchParams(params)}`);
  }

  getArticle(id) {
    return this.request(`/articles/${id}`);
  }

  /**
   * topic and project_id are required.
   * Optional: keywords (max 20), tone, word_count (300-5000, default 800).
   * Costs 1.5 credits. Returns 202 with a poll_url.
   */
  generateArticle({ topic, project_id, ...rest }) {
    return this.request('/articles/generate', {
      method: 'POST',
      body: JSON.stringify({ topic, project_id, ...rest }),
    });
  }

  getArticleStatus(id) {
    return this.request(`/articles/${id}/status`);
  }

  // Social
  listSocialContent(params = {}) {
    return this.request(`/social/content?${new URLSearchParams(params)}`);
  }

  getSocialContent(id) {
    return this.request(`/social/content/${id}`);
  }

  /**
   * source_url and platforms are required. Costs 0.6 credits per platform.
   * Returns 202 with ONE content_id covering every platform.
   */
  generateSocial({ source_url, platforms, ...rest }) {
    return this.request('/social/generate', {
      method: 'POST',
      body: JSON.stringify({ source_url, platforms, ...rest }),
    });
  }

  /** platforms is an optional subset. scheduled_at (ISO 8601) schedules it. */
  publishSocial({ content_id, platforms, scheduled_at }) {
    return this.request('/social/publish', {
      method: 'POST',
      body: JSON.stringify({ content_id, platforms, scheduled_at }),
    });
  }

  // Account
  getCredits() {
    return this.request('/user/credits');
  }

  getUsage(params = {}) {
    return this.request(`/user/usage?${new URLSearchParams(params)}`);
  }
}

// Usage
const client = new BrainpercentClient('bp_your_key');

const { data: projects } = await client.listProjects({ limit: 1 });
const { data: job } = await client.generateArticle({
  topic: 'Content marketing trends in 2026',
  project_id: projects[0].id,
  word_count: 1200,
});
console.log(job.status, job.poll_url); // 'queued' ...

import requests

class BrainpercentClient:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://www.brainpercent.app/api/v1"
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        })

    def _request(self, method: str, path: str, **kwargs):
        response = self.session.request(method, f"{self.base_url}{path}", **kwargs)
        response.raise_for_status()
        return response.json()

    # Projects (read only; projects are created in the app)
    def list_projects(self, **params):
        return self._request("GET", "/projects", params=params)

    def get_project(self, project_id: str):
        return self._request("GET", f"/projects/{project_id}")

    # Articles
    def list_articles(self, **params):
        return self._request("GET", "/articles", params=params)

    def get_article(self, article_id: str):
        return self._request("GET", f"/articles/{article_id}")

    def generate_article(self, topic: str, project_id: str, **kwargs):
        """topic and project_id are required. Optional: keywords (max 20),
        tone, word_count (300-5000, default 800). Costs 1.5 credits."""
        return self._request(
            "POST",
            "/articles/generate",
            json={"topic": topic, "project_id": project_id, **kwargs},
        )

    def get_article_status(self, article_id: str):
        return self._request("GET", f"/articles/{article_id}/status")

    # Social
    def list_social_content(self, **params):
        return self._request("GET", "/social/content", params=params)

    def get_social_content(self, content_id: str):
        return self._request("GET", f"/social/content/{content_id}")

    def generate_social(self, source_url: str, platforms: list, **kwargs):
        """0.6 credits per platform. Returns ONE content_id for all platforms."""
        return self._request(
            "POST",
            "/social/generate",
            json={"source_url": source_url, "platforms": platforms, **kwargs},
        )

    def publish_social(self, content_id: str, **kwargs):
        """Optional: platforms (subset), scheduled_at (ISO 8601)."""
        return self._request(
            "POST", "/social/publish", json={"content_id": content_id, **kwargs}
        )

    # Account
    def get_credits(self):
        return self._request("GET", "/user/credits")

    def get_usage(self, **params):
        return self._request("GET", "/user/usage", params=params)


# Usage
client = BrainpercentClient("bp_your_key")

projects = client.list_projects(limit=1)["data"]
job = client.generate_article(
    topic="Content marketing trends in 2026",
    project_id=projects[0]["id"],
    word_count=1200,
)["data"]
print(job["status"], job["poll_url"])  # 'queued' ...

export BP_API_KEY="bp_your_api_key_here"

# Find a project id. Every generation needs one.
curl "https://www.brainpercent.app/api/v1/projects?limit=1" \
  -H "Authorization: Bearer $BP_API_KEY"

# List finished articles ('cms' is the completed status)
curl "https://www.brainpercent.app/api/v1/articles?status=cms" \
  -H "Authorization: Bearer $BP_API_KEY"

# Generate an article (1.5 credits, returns 202 + poll_url)
curl -X POST https://www.brainpercent.app/api/v1/articles/generate \
  -H "Authorization: Bearer $BP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Practical SEO strategies for small teams",
    "project_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "tone": "professional",
    "word_count": 1200
  }'

# Turn a URL into posts (0.6 credits per platform, returns 202 + poll_url)
curl -X POST https://www.brainpercent.app/api/v1/social/generate \
  -H "Authorization: Bearer $BP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://example.com/blog/post",
    "platforms": ["linkedin", "instagram"],
    "project_id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
  }'

# Check credits
curl https://www.brainpercent.app/api/v1/user/credits \
  -H "Authorization: Bearer $BP_API_KEY"