CreativForge API Documentation

Public REST API for external integrations (Zapier, Make, custom tools).

Base URL: your-domain.com

Authentication

All API requests require an API key. Include it in one of these headers:

# Option 1: x-api-key header
curl -H "x-api-key: sk_cf_your_key_here" ...

# Option 2: Bearer token
curl -H "Authorization: Bearer sk_cf_your_key_here" ...

Generate API keys in Settings. Keys start with sk_cf_ and are shown only once upon creation.

Response Format

All responses are JSON. Successful responses return the data directly. Errors return:

{
  "error": "Description of the error",
  "details": { ... }  // Optional validation details
}
200Success
201Created
400Bad Request (invalid data)
401Unauthorized (missing or invalid API key)
404Not Found
500Internal Error

API Key Management

These endpoints use session auth (cookie-based, from the web app). They are used by the Settings page.

GET/api/v1/keys

List your API keys (masked).

Response:

{
  "keys": [
    {
      "id": "uuid",
      "label": "Zapier",
      "key_masked": "sk_cf_ab...wxyz",
      "is_active": true,
      "created_at": "2026-03-26T...",
      "last_used_at": "2026-03-26T..."
    }
  ]
}
POST/api/v1/keys

Create a new API key. Returns the full key ONCE.

Request body:

{ "label": "My Integration" }

Response (201):

{
  "key": "sk_cf_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "id": "uuid",
  "label": "My Integration",
  "created_at": "2026-03-26T..."
}
DELETE/api/v1/keys

Deactivate an API key.

Request body:

{ "id": "key-uuid-here" }

Social Builder

GET/api/v1/social/projects

List all social projects.

Response:

{
  "projects": [
    {
      "id": "uuid",
      "brand_name": "My Brand",
      "niche": "fitness",
      "platforms": ["instagram", "facebook"],
      "status": "active",
      ...
    }
  ]
}
POST/api/v1/social/projects

Create a new social project.

Request body:

{
  "brand_name": "My Brand",
  "niche": "fitness",
  "platforms": ["instagram", "facebook"],
  "tone_of_voice": "casual",
  "target_audience": "Women 25-40",
  "language": "pt",
  "website_url": "https://mybrand.com"
}

Required: brand_name, niche, platforms

Platforms: instagram, facebook, tiktok, linkedin, twitter

GET/api/v1/social/posts?project_id=UUID

List posts for a project. Supports filtering and pagination.

Query parameters:

  • project_id (required) — UUID of the project
  • platform — Filter: instagram, facebook, etc.
  • status — Filter: draft, generating, ready, published
  • limit — Max results (default 50, max 100)
  • offset — Pagination offset (default 0)

Response:

{
  "posts": [
    {
      "id": "uuid",
      "platform": "instagram",
      "caption": "...",
      "hashtags": ["fitness", "health"],
      "status": "ready",
      "image_url": "https://...",
      ...
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}
POST/api/v1/social/posts/publish

Publish posts to connected social platforms.

Request body:

{
  "post_ids": ["uuid1", "uuid2"],
  "targets": ["facebook", "instagram"],
  "credential_id": "meta-credential-uuid",
  "page_id": "facebook-page-id",
  "linkedin_credential_id": "li-credential-uuid",
  "twitter_credential_id": "tw-credential-uuid"
}

Required: post_ids, targets. For Facebook/Instagram: credential_id + page_id. Credentials must be connected via the web app.

Performance Builder

GET/api/v1/performance/batches

List performance batches with optional filters.

Query parameters:

  • status — Filter: draft, strategy, hooks, generating, review, active, completed
  • limit — Max results (default 50, max 100)
  • offset — Pagination offset (default 0)

Response:

{
  "batches": [
    {
      "id": "uuid",
      "name": "Campaign Q1",
      "niche": "ecommerce",
      "platform": "meta_ads",
      "status": "review",
      ...
    }
  ],
  "total": 15,
  "limit": 50,
  "offset": 0
}
POST/api/v1/performance/batches

Create a new performance batch.

Request body:

{
  "name": "Campaign Q1",
  "niche": "ecommerce",
  "offer": "50% off summer collection",
  "platform": "meta_ads",
  "objective": "ctr",
  "funnel_stage": "cold",
  "formats": ["1:1", "4:5", "9:16"],
  "persona": "Women 25-40, interested in fashion",
  "pain_point": "Finding affordable trendy clothes",
  "promise": "Look great without breaking the bank",
  "desired_cta": "Shop Now",
  "landing_url": "https://mystore.com/summer",
  "language": "pt"
}

Required: name, niche, offer, platform, objective, funnel_stage, formats

Platforms: meta_ads, google_pmax, taboola, outbrain, mgid

Rate Limits

Currently there are no enforced rate limits. Please be reasonable with your usage. Publish endpoints include built-in delays (2s between posts) to respect platform rate limits.

CreativForge Public API v1