SocialBrainAI

Developers

SocialBrainAI API

Manage your sub-accounts from your own software: posts, creations, balance and usage, without going through the interface.

Quick start OpenAPI specification

API add-on: €149 excl. VAT per month for the whole account · creations paid as you go from your balance

Quick start

Your first call in 3 steps

1

Enable the API add-on

Contact us: the add-on is enabled on your main account (€149 excl. VAT per month).

2

Create a key

In the app: Settings → API. Choose its permissions (read-only, or read and write) and, if needed, the allowed sub-accounts. Copy it: it’s only shown once.

3

Call the API

Send the key in the Authorization header of every request, over HTTPS.

Test your key
curl https://socialbrainai.com/api/public/v1/me \
  -H "Authorization: Bearer sba_live_YOUR_KEY"

Authentication

  • Header: Authorization: Bearer sba_live_…
  • A key belongs to the main account; it can be restricted to specific sub-accounts.
  • Permissions: read-only, or read and write (posts and paid creations).
  • We only store a hash of the key: if it’s lost, revoke it and create a new one.

Limits

  • 60 requests per minute per key (headers X-RateLimit-*).
  • Beyond that: 429 response with Retry-After.
  • Lists: up to 100 items per page (limit, offset).
  • Posts: up to 10 media files, public https:// URLs.

Rules

  • A post created through the API waits for your approval, unless you’ve turned approval off in the app.
  • A creation is prepaid at the catalog price (excl. VAT) from the main account’s balance.
  • A launched creation is not refunded automatically; if something goes wrong, file a claim from the app.

Examples

Publish and create from your own software

Schedule a post on two networks
curl -X POST https://socialbrainai.com/api/public/v1/posts \
  -H "Authorization: Bearer sba_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subaccount_id": "SUBACCOUNT_ID",
    "networks": ["instagram", "facebook"],
    "caption": "New collection now available in store!",
    "hashtags": "#newin #fashion",
    "media_urls": ["https://your-site.example/images/collection.jpg"],
    "scheduled_at": "2026-11-02T09:30:00Z"
  }'
Request an ad image, then track the request
curl -X POST https://socialbrainai.com/api/public/v1/generations \
  -H "Authorization: Bearer sba_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subaccount_id": "SUBACCOUNT_ID",
    "type": "image",
    "params": { "product_id": "PRODUCT_ID", "network": "instagram", "language": "en" }
  }'

# 202 response: { "id": "…", "status": "pending", "price_eur": … }
curl https://socialbrainai.com/api/public/v1/generations/REQUEST_ID \
  -H "Authorization: Bearer sba_live_YOUR_KEY"

Reference

Endpoints

Base URL: https://socialbrainai.com/api/public/v1

  • GET/meThe key in use, its permissions and your account
  • GET/subaccountsYour sub-accounts (brands) accessible with the key
  • GET/balancePrepaid balance of the main account (in euros)
  • GET/usage?from=&to=&subaccount_id=Usage per sub-account over a period
  • GET/catalogAvailable creation types and their prices excl. VAT
  • GET/posts?subaccount_id=&status=&network=List posts
  • POST/postsCreate a post (one per target network)write
  • GET/posts/{id}Get a post
  • PATCH/posts/{id}Update a post that hasn’t been published yetwrite
  • POST/posts/{id}/scheduleSchedule a postwrite
  • DELETE/posts/{id}Delete a postwrite
  • POST/generationsRequest a creation (prepaid from the balance)write
  • GET/generationsList your creation requests
  • GET/generations/{id}Track a request: status and result
  • GET/creations?subaccount_id=Completed creations for a sub-account
v1 creation types: text_post, carousel, image, product_video — current parameters and prices via GET /catalog. Full details: OpenAPI specification.

Get notified automatically

Set an https:// callback URL in Settings → API. We send a signed JSON message there when a creation is ready (generation.completed) or has failed (generation.failed). Verify the signature with the secret shown when you save the URL. Each event is sent once: you can always re-read the status with GET /generations/{id}.

Verify the signature (Python)
# Headers received: X-SBA-Event, X-SBA-Timestamp, X-SBA-Signature
import hmac, hashlib

def is_valid_signature(secret: str, timestamp: str, raw_body: bytes, signature: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body,
                                    hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Errors

Clear errors, in English and French

Error format
{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key is read-only.",
    "message_fr": "Cette clé d'API est en lecture seule.",
    "request_id": "req_4b1f0c9e2a7d4c11a0e3"
  }
}
  • 401
    missing_api_key · invalid_api_key · revoked_api_key

    Key missing, invalid or revoked

  • 402
    insufficient_balance

    Insufficient balance for the requested creation

  • 403
    api_access_disabled

    API add-on not enabled on the account

  • 403
    insufficient_scope

    Read-only key used for a write

  • 403
    subaccount_forbidden

    Sub-account not allowed for this key

  • 400
    subaccount_required

    Several sub-accounts possible: specify subaccount_id

  • 404
    not_found · product_not_found

    Resource not found (or belongs to another account)

  • 409
    post_locked

    Post is being sent or already published

  • 422
    validation_error · invalid_parameter · invalid_network · invalid_schedule · invalid_media_url

    Invalid parameters (see “details”)

  • 429
    rate_limited

    Too many requests: wait “Retry-After” seconds

  • 500
    internal_error

    Error on our side: try again later

Need the API for your clients?

Write to us: we’ll enable the add-on on your account and answer your technical questions.

Contact us My API keys