{ "openapi": "3.1.0", "info": { "title": "SocialBrainAI Public API", "description": "SocialBrainAI public API — drive your sub-accounts (brands) from your own software.\n\n**Authentication**: send `Authorization: Bearer sba_live_…` with every request. Keys are created in\nthe SocialBrainAI app (Settings → API). A key is shown only once; it may be read-only or read/write and\nmay be restricted to some sub-accounts.\n\n**Rate limit**: 60 requests per minute per key (headers `X-RateLimit-Limit`, `X-RateLimit-Remaining`,\n`X-RateLimit-Reset`; `429` + `Retry-After` when exceeded).\n\n**Billing**: generations are paid in advance from the prepaid balance of the main account at catalogue\nprice (excl. tax). A started generation is never refunded automatically.\n\n**Approval**: posts created through the API are `pending_approval` unless approval was disabled for the\nAPI in the app.\n\n**Errors**: `{\"error\": {\"code\", \"message\", \"message_fr\", \"request_id\", \"details?\"}}`.\n", "version": "1.0.0" }, "paths": { "/me": { "get": { "tags": [ "Account" ], "summary": "Current API key and account", "operationId": "me_api_public_v1_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing, invalid or revoked API key (missing_api_key, invalid_api_key, revoked_api_key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API option disabled, read-only key, or sub-account not allowed (api_access_disabled, insufficient_scope, subaccount_forbidden).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (rate_limited).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/subaccounts": { "get": { "tags": [ "Account" ], "summary": "List sub-accounts", "operationId": "list_subaccounts_api_public_v1_subaccounts_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing, invalid or revoked API key (missing_api_key, invalid_api_key, revoked_api_key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API option disabled, read-only key, or sub-account not allowed (api_access_disabled, insufficient_scope, subaccount_forbidden).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (rate_limited).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/balance": { "get": { "tags": [ "Billing" ], "summary": "Prepaid balance of the main account", "operationId": "balance_api_public_v1_balance_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing, invalid or revoked API key (missing_api_key, invalid_api_key, revoked_api_key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API option disabled, read-only key, or sub-account not allowed (api_access_disabled, insufficient_scope, subaccount_forbidden).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (rate_limited).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/usage": { "get": { "tags": [ "Billing" ], "summary": "Consumption by sub-account over a period", "operationId": "usage_api_public_v1_usage_get", "parameters": [ { "name": "subaccount_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subaccount Id" } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Start (inclusive), default: 30 days ago.", "title": "From" }, "description": "Start (inclusive), default: 30 days ago." }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "End (exclusive), default: now.", "title": "To" }, "description": "End (exclusive), default: now." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 200, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Invalid parameters (validation_error, invalid_parameter…).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked API key (missing_api_key, invalid_api_key, revoked_api_key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API option disabled, read-only key, or sub-account not allowed (api_access_disabled, insufficient_scope, subaccount_forbidden).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (rate_limited).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/catalog": { "get": { "tags": [ "Generations" ], "summary": "Generation types and prices", "operationId": "catalog_api_public_v1_catalog_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing, invalid or revoked API key (missing_api_key, invalid_api_key, revoked_api_key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API option disabled, read-only key, or sub-account not allowed (api_access_disabled, insufficient_scope, subaccount_forbidden).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (rate_limited).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/posts": { "get": { "tags": [ "Posts" ], "summary": "List posts", "operationId": "list_posts_api_public_v1_posts_get", "parameters": [ { "name": "subaccount_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subaccount Id" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "draft", "pending_approval", "approved", "scheduled", "publishing", "published", "failed", "cancelled" ], "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "network", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Network" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Invalid parameters (validation_error, invalid_parameter…).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked API key (missing_api_key, invalid_api_key, revoked_api_key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API option disabled, read-only key, or sub-account not allowed (api_access_disabled, insufficient_scope, subaccount_forbidden).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (rate_limited).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Posts" ], "summary": "Create a post (one per network)", "operationId": "create_post_api_public_v1_posts_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Invalid parameters (validation_error, invalid_parameter…).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked API key (missing_api_key, invalid_api_key, revoked_api_key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API option disabled, read-only key, or sub-account not allowed (api_access_disabled, insufficient_scope, subaccount_forbidden).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (rate_limited).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/posts/{post_id}": { "get": { "tags": [ "Posts" ], "summary": "Get a post", "operationId": "get_post_api_public_v1_posts__post_id__get", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Post Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Invalid parameters (validation_error, invalid_parameter…).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked API key (missing_api_key, invalid_api_key, revoked_api_key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API option disabled, read-only key, or sub-account not allowed (api_access_disabled, insufficient_scope, subaccount_forbidden).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (rate_limited).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Posts" ], "summary": "Update a post (not yet published)", "operationId": "update_post_api_public_v1_posts__post_id__patch", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Post Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Invalid parameters (validation_error, invalid_parameter…).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked API key (missing_api_key, invalid_api_key, revoked_api_key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API option disabled, read-only key, or sub-account not allowed (api_access_disabled, insufficient_scope, subaccount_forbidden).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (rate_limited).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Posts" ], "summary": "Delete a post", "operationId": "delete_post_api_public_v1_posts__post_id__delete", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Post Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Invalid parameters (validation_error, invalid_parameter…).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked API key (missing_api_key, invalid_api_key, revoked_api_key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API option disabled, read-only key, or sub-account not allowed (api_access_disabled, insufficient_scope, subaccount_forbidden).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (rate_limited).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/posts/{post_id}/schedule": { "post": { "tags": [ "Posts" ], "summary": "Schedule a post", "operationId": "schedule_post_api_public_v1_posts__post_id__schedule_post", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Post Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSchedule" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Invalid parameters (validation_error, invalid_parameter…).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked API key (missing_api_key, invalid_api_key, revoked_api_key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API option disabled, read-only key, or sub-account not allowed (api_access_disabled, insufficient_scope, subaccount_forbidden).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (rate_limited).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/generations": { "post": { "tags": [ "Generations" ], "summary": "Request a generation (prepaid from balance)", "operationId": "create_generation_api_public_v1_generations_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationCreate" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Invalid parameters (validation_error, invalid_parameter…).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked API key (missing_api_key, invalid_api_key, revoked_api_key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API option disabled, read-only key, or sub-account not allowed (api_access_disabled, insufficient_scope, subaccount_forbidden).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (rate_limited).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance (insufficient_balance).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Generations" ], "summary": "List generation requests", "operationId": "list_generations_api_public_v1_generations_get", "parameters": [ { "name": "subaccount_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subaccount Id" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "pending", "processing", "completed", "failed" ], "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Invalid parameters (validation_error, invalid_parameter…).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked API key (missing_api_key, invalid_api_key, revoked_api_key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API option disabled, read-only key, or sub-account not allowed (api_access_disabled, insufficient_scope, subaccount_forbidden).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (rate_limited).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/generations/{generation_id}": { "get": { "tags": [ "Generations" ], "summary": "Get a generation request (status and result)", "operationId": "get_generation_api_public_v1_generations__generation_id__get", "parameters": [ { "name": "generation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Generation Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Invalid parameters (validation_error, invalid_parameter…).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked API key (missing_api_key, invalid_api_key, revoked_api_key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API option disabled, read-only key, or sub-account not allowed (api_access_disabled, insufficient_scope, subaccount_forbidden).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (rate_limited).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/creations": { "get": { "tags": [ "Generations" ], "summary": "List finished creations of a sub-account", "operationId": "list_creations_api_public_v1_creations_get", "parameters": [ { "name": "subaccount_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subaccount Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Invalid parameters (validation_error, invalid_parameter…).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked API key (missing_api_key, invalid_api_key, revoked_api_key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API option disabled, read-only key, or sub-account not allowed (api_access_disabled, insufficient_scope, subaccount_forbidden).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (rate_limited).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "GenerationCreate": { "properties": { "subaccount_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subaccount Id" }, "type": { "type": "string", "enum": [ "text_post", "carousel", "image", "product_video" ], "title": "Type" }, "params": { "type": "object", "title": "Params", "description": "Type-specific parameters: see GET /catalog." } }, "additionalProperties": false, "type": "object", "required": [ "type" ], "title": "GenerationCreate" }, "PostCreate": { "properties": { "subaccount_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subaccount Id", "description": "Sub-account ID. Optional when the key can only access one sub-account." }, "networks": { "items": { "type": "string", "enum": [ "instagram", "facebook", "tiktok", "youtube", "linkedin", "pinterest", "threads" ] }, "type": "array", "minItems": 1, "title": "Networks", "description": "Target networks: one post is created per network." }, "caption": { "type": "string", "maxLength": 5000, "title": "Caption", "default": "" }, "title": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Title" }, "hashtags": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Hashtags", "description": "Space-separated hashtags, e.g. '#promo #summer'." }, "media_urls": { "items": { "type": "string" }, "type": "array", "title": "Media Urls", "description": "Public https:// URLs of images or videos (max 10)." }, "content_type": { "anyOf": [ { "type": "string", "enum": [ "text", "image", "video", "carousel" ] }, { "type": "null" } ], "title": "Content Type", "description": "Guessed from media if omitted." }, "scheduled_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Scheduled At", "description": "ISO 8601 date-time (UTC if no offset). Must be in the future." } }, "additionalProperties": false, "type": "object", "required": [ "networks" ], "title": "PostCreate" }, "PostSchedule": { "properties": { "scheduled_at": { "type": "string", "format": "date-time", "title": "Scheduled At", "description": "ISO 8601 date-time, in the future." } }, "additionalProperties": false, "type": "object", "required": [ "scheduled_at" ], "title": "PostSchedule" }, "PostUpdate": { "properties": { "caption": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ], "title": "Caption" }, "title": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Title" }, "hashtags": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Hashtags" }, "media_urls": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Media Urls" }, "scheduled_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Scheduled At" } }, "additionalProperties": false, "type": "object", "title": "PostUpdate" }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "invalid_api_key" }, "message": { "type": "string", "example": "Invalid API key." }, "message_fr": { "type": "string", "example": "Clé d'API invalide." }, "request_id": { "type": "string", "example": "req_3f2a…" }, "details": { "type": "array", "items": { "type": "object" } } }, "required": [ "code", "message", "message_fr", "request_id" ] } }, "required": [ "error" ] } }, "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "sba_live_…" } } }, "servers": [ { "url": "https://socialbrainai.com/api/public/v1" } ], "security": [ { "ApiKey": [] } ] }