{ "openapi": "3.0.0", "info": { "description": "Unified social media inbox API. Read and respond to comments, DMs, reviews, and mentions across Instagram, Facebook, Threads, Google Business Profile, TikTok, LinkedIn, and YouTube through a single REST API. X/Twitter and Trustpilot coming soon.", "title": "SocialAPI.AI", "contact": { "name": "SocialAPI.AI Support", "email": "support@social-api.ai" }, "license": { "name": "MIT" }, "version": "1.0" }, "paths": { "/accounts": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns all active social media accounts connected to the authenticated API key's workspace.", "tags": [ "Accounts" ], "summary": "List connected accounts", "parameters": [ { "description": "Filter accounts by brand ID", "name": "brand_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of connected accounts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.AccountsListResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "429": { "description": "Daily rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/accounts/connect": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Initiates account connection. For OAuth2 platforms returns an auth_url to redirect the user to.\nFor apikey/credentials platforms stores the credentials immediately and returns account_id.\nFor WhatsApp, open auth_url to run Meta's signup. When the WhatsApp Business account holds several numbers, the redirect to your redirect_uri carries status=selection_required and a connection_id: list the numbers with GET /v1/accounts/pending/{connection_id} and pick one with POST /v1/accounts/pending/{connection_id}/select.\nSet the top-level redirect_uri field when connecting WhatsApp so the result reaches a page you control.", "tags": [ "Accounts" ], "summary": "Connect a social account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ConnectRequest" } } }, "description": "Platform and metadata", "required": true }, "responses": { "201": { "description": "Account connected (direct auth)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ConnectAccountResponse" } } } }, "202": { "description": "OAuth2 flow initiated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ConnectOAuthResponse" } } } }, "400": { "description": "Missing platform, unsupported platform, or invalid permissions (validation.permissions_empty, validation.permission_unknown)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "Plan limit reached (billing.platform_not_available or billing.brands_limit)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/accounts/pending/{connection_id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the candidates of a pending connection: the Google Business Profiles of a Google login that manages more than one, the LinkedIn member profile and company Pages of a LinkedIn authorization that offers more than one, or the phone numbers of a WhatsApp Business account that holds several. Choose one with the select endpoint.", "tags": [ "Accounts" ], "summary": "Get a pending account selection", "parameters": [ { "description": "Pending connection ID", "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.PendingConnectionDetailResponse" } } } }, "404": { "description": "Unknown, expired, or not owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/accounts/pending/{connection_id}/select": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Promotes a pending connection into a connected account. For Google, LinkedIn and WhatsApp, pass platform_account_id to choose exactly one candidate. For Facebook, pass page_ids with the subset of candidate Pages to assign to the brand. First selection wins; the pending connection is then consumed.", "tags": [ "Accounts" ], "summary": "Select the account or Pages to connect from a pending connection", "parameters": [ { "description": "Pending connection ID", "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.SelectProfileRequest" } } }, "description": "Chosen platform_account_id (Google) or page_ids (Facebook)", "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ConnectAccountResponse" } } } }, "400": { "description": "platform_account_id or page_ids not in the candidate set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Unknown, expired, or not owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/accounts/{id}": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Disconnects a connected account. It will no longer appear in the accounts list\nand all API calls using this account will return 404.", "tags": [ "Accounts" ], "summary": "Disconnect a social account", "parameters": [ { "description": "Account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Account disconnected" }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "description": "Replaces the permissions of a connected account. Send null for every permission, including ones added later. Removing a permission takes effect at once and immediately deletes the comments, messages, analytics and posts not published through SocialAPI that it covers, and adding the permission back does not restore them. Posts published through SocialAPI are kept. Adding a permission takes effect at once when the platform already granted it, otherwise reconnect the account to ask for it. Check effective_permissions in the response.", "tags": [ "Accounts" ], "summary": "Update an account's permissions", "parameters": [ { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.UpdateAccountPermissionsRequest" } } }, "description": "New permissions", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.Account" } } } }, "400": { "description": "Invalid body, missing permissions field, empty list, or unknown permission (validation.body_invalid, validation.field_required, validation.permissions_empty, validation.permission_unknown)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "The key's scopes do not include accounts:manage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/accounts/{id}/analytics": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns daily history for a connected account: follower levels, reach, and the other metrics the platform publishes. For the account's current figures, use the live insights routes instead.\nEach series names its metric kind (gauge for a level you may diff, flow for a per-day count you may sum) and the timezone its days were cut on. Every point also carries how many subjects contributed to that day, always present and always at least 1, even for a single-subject account.", "tags": [ "Analytics" ], "summary": "Get account analytics history", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": "2026-08-23", "description": "First day, YYYY-MM-DD. Defaults to 29 days before to.", "name": "from", "in": "query", "schema": { "type": "string" } }, { "example": "2026-09-21", "description": "Last day, YYYY-MM-DD. Defaults to today (UTC).", "name": "to", "in": "query", "schema": { "type": "string" } }, { "description": "Comma-separated metric names. Defaults to every stored metric.", "name": "metrics", "in": "query", "schema": { "type": "string" } }, { "description": "Narrow to one page of a multi-page account", "name": "page_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.AnalyticsResponseWrapper" } } } }, "400": { "description": "Malformed or inverted range, or a range wider than 400 days", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/accounts/{id}/boards": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the boards for a connected Pinterest account.", "tags": [ "Accounts" ], "summary": "List Pinterest boards", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.PinterestBoardsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates a board on Pinterest and returns it.", "tags": [ "Accounts" ], "summary": "Create Pinterest board", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.CreateBoardRequest" } } }, "description": "Board to create", "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.PinterestBoardItem" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/accounts/{id}/boards/{boardId}": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Deletes the board on Pinterest along with every pin saved to it. This cannot be undone.", "tags": [ "Accounts" ], "summary": "Delete Pinterest board", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Board ID", "name": "boardId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Board deleted" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "description": "Update a board. Privacy accepts only PUBLIC or SECRET.", "tags": [ "Accounts" ], "summary": "Update Pinterest board", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Board ID", "name": "boardId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.UpdateBoardRequest" } } }, "description": "Board update", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.PinterestBoardItem" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/accounts/{id}/creator-info": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns platform-specific creator settings needed before publishing (privacy levels, interaction toggles, posting availability). Currently supported for TikTok only; other platforms return 501.", "tags": [ "Accounts" ], "summary": "Get creator info for publishing", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Creator info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.CreatorInfoResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Platform does not support creator info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/accounts/{id}/export": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Enqueue an async analytics export job for a connected account. Subject to plan limits (exports per month, cooldown hours, concurrent export cap). For some TikTok accounts, include_transcript and include_vision are refused with 400 account.export_enrichment_not_supported; export again without them.", "tags": [ "Exports" ], "summary": "Create analytics export", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.CreateExportRequest" } } }, "description": "Export options", "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ExportAcceptedResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/accounts/{id}/limits": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns platform-specific quota data for a connected account as a key/value map where values are remaining counts. Keys are platform-defined - for example Instagram returns `posts_remaining`. An empty object is returned for platforms without usage limits.", "tags": [ "Usage" ], "summary": "Get platform usage limits", "parameters": [ { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Platform quota map (keys are platform-specific)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.UsageLimitsResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "Account requires reconnection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Platform does not expose usage limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/accounts/{id}/mentions": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Fetches posts where your brand account was mentioned or tagged. Results are sorted newest-first. Returns 501 for platforms that do not support mention tracking. On Instagram this returns only media your account was tagged in: @mentions written inside a post caption or inside a comment are never included, because Meta exposes no endpoint to poll them, and they are not currently delivered as mention.received webhooks either. On Threads, an account connected before 2026-10-17 gets an authorization error until it is reconnected.", "tags": [ "Mentions" ], "summary": "List brand mentions", "parameters": [ { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": "2026-02-01T00:00:00Z", "description": "Return only items created after this timestamp (RFC3339)", "name": "since", "in": "query", "schema": { "type": "string" } }, { "example": 20, "description": "Maximum number of results to return (1-100, default 20)", "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "description": "Pagination cursor returned by the previous response", "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of mentions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.MentionsListResponse" } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Platform does not support mention tracking", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/accounts/{id}/mentions/reply": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Replies, as a public comment, to a mention of the connected account, including on a third-party post where the normal comment-reply endpoint is not permitted. Provide media_id (the media/post the mention is on); set comment_id only when the mention was in a comment (omit it to reply to a mention in the post caption). Supported on Instagram, Facebook, Threads and Bluesky. Consumes 1 interaction credit.", "tags": [ "Mentions" ], "summary": "Reply to a mention", "parameters": [ { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "comment_id": { "type": "string" }, "media_id": { "type": "string" }, "text": { "type": "string" } } } } }, "description": "Reply content", "required": true }, "responses": { "200": { "description": "Reply posted with comment_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ReplyToCommentSuccessResponse" } } } }, "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "429": { "description": "Monthly interaction limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Platform does not support replying to mentions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/accounts/{id}/pages": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns pages (e.g. Facebook Pages) associated with a connected account.", "tags": [ "Accounts" ], "summary": "List account pages", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.PagesListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/accounts/{id}/pages/{pageId}": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Update a page's is_default or is_active status.", "tags": [ "Accounts" ], "summary": "Update account page", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Page ID", "name": "pageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.UpdatePageRequest" } } }, "description": "Page update", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.AccountPageResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/accounts/{id}/sync": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Reports whether a post sync is running for the account and when its posts were last refreshed. Poll this after POST /accounts/{id}/sync until state leaves \"syncing\". A failed sync carries the reason in error.", "tags": [ "Accounts" ], "summary": "Get the post sync status of a connected account", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current sync state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.AccountPostsSyncResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "The account was not granted the posts.read permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Refreshes one connected account's posts: new posts appear, engagement counts update, and Instagram and Facebook media links in platform_media are renewed. Instagram covers up to the 500 most recent posts, Facebook up to the 500 most recent per Page; other platforms cover up to the 25 most recent. Returns immediately: poll GET /accounts/{id}/sync until state leaves \"syncing\", then read the posts. A sync already running for the account is returned as-is. Each account can start a sync once every 15 minutes, and each day your plan allows 10 syncs per brand it includes (Enterprise is unlimited); the count resets at midnight UTC.", "tags": [ "Accounts" ], "summary": "Start a sync of a connected account's posts", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Sync started, or already running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.AccountPostsSyncResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "The account was not granted the posts.read permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "429": { "description": "accounts.sync_rate_limited: this account was synced less than 15 minutes ago. accounts.sync_daily_limit: the plan's daily sync limit is reached. The Retry-After header carries the seconds to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Platform cannot list posts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "503": { "description": "The sync could not be started. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/analytics/overview": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Summarises how the posts published in a range performed: totals against the previous range of equal length, engagement per publish day, breakdowns by platform and media type, the top posts, the hours your posts did best in, and the daily replies, DMs and moderation SocialAPI performed. Covers every account the key can read, or one account, brand, or platform.\nEngagements are likes + comments + shares + saves. Views are reported apart, by the platforms that publish them. Counters are the ones SocialAPI last synced (see metrics_synced_at), so this makes no platform call and costs no credits. Accounts without the analytics.read permission are left out and counted in accounts_excluded.", "tags": [ "Analytics" ], "summary": "Get analytics overview", "parameters": [ { "example": "2026-10-07", "description": "First day, YYYY-MM-DD, in tz. Defaults to 29 days before to.", "name": "from", "in": "query", "schema": { "type": "string" } }, { "example": "2026-11-05", "description": "Last day, YYYY-MM-DD, in tz. Defaults to today in tz.", "name": "to", "in": "query", "schema": { "type": "string" } }, { "example": "Europe/Paris", "description": "IANA time zone that days and hours are cut in. Defaults to UTC.", "name": "tz", "in": "query", "schema": { "type": "string" } }, { "description": "Narrow to one connected account", "name": "account_id", "in": "query", "schema": { "type": "string" } }, { "description": "Narrow to one brand", "name": "brand_id", "in": "query", "schema": { "type": "string" } }, { "example": "instagram", "description": "Narrow to one platform", "name": "platform", "in": "query", "schema": { "type": "string" } }, { "description": "Order of top_posts: engagements (default), likes, comments, shares, or views", "name": "sort", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.AnalyticsOverviewResponseWrapper" } } } }, "400": { "description": "Malformed or inverted range, a range wider than 400 days, an unknown tz, or an unknown sort", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account or brand not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/announcements": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns service announcements that are currently visible, newest first. Each item carries a `seen` flag for the calling user. `window_start` and `window_end` describe the announced maintenance window and are absent for non-maintenance announcements. Free operation, consumes no credits.", "tags": [ "Announcements" ], "summary": "List active announcements", "responses": { "200": { "description": "Currently visible announcements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.AnnouncementsListResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/announcements/{id}/seen": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Records that the calling user has seen an announcement, so it is not shown again. Idempotent: repeat calls succeed without changing anything. Free operation, consumes no credits.", "tags": [ "Announcements" ], "summary": "Mark an announcement as seen", "parameters": [ { "example": "9c1e7f2a-3b4d-4e5f-8a9b-0c1d2e3f4a5b", "description": "Announcement ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Announcement marked as seen", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.OKResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Announcement not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/automations": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Lists your Automations, newest first. Filter to one account with account_id.", "tags": [ "Automations" ], "summary": "List Automations", "parameters": [ { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID", "name": "account_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.AutomationListResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "The key's scopes do not include automations:read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates an Automation on an Instagram or Facebook account. When a comment or DM on the account matches its filters, its actions are carried out within seconds, with no code on your side. Each action costs what the same API call costs: reply_comment and send_dm cost 1 credit, private_reply and hide_comment are free. The first step's actions depend on the trigger: a comment trigger allows hide_comment, reply_comment and private_reply; a dm trigger allows send_dm. Steps after start run when the person taps one of your postback buttons, and may only send DMs. An account holds at most 50 Automations. Comments and messages sent by the account itself never trigger it; on Facebook that is the Page, so a Page admin commenting from their personal profile does trigger it. A dm Automation answers the same person at most 5 times an hour. Besides automations:write, a scoped key needs the scope each action's own API call needs: inbox:write for hide_comment, reply_comment and private_reply, dms:send for send_dm. Send follow_gate instead of steps to build a Follow gate: the commenter gets a private reply with a button, and a tap sends the link if they follow the account, otherwise a follow-first message with a button to try again. Instagram only.", "tags": [ "Automations" ], "summary": "Create an Automation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/social-api_ai_core_api_service.CreateAutomationParams" } } }, "description": "Automation definition", "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/social-api_ai_core_api_service.Automation" } } } }, "400": { "description": "Invalid definition (validation.*), or a trigger or action needs a permission the account does not have (validation.permission_missing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "The key's scopes do not include automations:write or the scope an action needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "409": { "description": "The account already has 50 Automations (automation.limit_reached)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "422": { "description": "The account is not on Instagram or Facebook (automation.platform_unsupported)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/automations/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns one Automation with its fired, sent and failed counts.", "tags": [ "Automations" ], "summary": "Get an Automation", "parameters": [ { "example": "aut_01J9Z8Y7X6W5V4T3S2R1Q0P9N8", "description": "Automation ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/social-api_ai_core_api_service.Automation" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "The key's scopes do not include automations:read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Automation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Deletes an Automation and its run history. Buttons it already sent stop doing anything.", "tags": [ "Automations" ], "summary": "Delete an Automation", "parameters": [ { "example": "aut_01J9Z8Y7X6W5V4T3S2R1Q0P9N8", "description": "Automation ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.SuccessResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "The key's scopes do not include automations:write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Automation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "description": "Updates the fields you send and keeps the rest. Set status to paused to stop the Automation and to active to resume it. steps replaces the whole list. Changed steps or post_ids must meet the same rules as creation. Renaming or pausing needs only automations:write; resuming, or changing steps, post_ids or once_per_person, also needs each action's own scope.", "tags": [ "Automations" ], "summary": "Update an Automation", "parameters": [ { "example": "aut_01J9Z8Y7X6W5V4T3S2R1Q0P9N8", "description": "Automation ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/social-api_ai_core_api_service.UpdateAutomationParams" } } }, "description": "Fields to change", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/social-api_ai_core_api_service.Automation" } } } }, "400": { "description": "Invalid definition (validation.*), or a trigger or action needs a permission the account does not have (validation.permission_missing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "The key's scopes do not include automations:write or the scope an action needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Automation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/automations/{id}/firings": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Lists the Automation's runs from the last 30 days, newest first, with the outcome of each action. A failed action carries the error code the same API call would have returned.", "tags": [ "Automations" ], "summary": "List an Automation's runs", "parameters": [ { "example": "aut_01J9Z8Y7X6W5V4T3S2R1Q0P9N8", "description": "Automation ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "next_cursor from the previous page", "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "description": "Page size, 1 to 100, default 20", "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.FiringListResponse" } } } }, "400": { "description": "limit is not a positive integer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "The key's scopes do not include automations:read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Automation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/billing/plans": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns every subscription tier with prices and resource limits, ordered from cheapest to most expensive. Each tier is priced in USD and in EUR. -1 means unlimited for limits and custom pricing for prices.", "tags": [ "Billing" ], "summary": "List plans", "responses": { "200": { "description": "Plan catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.BillingPlansResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/brands": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns all brands for the authenticated user with their connected account counts.", "tags": [ "Brands" ], "summary": "List brands", "responses": { "200": { "description": "List of brands", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.BrandsListResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates a new brand for grouping connected social accounts. Each brand can have one account per platform.", "tags": [ "Brands" ], "summary": "Create a brand", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.CreateBrandRequest" } } }, "description": "Brand name", "required": true }, "responses": { "201": { "description": "Brand created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.BrandResponse" } } } }, "400": { "description": "Invalid request body or missing name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "Brand limit reached for plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/brands/{id}": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Deletes a brand and disconnects all its connected accounts.", "tags": [ "Brands" ], "summary": "Delete a brand", "parameters": [ { "description": "Brand ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Brand deleted" }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Brand not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "description": "Renames a brand.", "tags": [ "Brands" ], "summary": "Update a brand", "parameters": [ { "description": "Brand ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.UpdateBrandRequest" } } }, "description": "New name", "required": true }, "responses": { "200": { "description": "Brand updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.BrandResponse" } } } }, "400": { "description": "Invalid request body or missing name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Brand not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/brands/{id}/analytics": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns daily history for every account and page in a brand, summed per metric per day. A brand total always reflects the accounts the brand holds right now.\nRead subjects_counted before drawing a chart. A brand whose accounts did not all report on a given day produces a lower sum for that day, and without the count that reads as a decline instead of a gap.", "tags": [ "Analytics" ], "summary": "Get brand analytics history", "parameters": [ { "description": "Brand ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": "2026-08-23", "description": "First day, YYYY-MM-DD. Defaults to 29 days before to.", "name": "from", "in": "query", "schema": { "type": "string" } }, { "example": "2026-09-21", "description": "Last day, YYYY-MM-DD. Defaults to today (UTC).", "name": "to", "in": "query", "schema": { "type": "string" } }, { "description": "Comma-separated metric names. Defaults to every stored metric.", "name": "metrics", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.AnalyticsResponseWrapper" } } } }, "400": { "description": "Malformed or inverted range, or a range wider than 400 days", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Brand not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/events": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns a paginated, filtered slice of the unified event log. Events cover post lifecycle, inbox activity, account changes, and webhook deliveries. Retention varies by plan tier; the response includes the user's current retention window.", "tags": [ "Events" ], "summary": "List developer events", "parameters": [ { "description": "Filter by event category", "name": "category", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by status (ok, failed)", "name": "status", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by platform", "name": "platform", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by connected account ID", "name": "account_id", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by resource ID (post, conversation, ...)", "name": "resource_id", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by action (e.g. post.published)", "name": "action", "in": "query", "schema": { "type": "string" } }, { "description": "Lower time bound (RFC3339)", "name": "from", "in": "query", "schema": { "type": "string" } }, { "description": "Upper time bound (RFC3339)", "name": "to", "in": "query", "schema": { "type": "string" } }, { "description": "Pagination cursor from a previous response", "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "description": "Page size (default 50)", "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.EventsListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/events/summary": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns aggregated event counts for the requested window: totals, failure counts, breakdowns by category and error category, plus inbox-specific breakdown. Useful for dashboard summary cards.", "tags": [ "Events" ], "summary": "Event summary counts", "parameters": [ { "description": "Lower time bound (RFC3339)", "name": "from", "in": "query", "schema": { "type": "string" } }, { "description": "Upper time bound (RFC3339)", "name": "to", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.EventsSummaryResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/exports": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the 50 most recent export jobs for the authenticated user. Optionally filter by status.", "tags": [ "Exports" ], "summary": "List analytics exports", "parameters": [ { "description": "Filter by status (pending, processing, completed, failed)", "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ExportsListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/exports/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the current status, progress, result download URL (presigned Excel), and report URL for an export job.", "tags": [ "Exports" ], "summary": "Get export status and result", "parameters": [ { "description": "Export ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ExportStatusResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/exports/{id}/videos": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the video data for a completed export, including metrics and optional AI-enriched fields (transcript, vision summary).", "tags": [ "Exports" ], "summary": "Get export videos", "parameters": [ { "description": "Export ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ExportVideosResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/feedback": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Submit feedback (bug report, feature request, or general comment). Routed to the SocialAPI team.", "tags": [ "Feedback" ], "summary": "Send feedback", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.SendFeedbackRequest" } } }, "description": "Feedback type and message", "required": true }, "responses": { "200": { "description": "Feedback received", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.OKResponse" } } } }, "400": { "description": "Invalid type or empty message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/inbox/comments": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns inbox posts that have comments, ordered by most-recently-commented. Supports filtering by account, platform, minimum comment count, and date range. Uses cursor-based pagination. YouTube commented posts only appear when the request is scoped with account_id (they are absent from the unfiltered aggregate), and that list returns a single page (no cursor).", "tags": [ "Inbox Comments" ], "summary": "List commented posts", "parameters": [ { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Filter by connected account ID", "name": "account_id", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by brand ID (returns only posts from accounts in this brand)", "name": "brand_id", "in": "query", "schema": { "type": "string" } }, { "example": "instagram", "description": "Filter by platform (instagram, facebook, threads, tiktok, youtube, twitter, bluesky, whatsapp)", "name": "platform", "in": "query", "schema": { "type": "string" } }, { "example": 1, "description": "Only return posts with at least this many comments (default 0)", "name": "min_comments", "in": "query", "schema": { "type": "integer" } }, { "example": "2026-01-01T00:00:00Z", "description": "Only return posts commented after this timestamp (RFC3339)", "name": "since", "in": "query", "schema": { "type": "string" } }, { "example": "date", "description": "Sort field: date (default)", "name": "sort_by", "in": "query", "schema": { "type": "string" } }, { "example": "desc", "description": "Sort direction: desc (default) or asc", "name": "sort_order", "in": "query", "schema": { "type": "string" } }, { "example": 25, "description": "Max results per page (default 25)", "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "description": "Pagination cursor from previous response", "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of commented posts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.CommentedPostsListResponse" } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/inbox/comments/{postId}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns comments for a specific inbox post, including per-platform capability flags (can_reply, can_delete, can_hide, can_like, can_private_reply). Uses cursor-based pagination.", "tags": [ "Inbox Comments" ], "summary": "List comments on a post", "parameters": [ { "example": "17895695668004550", "description": "Platform post ID", "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID that owns the post", "name": "account_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "example": 25, "description": "Results per page (default 25). Some platforms return fewer, and on TikTok the first page can return more", "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "description": "Pagination cursor from previous response", "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "example": "held_for_review", "description": "Filter by moderation status: published (default), held_for_review, likely_spam. YouTube only; other platforms do not filter by it.", "name": "moderation_status", "in": "query", "schema": { "type": "string" } }, { "example": "relevance", "description": "Order: recent (default) or relevance. YouTube only; other platforms do not sort by it.", "name": "order", "in": "query", "schema": { "type": "string" } }, { "example": "great video", "description": "Keyword search across comment text (max 256 chars). YouTube only; other platforms do not filter by it.", "name": "q", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of comments with capabilities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.CommentsWithCapsListResponse" } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Post not found in inbox", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Posts a reply on the platform. If comment_id is provided, replies to that specific comment (threaded reply); otherwise replies to the post itself (top-level comment). Consumes 1 interaction credit.", "tags": [ "Inbox Comments" ], "summary": "Reply to a comment", "parameters": [ { "example": "17895695668004550", "description": "Platform post ID", "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "string" }, "comment_id": { "type": "string" }, "text": { "type": "string" } } } } }, "description": "Reply content", "required": true }, "responses": { "200": { "description": "Reply posted with comment_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ReplyToCommentSuccessResponse" } } } }, "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "429": { "description": "Monthly interaction limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Platform does not support comment replies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/inbox/comments/{postId}/{commentId}": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Deletes a comment on the platform and removes it from the inbox. Not all platforms support comment deletion - check the can_delete capability flag.", "tags": [ "Inbox Comments" ], "summary": "Delete a comment", "parameters": [ { "example": "17895695668004550", "description": "Platform post ID", "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": "17858893269577012", "description": "Platform comment ID to delete", "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID", "name": "account_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Comment deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.SuccessResponse" } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "The key's scopes do not include inbox:write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Platform does not support comment deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/inbox/comments/{postId}/{commentId}/hide": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Hides a comment on the platform so it is not visible to the public, and marks it hidden in the inbox. Supported on Instagram, Facebook, Threads (replies from other accounts), X (replies to the account's own posts), YouTube, Bluesky (replies in threads the account started), and TikTok (default connection, not a creator connection; comments written by other people). Check the can_hide capability flag. On Threads, an account connected before 2026-10-17 gets an authorization error until it is reconnected.", "tags": [ "Inbox Comments" ], "summary": "Hide a comment", "parameters": [ { "example": "17895695668004550", "description": "Platform post ID", "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": "17858893269577012", "description": "Platform comment ID to hide", "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "string" } } } } }, "description": "Account that owns the post", "required": true }, "responses": { "200": { "description": "Comment hidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.SuccessResponse" } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "The key's scopes do not include inbox:write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Platform does not support hiding comments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Restores a previously hidden comment so it is publicly visible again. Supported on the same platforms as hiding: Instagram, Facebook, Threads, X, YouTube, Bluesky, and TikTok. On Threads, an account connected before 2026-10-17 gets an authorization error until it is reconnected.", "tags": [ "Inbox Comments" ], "summary": "Unhide a comment", "parameters": [ { "example": "17895695668004550", "description": "Platform post ID", "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": "17858893269577012", "description": "Platform comment ID to unhide", "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID", "name": "account_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Comment unhidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.SuccessResponse" } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "The key's scopes do not include inbox:write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Platform does not support hiding comments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/inbox/comments/{postId}/{commentId}/like": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Likes a comment on the platform as the connected account. Supported on Facebook, LinkedIn Pages, and Instagram accounts connected with Facebook Login. Instagram accounts connected with Instagram Login cannot like comments. Check the can_like capability flag.", "tags": [ "Inbox Comments" ], "summary": "Like a comment", "parameters": [ { "example": "17895695668004550", "description": "Platform post ID", "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": "17858893269577012", "description": "Platform comment ID to like", "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "string" } } } } }, "description": "Account to like as", "required": true }, "responses": { "200": { "description": "Comment liked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.SuccessResponse" } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "The key's scopes do not include inbox:write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Platform does not support comment likes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Removes a like from a comment on the platform. Supported on Facebook, LinkedIn Pages, and Instagram accounts connected with Facebook Login. Check the can_like capability flag.", "tags": [ "Inbox Comments" ], "summary": "Unlike a comment", "parameters": [ { "example": "17895695668004550", "description": "Platform post ID", "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": "17858893269577012", "description": "Platform comment ID to unlike", "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID", "name": "account_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Comment unliked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.SuccessResponse" } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "The key's scopes do not include inbox:write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Platform does not support comment likes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/inbox/comments/{postId}/{commentId}/private-reply": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Sends a direct message to the author of a comment. Only supported on Instagram and Facebook. Meta allows one private reply per comment, within 7 days of the comment; a second attempt or an expired window returns HTTP 400 with error code platform.instagram.private_reply_ineligible or platform.facebook.private_reply_ineligible. Once a comment has spent its one reply, or the comment is older than 7 days, further attempts are refused and do not count against your outbound message rate; the error carries a reason of already_replied, platform_refused or window_expired. The 400 is terminal: retrying it will never succeed. Set buttons (1 to 3) to send the reply as a button template with text as its body; a tap on a postback button arrives as a dm.postback event. Set attachment instead of text to send one image, video, audio or file: a private reply is a single message, so it carries either text (with optional buttons) or one attachment, never both. You cannot message the commenter again until they respond; once they do, the conversation continues within the standard 24-hour messaging window. Check the can_private_reply capability flag.", "tags": [ "Inbox Comments" ], "summary": "Send a private reply to a commenter", "parameters": [ { "example": "17895695668004550", "description": "Platform post ID", "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": "17858893269577012", "description": "Platform comment ID", "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.PrivateReplyRequest" } } }, "description": "Private reply content", "required": true }, "responses": { "200": { "description": "Private reply sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.SuccessResponse" } } } }, "400": { "description": "Missing required fields, attachment combined with text or buttons (validation.attachment_conflict), or comment not eligible for a private reply (platform.instagram.private_reply_ineligible, platform.facebook.private_reply_ineligible)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "The key's scopes do not include inbox:write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "422": { "description": "The platform could not fetch or accept the attachment (platform.instagram.attachment_failed, platform.facebook.attachment_failed). The comment can still receive a private reply: fix the URL or file and send again", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Platform does not support private replies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/inbox/comments/{postId}/{commentId}/replies": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns paginated replies to a specific comment. Same response shape as top-level comments. Uses cursor-based pagination.", "tags": [ "Inbox Comments" ], "summary": "List replies to a comment", "parameters": [ { "example": "17895695668004550", "description": "Platform post ID", "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": "17858893269577012", "description": "Platform comment ID to get replies for", "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID that owns the post", "name": "account_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "example": 10, "description": "Max results per page (default 10)", "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "description": "Pagination cursor from previous response", "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of replies with capabilities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.CommentsWithCapsListResponse" } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Platform does not support comment replies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/inbox/conversations": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns paginated DM conversations for the authenticated user, optionally filtered by account, platform, and status.", "tags": [ "Inbox" ], "summary": "List inbox conversations", "parameters": [ { "description": "Filter by connected account ID", "name": "account_id", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by brand ID (returns only conversations from accounts in this brand)", "name": "brand_id", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by Facebook/Instagram page ID (for multi-page accounts)", "name": "page_id", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by platform (instagram, facebook, …)", "name": "platform", "in": "query", "schema": { "type": "string" } }, { "description": "Conversation status: active (default) or archived", "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "archived" ] } }, { "description": "Max results (1–100, default 25)", "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "description": "Pagination cursor from previous response", "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of conversations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ConversationsListResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/inbox/conversations/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns a single inbox conversation by ID.", "tags": [ "Inbox" ], "summary": "Get a conversation", "parameters": [ { "description": "Conversation ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Conversation details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ConversationResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "description": "Sets the status of a conversation to active or archived.", "tags": [ "Inbox" ], "summary": "Update conversation status", "parameters": [ { "description": "Conversation ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.UpdateConversationRequest" } } }, "description": "Status payload", "required": true }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.SuccessResponse" } } } }, "400": { "description": "Invalid request body or status value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/inbox/conversations/{id}/messages": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns paginated messages for an inbox conversation, newest first.", "tags": [ "Inbox" ], "summary": "List messages in a conversation", "parameters": [ { "description": "Conversation ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Max results (1–200, default 25)", "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "description": "Pagination cursor from previous response", "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of messages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.MessagesListResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Sends an outgoing DM via the connected platform account and records it in the conversation.", "tags": [ "Inbox" ], "summary": "Send a message in a conversation", "parameters": [ { "description": "Conversation ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.SendMessageRequest" } } }, "description": "Message payload", "required": true }, "responses": { "200": { "description": "Message sent with ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.SendMessageResponse" } } } }, "400": { "description": "Invalid request body, missing required fields, or messaging window closed (platform.instagram.window_closed / platform.facebook.window_closed: the recipient must message you first to reopen the 24-hour window). After the platform refuses a thread for a closed window, later untagged sends on it are refused here with the same code and blocked_locally in the meta, until an inbound message reopens it or 24 hours pass; no credit is charged for those.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "Platform rejected the request (e.g. platform.instagram.permission_denied), or account requires reconnection (account.reconnection_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Conversation or account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "422": { "description": "The platform could not fetch or accept an attachment (platform.instagram.attachment_failed, platform.facebook.attachment_failed): check that the URL is publicly reachable and the file type and size are supported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "429": { "description": "Platform rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Platform does not support sending DMs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/inbox/conversations/{id}/messages/{messageId}/reaction": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Adds or replaces the account's emoji reaction on a message. Send the emoji character itself. Supported on Instagram and Facebook Messenger.", "tags": [ "Inbox Conversations" ], "summary": "React to a message", "parameters": [ { "example": "conv_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Conversation ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": "m_AbCdEfGhIjKl", "description": "Platform message ID to react to", "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ReactToMessageRequest" } } }, "description": "Account and emoji", "required": true }, "responses": { "200": { "description": "Reaction applied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.SuccessResponse" } } } }, "400": { "description": "Invalid body, missing account_id, or reaction is not a single emoji", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Conversation or account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Platform does not support message reactions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "Upstream platform API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Removes the account's emoji reaction from a message.", "tags": [ "Inbox Conversations" ], "summary": "Remove a reaction from a message", "parameters": [ { "example": "conv_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Conversation ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": "m_AbCdEfGhIjKl", "description": "Platform message ID to remove the reaction from", "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID", "name": "account_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reaction removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.SuccessResponse" } } } }, "400": { "description": "Missing account_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Conversation or account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Platform does not support message reactions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "Upstream platform API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/inbox/conversations/{id}/read": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Resets the unread count on a conversation to zero.", "tags": [ "Inbox" ], "summary": "Mark conversation as read", "parameters": [ { "description": "Conversation ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Marked as read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.SuccessResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/inbox/media/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the bytes of an inbound attachment. 504 means retry shortly, not gone.", "tags": [ "Inbox" ], "summary": "Get inbox media", "parameters": [ { "description": "Inbox media ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Unknown media, or not owned by the caller", "content": { "application/octet-stream": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "410": { "description": "Media expired or permanently unavailable", "content": { "application/octet-stream": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "503": { "description": "Too many concurrent waiters, retry shortly", "content": { "application/octet-stream": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "504": { "description": "Fetch still in progress, retry shortly", "content": { "application/octet-stream": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/inbox/reviews": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Lists your review-capable connected Accounts, each with its live review summary (average rating, total count, last review time). Use this to build the reviews inbox navigation, then GET /inbox/reviews/{account_id} for one Account's reviews.", "tags": [ "Inbox Reviews" ], "summary": "List Accounts with reviews", "parameters": [ { "example": "google", "description": "Filter by platform (google, app_store_connect)", "name": "platform", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accounts with review summaries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ReviewAccountsResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/inbox/reviews/{account_id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns one page of reviews for a single connected Account, newest first by default. Supported on Google Business Profile and App Store Connect. App Store Connect reviews also carry a title; App Store Connect does not report an average rating, so summary.average_rating is 0 for those Accounts.", "tags": [ "Inbox Reviews" ], "summary": "List reviews for an Account", "parameters": [ { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID", "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": 20, "description": "Max results (1-50, default 20)", "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "description": "Pagination cursor from previous response", "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "description": "Sort order", "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "newest", "rating_asc", "rating_desc" ] } } ], "responses": { "200": { "description": "Reviews with summary and pagination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ReviewsListResponse" } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "422": { "description": "Account platform does not support reviews (account.platform_unsupported)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/inbox/reviews/{id}/reply": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Posts a public reply to a review on the platform (Google Business Profile, App Store Connect). Consumes 1 interaction credit. On Google, replies are moderated: a successful response returns state PENDING and the reply is not publicly visible until it becomes APPROVED. A rejected reply is never published, and the reason is reported as policy_violation on the review. On App Store Connect, replying again replaces your earlier response, and a response can take up to 24 hours to appear on the App Store.", "tags": [ "Inbox Reviews" ], "summary": "Reply to a review", "parameters": [ { "example": "AbCdEf123456", "description": "Review ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ReplyReviewRequest" } } }, "description": "Reply content", "required": true }, "responses": { "200": { "description": "Reply posted with reply_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ReplyToReviewResponse" } } } }, "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "Account requires reconnection (account.reconnection_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "422": { "description": "Account platform does not support reviews (account.platform_unsupported)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "429": { "description": "Monthly interaction limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/inbox/sync": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Reports whether a sync is running for the given target and when that target last completed one. Poll this after POST /inbox/sync until state leaves \"syncing\", then refetch the conversation or message list.", "tags": [ "Inbox" ], "summary": "Get inbox sync status", "parameters": [ { "description": "Connected account ID", "name": "account_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "description": "Conversation ID, to report on a thread sync instead of the account's list", "name": "conversation_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current sync state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.InboxSyncResponse" } } } }, "400": { "description": "Missing account_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account or conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Refreshes an account's inbox from the platform. Add conversation_id to refresh a single thread instead. Returns immediately: poll GET /inbox/sync until state leaves \"syncing\". A sync already running for the same target is returned as-is rather than duplicated.", "tags": [ "Inbox" ], "summary": "Start an inbox sync", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.InboxSyncRequest" } } }, "description": "Sync target", "required": true }, "responses": { "202": { "description": "Sync started, or already running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.InboxSyncResponse" } } } }, "400": { "description": "Missing or invalid account_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account or conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "429": { "description": "A sync for this target ran too recently. The Retry-After header carries the seconds to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/invite/{token}": { "get": { "description": "Public endpoint (no auth). Validates the invite token and redirects the user\nto the platform's OAuth authorization page. On successful OAuth callback,\nthe account is connected to the invite creator's brand.", "tags": [ "Invites" ], "summary": "Redeem an invite link", "parameters": [ { "description": "Invite token", "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to platform OAuth" }, "404": { "description": "Invite not found", "content": { "*/*": { "schema": { "type": "string" } } } }, "410": { "description": "Invite expired or already used", "content": { "*/*": { "schema": { "type": "string" } } } } } } }, "/invites": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns all invites (active and used/expired) for a brand, ordered by created_at DESC.", "tags": [ "Invites" ], "summary": "List invites for a brand", "parameters": [ { "description": "Brand ID", "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of invites", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.InviteListResponse" } } } }, "400": { "description": "Missing brand_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Brand not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates a single-use invite link for an external user to connect a social account to a brand.\nThe brand must not already have a connected account for the specified platform, and\nno active (unused, unexpired) invite may exist for the same brand+platform combination.", "tags": [ "Invites" ], "summary": "Create an invite link", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.CreateInviteRequest" } } }, "description": "Invite details", "required": true }, "responses": { "201": { "description": "Invite created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.InviteResponse" } } } }, "400": { "description": "Missing or invalid fields, or invalid permissions (validation.permissions_empty, validation.permission_unknown)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Brand not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "409": { "description": "Account or active invite already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/invites/{id}": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Marks an invite as used (revoked), preventing it from being redeemed.", "tags": [ "Invites" ], "summary": "Revoke an invite", "parameters": [ { "description": "Invite ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Invite revoked" }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Invite not found or already used", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/keys": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns all API keys for the authenticated user, including each key's scope and brand restrictions.", "tags": [ "API Keys" ], "summary": "List API keys", "responses": { "200": { "description": "List of API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.KeysListResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Generates a new API key for the authenticated user. Optionally restrict it to a set of scopes (see GET /keys/scopes) and/or brands. Empty scopes or brand_ids mean unrestricted.", "tags": [ "API Keys" ], "summary": "Create API key", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.CreateKeyRequest" } } }, "description": "Key name and optional restrictions", "required": true }, "responses": { "201": { "description": "Key created (raw key shown once)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.CreateKeyResponse" } } } }, "400": { "description": "Invalid request body, missing name, unknown scope, or invalid brand ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/keys/scopes": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the catalog of scopes assignable to restricted API keys.", "tags": [ "API Keys" ], "summary": "List API key scopes", "responses": { "200": { "description": "Scope catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.KeyScopesResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/keys/{id}": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Deactivates an API key. This is irreversible.", "tags": [ "API Keys" ], "summary": "Revoke API key", "parameters": [ { "description": "API key ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Key revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.OKResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "API key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "description": "Edits an existing key's name, scopes, and brand restrictions in place. The key value is unchanged (no new secret is issued). Empty scopes or brand_ids mean unrestricted. Requires a full-access key or the dashboard.", "tags": [ "API Keys" ], "summary": "Update API key", "parameters": [ { "description": "API key ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.UpdateKeyRequest" } } }, "description": "New name and restrictions", "required": true }, "responses": { "200": { "description": "Key updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.UpdateKeyResponse" } } } }, "400": { "description": "Invalid request body, missing name, unknown scope, or invalid brand ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "API key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/keys/{id}/rotate": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Issues a new secret for an existing key, keeping its id, name, scopes, and brand restrictions. The old key value stops working immediately. The new raw key is shown once. Requires a full-access key or the dashboard.", "tags": [ "API Keys" ], "summary": "Rotate API key", "parameters": [ { "description": "API key ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Key rotated (new raw key shown once)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.CreateKeyResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "API key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/media": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns a paginated list of uploaded media files for the authenticated user.", "tags": [ "Media" ], "summary": "List media files", "parameters": [ { "description": "Max results (default 50, max 100)", "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "description": "Pagination cursor (media ID)", "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.MediaListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/media/storage": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns total bytes used, the plan limit, and file count for the authenticated user.", "tags": [ "Media" ], "summary": "Get storage usage", "responses": { "200": { "description": "OK", "headers": { "X-Storage-Limit": { "description": "Storage limit in bytes (-1 = unlimited)", "schema": { "type": "integer" } }, "X-Storage-Used": { "description": "Bytes of storage used", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.StorageUsageResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/media/upload": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Upload a media file directly through the API.", "tags": [ "Media" ], "summary": "Upload media (server-side)", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "description": "Media file to upload (max 50 MB)", "type": "string", "format": "binary" } }, "required": [ "file" ] } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.MediaUploadResponse" } } } }, "400": { "description": "Missing file or exceeds 50 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "413": { "description": "Storage quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/media/upload-url": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns a presigned PUT URL for client-side media upload. Upload the file directly\nvia HTTP PUT to the returned URL, then call POST /v1/media/:id/verify to confirm.", "tags": [ "Media" ], "summary": "Get a presigned media upload URL", "parameters": [ { "example": "image/jpeg", "description": "MIME type (e.g. image/jpeg)", "name": "media_type", "in": "query", "required": true, "schema": { "type": "string" } }, { "example": "photo.jpg", "description": "Original filename", "name": "filename", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.MediaUploadInfoResponse" } } } }, "400": { "description": "Missing media_type or filename", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "413": { "description": "Storage quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/media/{id}": { "delete": { "security": [ { "BearerAuth": [] } ], "tags": [ "Media" ], "summary": "Delete a media file", "parameters": [ { "description": "Media ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/media/{id}/verify": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Confirms that a presigned-URL upload completed successfully and marks the media as ready.", "tags": [ "Media" ], "summary": "Verify a media upload", "parameters": [ { "example": "550e8400-e29b-41d4-a716-446655440000", "description": "Media ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Upload verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.SuccessResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Media not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/migrations": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Starts a migration from another provider with an API key from your account there, and returns the first assessment of your accounts. Calling it again replaces the key. You must accept the current authorisation text: send its `version` from `GET /v1/migrations/{provider}`. Dashboard sessions only; API keys get 403.", "tags": [ "Migration" ], "summary": "Start a migration", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.StartMigrationRequest" } } }, "description": "Provider, key and accepted authorisation version", "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.MigrationResponse" } } } }, "400": { "description": "Invalid body, unknown provider, or authorisation not accepted (`migration.authorisation_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "Dashboard session required, the feature is not available on your account yet (`auth.beta_only`), or your role cannot manage migrations; ask an Admin or the Owner (`auth.insufficient_role`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "409": { "description": "Another SocialAPI account is already migrating this provider account (`migration.already_claimed`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "422": { "description": "The provider rejected the key (`migration.key_invalid`), or it lacks read access to profiles or accounts (`migration.key_restricted`, `meta.required_group` names what is missing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "The provider did not answer; retry (`migration.source_unavailable`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/migrations/{provider}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns your migration from a provider: the authorisation text to accept before starting, and once started, your accounts, the Brands and plan they need, and progress. If the provider cannot be read, the response is still 200 with `assessment` null and `assessment_error` set. The assessment can be up to 5 minutes old unless `refresh` is true. Dashboard sessions only; API keys get 403.", "tags": [ "Migration" ], "summary": "Get a migration", "parameters": [ { "description": "Provider identifier", "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "true to read your accounts now", "name": "refresh", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.MigrationResponse" } } } }, "400": { "description": "Unknown provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "Dashboard session required, or the feature is not available on your account yet (`auth.beta_only`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Stops the migration from a provider. Requests sent through the base URL with that key stop working. Dashboard sessions only; API keys get 403.", "tags": [ "Migration" ], "summary": "Stop a migration", "parameters": [ { "description": "Provider identifier", "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Unknown provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "Dashboard session required, the feature is not available on your account yet (`auth.beta_only`), or your role cannot manage migrations; ask an Admin or the Owner (`auth.insufficient_role`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "No migration from this provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/oauth/exchange": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Exchanges an OAuth authorization code for a connected social account. Use this when\nyou handle the OAuth callback on your own server (proxy flow). For a single account\nthe response is a flat ConnectAccountResponse (HTTP 201). When a single OAuth flow\nconnects multiple accounts (e.g. Facebook Pages) the response is OAuthCallbackResponse.", "tags": [ "Accounts" ], "summary": "Exchange OAuth code", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ExchangeRequest" } } }, "description": "Platform, code, and metadata (redirect_uri + state required)", "required": true }, "responses": { "200": { "description": "Google login manages multiple Business Profiles; select one", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.PendingConnectionResponse" } } } }, "201": { "description": "Single account connected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ConnectAccountResponse" } } } }, "400": { "description": "Missing or invalid fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "Plan limit reached (billing.platform_not_available or billing.brands_limit)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/facebook/accounts/{id}/insights/daily": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns one point per day for one Page of a connected Facebook account: followers at the end of the day, plus that day's views, reach and post engagements. Days with no data are omitted. Same permission errors as the Page insights summary.", "tags": [ "Facebook" ], "summary": "Get daily Facebook Page insights", "parameters": [ { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Page to report on, the id from GET /accounts/{id}/pages. Defaults to the account's default Page.", "name": "page_id", "in": "query", "schema": { "type": "string" } }, { "description": "Trailing days to return, 1 to 365. Defaults to 365.", "name": "days", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Daily Page insights, oldest first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.FacebookDailyInsightsResponse" } } } }, "400": { "description": "days out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "Page connected without the insights permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found, or page_id is not an active Page of this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "Upstream Facebook API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/facebook/accounts/{id}/summary": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns trailing-30-day Page insight aggregates (followers, views, reach, post engagements, net follower change) for one Page of a connected Facebook account. A Page connected before 2026-10-17, or whose login declined the insights permission, returns 403 platform.facebook.insights_scope_missing and must be reconnected.", "tags": [ "Facebook" ], "summary": "Get Facebook Page insights summary", "parameters": [ { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Page to report on, the id from GET /accounts/{id}/pages. Defaults to the account's default Page.", "name": "page_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page insights summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.FacebookAccountSummaryResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "Page connected without the insights permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found, or page_id is not an active Page of this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "Upstream Facebook API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/facebook/logins/{loginId}/pages": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Lists every Page this login can manage, live from Meta, merged with assignment state. Pages granted after the last OAuth exchange appear here without re-authenticating. assignable reflects ownership only; the 5-page-per-brand cap is enforced when assigning.", "tags": [ "Facebook" ], "summary": "List a Facebook login's Pages", "parameters": [ { "description": "Facebook login (credential) ID", "name": "loginId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.FacebookLoginPagesResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Unknown login", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/facebook/logins/{loginId}/pages/{pageId}/assign": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Assigns one Page from this login to the given brand. Each Page belongs to exactly one brand, so a Page currently held by another brand of yours is moved to the target brand. Each brand can connect up to 5 Facebook Pages, a hard cap. Assigning beyond that limit is refused.", "tags": [ "Facebook" ], "summary": "Assign a Facebook Page to a brand", "parameters": [ { "description": "Facebook login (credential) ID", "name": "loginId", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Platform page ID", "name": "pageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.AssignPageRequest" } } }, "description": "Target brand", "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.AssignPageResponse" } } } }, "403": { "description": "Brand already holds as many Facebook Pages as the plan allows (platform.facebook.page_cap)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Unknown login or brand", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "409": { "description": "Brand connected through a different login", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/google/accounts/{id}": { "put": { "security": [ { "BearerAuth": [] } ], "description": "Writes the location's public profile: name, description, phone numbers, address, website, categories, opening hours, service area. Only the fields you send are touched. A field you omit is left as it is, and a field you send with an empty value is CLEARED, which is how you remove a phone number or a website. Fields Google owns are not writable and are rejected: place_id, maps_uri, new_review_uri and the status flags are output-only, and language_code is fixed when the location is created. Google moderates these edits, so a 200 means the change was accepted for review rather than already live on Search and Maps; read the location back to see what is live and check has_pending_edits. Google allows 10 edits per minute per Business Profile and that limit cannot be raised. Pass validate_only=true to have Google check the change without applying it, which is the only way to test against a real profile since the API has no sandbox.", "tags": [ "Google" ], "summary": "Update a Google Business Profile location", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Validate the change without applying it", "name": "validate_only", "in": "query", "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPLocationUpdate" } } }, "description": "Fields to change", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.UpdateGoogleLocationResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Unknown account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "422": { "description": "No updatable field set, or a value Google rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "429": { "description": "Google's 10 edits per minute per profile exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "Upstream Google API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/google/accounts/{id}/insights": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns daily time series for a location: how many people saw it on Google Search and Maps, and how many then called, asked for directions, messaged, booked, ordered, or clicked through to the website. start_date and end_date are inclusive and formatted YYYY-MM-DD. metric takes a comma-separated list and defaults to every metric. A day with no activity comes back as a zero rather than a gap. Google publishes no retention window and no freshness lag for this data, so a recent day may still be filling in and an old range may return nothing.", "tags": [ "Google" ], "summary": "Get Google Business Profile performance metrics", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Inclusive start date, YYYY-MM-DD", "name": "start_date", "in": "query", "required": true, "schema": { "type": "string" } }, { "description": "Inclusive end date, YYYY-MM-DD", "name": "end_date", "in": "query", "required": true, "schema": { "type": "string" } }, { "description": "Comma-separated metric names, defaults to all", "name": "metric", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.GoogleInsightsResponse" } } } }, "400": { "description": "Missing or invalid parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Unknown account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "Upstream Google API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/google/accounts/{id}/media": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Lists the photos and videos on a location's public profile: its logo, cover, interior shots, and so on. This is profile media, not the media attached to a post. Set contributed=true to read the separate, read-only gallery of photos customers submitted; those items carry an attribution block that Google requires you to display as provided, unaltered.", "tags": [ "Google" ], "summary": "List a Google Business Profile location's media", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Read the customer-contributed gallery instead of your own media", "name": "contributed", "in": "query", "schema": { "type": "boolean" } }, { "description": "Items per page", "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "description": "Pagination cursor from a previous response", "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.GoogleMediaListResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Unknown account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Attaches one photo or video to a location's public profile under the given category. media takes exactly one item in the same form the publishing endpoints accept: a stored media library id (source_type media_id), a public URL (url), or a reference to bytes you uploaded to Google yourself (platform_attachment_id). The photo or video format is derived from the item you supply, so you never set Google's own upload fields. Google limits a location to 10 edits per minute, and that limit cannot be raised.", "tags": [ "Google" ], "summary": "Add media to a Google Business Profile location", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.CreateGoogleMediaRequest" } } }, "description": "Media item and category", "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.GoogleMediaItem" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Unknown account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "422": { "description": "Invalid media source or category", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/google/accounts/{id}/media/{mediaId}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns one photo or video from a location's profile. mediaId accepts either the bare id or the full Google resource name returned by the list endpoint.", "tags": [ "Google" ], "summary": "Get one Google Business Profile media item", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Media item ID", "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.GoogleMediaItem" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Unknown account or media item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Deletes one photo or video you added to a location's profile. Photos contributed by customers cannot be deleted through the API and return a permission error; use the takedown_url on the item instead.", "tags": [ "Google" ], "summary": "Remove media from a Google Business Profile location", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Media item ID", "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "Customer-contributed media cannot be deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Unknown account or media item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/google/accounts/{id}/search-keywords": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the keywords people searched before seeing the location, aggregated by month over an inclusive YYYY-MM range. A low-volume keyword comes back with threshold and is_threshold=true instead of value: Google withholds the exact count and gives an upper bound, so treating a threshold as a count overstates the keyword. limit is capped at 100 by Google.", "tags": [ "Google" ], "summary": "Get the search keywords that surfaced a Google Business Profile", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Inclusive start month, YYYY-MM", "name": "start_month", "in": "query", "required": true, "schema": { "type": "string" } }, { "description": "Inclusive end month, YYYY-MM", "name": "end_month", "in": "query", "required": true, "schema": { "type": "string" } }, { "description": "Keywords per page, maximum 100", "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "description": "Pagination cursor from a previous response", "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.GoogleSearchKeywordsResponse" } } } }, "400": { "description": "Missing or invalid parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Unknown account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "Upstream Google API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/google/logins/{loginId}/locations": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Lists every Business Profile location this login can manage, live from Google, merged with assignment state. Locations added in Google Business Profile after the last authorization appear here without re-authenticating. assignable reflects ownership only. login_email identifies the Google account itself, and may be empty on older connections.", "tags": [ "Google" ], "summary": "List a Google login's Business Profile locations", "parameters": [ { "description": "Google login (credential) ID", "name": "loginId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.GoogleLoginLocationsResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Unknown login", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/google/logins/{loginId}/locations/{locationId}/assign": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Assigns one location from this login to the given brand, without re-doing OAuth. Each location belongs to exactly one brand, and each brand holds at most one Google Business Profile.", "tags": [ "Google" ], "summary": "Assign a Google Business Profile location to a brand", "parameters": [ { "description": "Google login (credential) ID", "name": "loginId", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Location resource name (URL-encoded), e.g. accounts%2F123%2Flocations%2F456", "name": "locationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.AssignLocationRequest" } } }, "description": "Target brand", "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.AssignLocationResponse" } } } }, "400": { "description": "Location is not accessible through this login, or already belongs to another brand", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Unknown login or brand", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "409": { "description": "Brand already has a Google Business Profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/instagram/accounts/{id}/media/{mediaId}/collab/accept": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Accepts a pending collaboration invite on an Instagram media object, publishing the co-authored post to this account's feed. Call with the invited account, not the publishing account. Invites expire 14 days after they are sent.", "tags": [ "Instagram" ], "summary": "Accept an Instagram collaboration invite", "parameters": [ { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID (the invited account)", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": "17895695668004550", "description": "Instagram media ID carrying the invite", "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invite accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.SuccessResponse" } } } }, "400": { "description": "No pending invite for this account on this media", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account or media not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Platform does not support collaborators", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "Upstream Instagram API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/instagram/accounts/{id}/media/{mediaId}/collab/decline": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Declines a pending collaboration invite on an Instagram media object. The post will not appear on this account's feed. Call with the invited account, not the publishing account.", "tags": [ "Instagram" ], "summary": "Decline an Instagram collaboration invite", "parameters": [ { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID (the invited account)", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": "17895695668004550", "description": "Instagram media ID carrying the invite", "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invite declined", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.SuccessResponse" } } } }, "400": { "description": "No pending invite for this account on this media", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account or media not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Platform does not support collaborators", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "Upstream Instagram API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/instagram/accounts/{id}/media/{mediaId}/collaborators": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the collaborators invited on a co-authored Instagram post and the state of each invite (accepted, pending, declined). Readable only by the account that published the media: Meta scopes co-authored media data to the publisher, so a collaborating account cannot read this edge. Collaborators can only be invited when the post is created (platform_data.collaborators); Instagram exposes no API to add one to an already-published post.", "tags": [ "Instagram" ], "summary": "List collaborators on an Instagram post", "parameters": [ { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID (must be the publishing account)", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": "17895695668004550", "description": "Instagram media ID", "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Collaborators and invite status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.InstagramCollaboratorsResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account or media not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Platform does not support collaborators", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "Upstream Instagram API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/instagram/accounts/{id}/participants/{participantId}/profile": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the profile Instagram exposes for a messaging participant, including the follow relationship in both directions (is_user_follow_business, is_business_follow_user). Works for an Instagram account connected either directly or through a linked Facebook Page. The follow relationship is current as of the call; do not cache it, since it changes the moment someone unfollows. Instagram only returns this data for users who have consented by messaging your account or tapping an icebreaker or the persistent menu; for anyone else this returns 403 platform.instagram.230, which means Instagram will not disclose the relationship and is NOT the same as \"does not follow\". Branch on that error rather than treating it as a negative. Fields name and profile_pic are absent for users who have set neither; the follow fields are still returned. profile_pic URLs expire after a few days, so do not store them.", "tags": [ "Instagram" ], "summary": "Get an Instagram messaging participant's profile", "parameters": [ { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": "2287522528728101", "description": "Instagram-scoped user ID (IGSID) of the participant, as returned in conversation payloads", "name": "participantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Participant profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.InstagramParticipantProfileResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "User consent required (platform.instagram.230), or platform access not permitted for your plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account or participant not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Platform does not support participant profiles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "Upstream Instagram API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/instagram/accounts/{id}/stories": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the currently-active stories for a connected Instagram account. Stories are ephemeral and expire about 24 hours after posting; each item carries is_story and a computed expires_at in metadata. Returns 501 for non-Instagram accounts.", "tags": [ "Instagram" ], "summary": "List active Instagram stories", "parameters": [ { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": 20, "description": "Maximum number of results to return (1-100, default 20)", "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "description": "Pagination cursor returned by the previous response", "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of active stories", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.InstagramStoriesResponse" } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "Platform access not permitted for your plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Platform does not support stories", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/instagram/accounts/{id}/summary": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns live profile counts plus trailing-30-day insight totals (reach, views, interactions, engaged accounts, net follower change) for a connected Instagram account. The totals need the analytics.read permission. An account without it returns 403 account.permission_missing: add analytics.read to the account's permissions or reconnect the account. If Instagram itself has withdrawn the insights access, the next call can return 403 platform.instagram.insights_scope_missing instead: reconnect the account.", "tags": [ "Instagram" ], "summary": "Get Instagram account insights summary", "parameters": [ { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account insights summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.InstagramAccountSummaryResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "Account does not have the analytics.read permission (account.permission_missing), or Instagram withdrew the insights access (platform.instagram.insights_scope_missing); add the permission or reconnect the account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "Upstream Instagram API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/linkedin/insights": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the follower count plus per-post performance for a connected LinkedIn account. For a company Page, `posts` covers the Page's recent posts. For a personal profile, `posts` covers the 5 most recent posts published to it through SocialAPI, and `clicks` and `engagement_rate` are always 0. `kind` is `organization` for a Page and `member` for a profile.", "tags": [ "LinkedIn" ], "summary": "Get LinkedIn insights", "parameters": [ { "description": "Connected account ID", "name": "account_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.LinkedInInsightsResponse" } } } }, "400": { "description": "Missing account_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "Upstream LinkedIn API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/linkedin/logins/{loginId}/profiles": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Lists the member profile and every company Page a LinkedIn login can connect, with assignment state. A Page the member started administering after the last authorization appears without re-authenticating. A login authorized with connection_type profile lists the member only, and one authorized with connection_type organization lists its Pages only. loginId is the login_id of any LinkedIn account connected through that login.", "tags": [ "LinkedIn" ], "summary": "List the profile and Pages of a LinkedIn login", "parameters": [ { "description": "LinkedIn login ID", "name": "loginId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.LinkedInLoginProfilesResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Unknown login", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/linkedin/logins/{loginId}/profiles/{profileId}/assign": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Connects the member profile or one company Page of a LinkedIn login to the given brand, without re-doing OAuth. Each LinkedIn account belongs to one brand. A brand can hold several LinkedIn accounts.", "tags": [ "LinkedIn" ], "summary": "Connect a LinkedIn profile or Page from a login", "parameters": [ { "description": "LinkedIn login ID", "name": "loginId", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "platform_account_id from the profiles list, URL-encoded (urn%3Ali%3Aorganization%3A123456)", "name": "profileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.AssignLinkedInProfileRequest" } } }, "description": "Target brand", "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.AssignLocationResponse" } } } }, "400": { "description": "Account is not accessible through this login, or already belongs to another brand", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Unknown login or brand", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/pinterest/accounts/{id}/pins": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the connected Pinterest account's pins.", "tags": [ "Accounts" ], "summary": "List Pinterest pins", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Maximum pins to return (default 50, max 50)", "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.PinterestPinsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/pinterest/accounts/{id}/summary": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the connected Pinterest account's public profile counts: followers, pins, boards, and monthly views.", "tags": [ "Accounts" ], "summary": "Get Pinterest account summary", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.PinterestSummaryResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/threads/insights": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns engagement metrics for a single Threads post (level=media) or for the connected account (level=account). An account connected before 2026-10-17 returns 403 platform.threads.insights_scope_missing until it is reconnected. Media metrics are views, likes, replies, reposts, quotes and shares. Account metrics are those five plus clicks, followers_count and follower_demographics. shares is media-only and clicks is account-only. follower_demographics requires exactly one breakdown (country, city, age or gender) and rejects since or until.", "tags": [ "Threads" ], "summary": "Get Threads insights", "parameters": [ { "description": "Connected account ID", "name": "account_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "description": "media or account", "name": "level", "in": "query", "required": true, "schema": { "type": "string" } }, { "description": "Platform post ID, required when level is media", "name": "post_id", "in": "query", "schema": { "type": "string" } }, { "description": "Comma-separated metric names, defaults to all metrics valid for the level", "name": "metric", "in": "query", "schema": { "type": "string" } }, { "description": "One of country, city, age, gender; only valid with follower_demographics", "name": "breakdown", "in": "query", "schema": { "type": "string" } }, { "description": "Unix timestamp lower bound, must be >= 1712991600", "name": "since", "in": "query", "schema": { "type": "integer" } }, { "description": "Unix timestamp upper bound, must be >= 1712991600", "name": "until", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ThreadsInsightsResponse" } } } }, "400": { "description": "Missing or invalid parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "The account was connected without the insights permission (platform.threads.insights_scope_missing); reconnect the account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "Upstream Threads API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/threads/profile-lookup": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Beta. Resolves a public Threads profile by exact username and returns its public metrics. Requires the threads_profile_discovery Threads permission, which is pending Meta App Review, so calls may return an upstream authorization error for accounts outside the app's tester roster until that permission is granted. Matching is exact, with no fuzzy or prefix search. Only profiles with 100 or more followers are discoverable, anything else returns 404. The upstream budget is 1000 lookups per user per rolling 24 hours.", "tags": [ "Threads" ], "summary": "Look up a public Threads profile (beta)", "parameters": [ { "description": "Connected account ID whose token authorizes the lookup", "name": "account_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "description": "Exact Threads username, with or without a leading @", "name": "username", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ThreadsProfileResponse" } } } }, "400": { "description": "Missing account_id or username", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Profile not discoverable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "429": { "description": "Lookup budget exhausted for this user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "Upstream Threads API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/tiktok/accounts/{id}/summary": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "TikTok" ], "summary": "Get TikTok account summary", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.TikTokAccountSummaryResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "Upstream TikTok API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/tiktok/accounts/{id}/sync": { "post": { "security": [ { "BearerAuth": [] } ], "tags": [ "TikTok" ], "summary": "Re-sync a TikTok account's videos", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "boolean" } } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Account is not a TikTok account or connector does not support post sync", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "Upstream TikTok API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/whatsapp/accounts/{id}/send-template": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Sends an approved WhatsApp template message to a recipient phone number. Template messages can be sent outside the 24-hour customer service window. The template must already be APPROVED on the WABA, and the language code must match an approved variant. Component parameter order must match the template's placeholders. The response includes message_id, the SocialAPI message ID for the send, which matches the id field on the dm.status.* webhooks for this message.", "tags": [ "WhatsApp" ], "summary": "Send a template message", "parameters": [ { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID (sapi_acc_...)", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.WhatsAppSendTemplateRequest" } } }, "description": "Recipient, template name, language, and components", "required": true }, "responses": { "200": { "description": "Message accepted by WhatsApp", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.WhatsAppSendTemplateResponse" } } } }, "400": { "description": "Missing required field (to, template_name, language)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "whatsapp.paid_plan_required: template sends need a paid plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found or not owned by caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "429": { "description": "Monthly interaction limit exceeded or platform rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "WhatsApp/Meta upstream error (template not approved, invalid parameters)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/whatsapp/accounts/{id}/templates": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns all message templates configured on the WhatsApp Business Account (WABA) associated with this connected account. Templates include approved, pending, rejected, and paused entries. Use the after cursor from paging.cursors to fetch subsequent pages.", "tags": [ "WhatsApp" ], "summary": "List message templates", "parameters": [ { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID (sapi_acc_...)", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": 25, "description": "Maximum number of templates to return (1-100)", "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "description": "Pagination cursor (after) from a previous response", "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Templates with pagination cursors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.WhatsAppTemplateListResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found or not owned by caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "WhatsApp/Meta upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Submits a new message template to the WhatsApp Business Account (WABA) for review. The request body is the raw WhatsApp Cloud API template payload (name, category, language, components). New templates start in PENDING status; Meta reviews them and the status transitions to APPROVED or REJECTED asynchronously.", "tags": [ "WhatsApp" ], "summary": "Create a message template", "parameters": [ { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID (sapi_acc_...)", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.WhatsAppCreateTemplateRequest" } } }, "description": "Template definition", "required": true }, "responses": { "201": { "description": "Created template (initial status)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.WhatsAppTemplateCreateResponse" } } } }, "400": { "description": "Missing or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found or not owned by caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "409": { "description": "Template name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "WhatsApp/Meta upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Deletes a template by name from the WhatsApp Business Account (WABA) associated with this connected account. WhatsApp deletes all language variants that share the given name. Templates cannot be deleted while they are being used in active campaigns.", "tags": [ "WhatsApp" ], "summary": "Delete a message template", "parameters": [ { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID (sapi_acc_...)", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": "order_confirmation", "description": "Template name to delete", "name": "name", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Template deleted" }, "400": { "description": "Missing name query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found or template does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "WhatsApp/Meta upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/whatsapp/phone-numbers/{id}/business-profile": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the public business profile for a WhatsApp phone number, including about text, address, description, contact email, websites, and vertical. The profile is visible to customers in the WhatsApp chat header.", "tags": [ "WhatsApp" ], "summary": "Get a WhatsApp Business Profile", "parameters": [ { "example": "106540352242922", "description": "WhatsApp phone number platform ID (numeric ID, not the E.164 number)", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Business profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.WhatsAppBusinessProfile" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Phone number not owned by caller or not connected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "WhatsApp/Meta upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Updates one or more fields of the public business profile (about, address, description, email, websites, vertical, profile_picture_handle). Only provided fields are changed. The profile picture itself is changed by passing a profile_picture_handle obtained from the Resumable Upload API; profile_picture_url is read-only.", "tags": [ "WhatsApp" ], "summary": "Update a WhatsApp Business Profile", "parameters": [ { "example": "106540352242922", "description": "WhatsApp phone number platform ID (numeric ID, not the E.164 number)", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.WhatsAppUpdateBusinessProfileRequest" } } }, "description": "Profile fields to update", "required": true }, "responses": { "204": { "description": "Profile updated" }, "400": { "description": "Empty or invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Phone number not owned by caller or not connected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "WhatsApp/Meta upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/whatsapp/phone-numbers/{id}/deregister": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Releases the phone number from WhatsApp Business, freeing it for use with another Business Solution Provider (BSP). This does not delete the connected account on SocialAPI; the account remains until it is disconnected explicitly.", "tags": [ "WhatsApp" ], "summary": "Deregister a phone number from WhatsApp Business", "parameters": [ { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID (sapi_acc_...)", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Phone number deregistered" }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found or not owned by caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "WhatsApp/Meta upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/whatsapp/phone-numbers/{id}/register": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Registers a previously verified phone number with WhatsApp Business and sets the 6-digit two-step verification PIN. The phone number must be verified via verify-code first. The PIN must be retained by the caller: losing it triggers a mandatory 7-day wait before it can be reset. A number that stays on the WhatsApp Business app is already registered and is refused with 409 whatsapp.business_app_number.", "tags": [ "WhatsApp" ], "summary": "Register a phone number with WhatsApp Business", "parameters": [ { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID (sapi_acc_...)", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.WhatsAppRegisterRequest" } } }, "description": "6-digit two-step verification PIN", "required": true }, "responses": { "204": { "description": "Phone number registered" }, "400": { "description": "Missing or invalid PIN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found or not owned by caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "409": { "description": "Phone number not verified, already registered with another BSP, or in use in the WhatsApp Business app", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "WhatsApp/Meta upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/whatsapp/phone-numbers/{id}/request-code": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Asks WhatsApp to send a one-time verification code to the phone number via SMS or voice call. The code is delivered to the underlying phone line, not to the API caller; follow up with verify-code once the user receives it. Step 1 of the phone-number registration flow (request-code, verify-code, register).", "tags": [ "WhatsApp" ], "summary": "Request a phone number verification code", "parameters": [ { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID (sapi_acc_...)", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.WhatsAppRequestCodeRequest" } } }, "description": "Verification channel and locale", "required": true }, "responses": { "204": { "description": "Code dispatched" }, "400": { "description": "Missing or invalid method/language", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found or not owned by caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "WhatsApp/Meta upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/whatsapp/phone-numbers/{id}/status": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns whether a phone number is verified and registered with WhatsApp Business. Used by client UIs to decide which step of the registration flow to show.", "tags": [ "WhatsApp" ], "summary": "Get phone number registration status", "parameters": [ { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID (sapi_acc_...)", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verification + registration flags", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_whatsapp.PhoneNumberStatusResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found or not owned by caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "WhatsApp/Meta upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/whatsapp/phone-numbers/{id}/verify-code": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Submits the 6-digit code received via SMS or voice to prove ownership of the phone number. Once verified, the phone number can be registered with WhatsApp Business. Codes expire quickly; if verification fails, request a new code.", "tags": [ "WhatsApp" ], "summary": "Verify a phone number with a code", "parameters": [ { "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "description": "Connected account ID (sapi_acc_...)", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.WhatsAppVerifyCodeRequest" } } }, "description": "Verification code", "required": true }, "responses": { "204": { "description": "Phone number verified" }, "400": { "description": "Missing or invalid code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found or not owned by caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "WhatsApp/Meta upstream error (code mismatch or expired)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/whatsapp/templates/validate": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Dry-run validation of a WhatsApp message template against the Cloud API rules (name format, component cardinality, header format, text limits, placeholder sequencing, button constraints). Returns errors for hard violations that WhatsApp would reject and warnings for best-practice issues. Performs no network call and does not submit the template.", "tags": [ "WhatsApp" ], "summary": "Validate a message template", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.WhatsAppCreateTemplateRequest" } } }, "description": "Template definition to validate", "required": true }, "responses": { "200": { "description": "Validation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.WhatsAppValidateTemplateResponse" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/whatsapp/templates/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns a single message template by its WhatsApp template ID. Requires an active WhatsApp account on your workspace. The template is identified by its WhatsApp template ID.", "tags": [ "WhatsApp" ], "summary": "Get a message template", "parameters": [ { "example": "1234567890123456", "description": "WhatsApp template platform ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Template details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.WhatsAppTemplateInfo" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Template not found or no WhatsApp account connected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "WhatsApp/Meta upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Updates the components of an existing message template by its WhatsApp template ID. Only APPROVED templates can be edited, and editing resets the template to PENDING for re-review. APPROVED templates are limited to one edit per day.", "tags": [ "WhatsApp" ], "summary": "Edit a message template", "parameters": [ { "example": "1234567890123456", "description": "WhatsApp template platform ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.WhatsAppEditTemplateRequest" } } }, "description": "Replacement components", "required": true }, "responses": { "204": { "description": "Template updated" }, "400": { "description": "Missing or invalid components", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Template not found or no WhatsApp account connected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "WhatsApp/Meta upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/youtube/accounts/{id}/summary": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "YouTube" ], "summary": "Get YouTube channel summary", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.YouTubeChannelSummaryResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "Upstream YouTube API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/youtube/accounts/{id}/sync": { "post": { "security": [ { "BearerAuth": [] } ], "tags": [ "YouTube" ], "summary": "Re-sync a YouTube account's videos", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "boolean" } } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Account is not a YouTube account or connector does not support post sync", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "502": { "description": "Upstream YouTube API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/youtube/accounts/{id}/videos/{videoId}": { "patch": { "tags": [ "YouTube" ], "summary": "Edit a published YouTube video (title, description, visibility, Studio tags)", "parameters": [ { "description": "Connected account ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "YouTube video ID", "name": "videoId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.UpdateYouTubeVideoRequest" } } }, "description": "Editable fields (all fields optional; omit any to leave unchanged)" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "boolean" } } } } } } } }, "/platforms/youtube/comments/{commentId}": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Edits the text of one of the connected account's own YouTube comments via comments.update. Only the comment author (the connected account) can edit. YouTube only.", "tags": [ "YouTube" ], "summary": "Edit a YouTube comment", "parameters": [ { "description": "YouTube comment ID", "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.EditYouTubeCommentRequest" } } }, "description": "New comment text (account_id, post_id, and text are all required to resolve the channel and edit the comment)", "required": true }, "responses": { "200": { "description": "Comment edited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.SuccessResponse" } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "The key's scopes do not include inbox:write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Account is not a YouTube account, or the connector does not support editing comments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/platforms/youtube/comments/{commentId}/moderate": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Sets the moderation status of a YouTube comment (published, held_for_review, or rejected), optionally banning the author. ban_author is only valid with status=rejected. YouTube only.", "tags": [ "YouTube" ], "summary": "Moderate a YouTube comment", "parameters": [ { "description": "YouTube comment ID", "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ModerateYouTubeCommentRequest" } } }, "description": "Moderation action (account_id and post_id are both required to resolve the channel that owns the comment)", "required": true }, "responses": { "200": { "description": "Comment moderated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.SuccessResponse" } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "The key's scopes do not include inbox:write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "Account is not a YouTube account, or the connector does not support comment moderation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/posts": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns posts with rich filtering and cursor pagination. Supports filtering by status, platform, account_ids, date range, and text search.", "tags": [ "Posts" ], "summary": "List all posts", "parameters": [ { "description": "Comma-separated connected account IDs", "name": "account_ids", "in": "query", "schema": { "type": "string" } }, { "description": "Filter to posts whose targets belong to this brand", "name": "brand_id", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by status (draft, scheduled, publishing, published, partial, failed, cancelled)", "name": "status", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by platform (e.g. instagram, facebook)", "name": "platform", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by specific page ID (for multi-page accounts like Facebook)", "name": "page_id", "in": "query", "schema": { "type": "string" } }, { "description": "Start of date range (RFC3339)", "name": "from", "in": "query", "schema": { "type": "string" } }, { "description": "End of date range (RFC3339)", "name": "to", "in": "query", "schema": { "type": "string" } }, { "description": "Text search (case-insensitive)", "name": "search", "in": "query", "schema": { "type": "string" } }, { "description": "Sort order: scheduled_asc (default), scheduled_desc, created_asc, created_desc", "name": "sort", "in": "query", "schema": { "type": "string" } }, { "description": "Pagination cursor from previous response", "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "description": "Max results (default 25, max 100)", "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "description": "Include hidden posts (default false)", "name": "hidden", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.PostsListResponse" } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates a post for one or more connected accounts. Set `publish_now: true` to publish\nimmediately: the post is accepted with status `publishing` and delivery runs in the\nbackground (so slow reel/video uploads do not block the request). The terminal status\n(`published`, `partial`, or `failed`) arrives via the `post.published`/`post.partial`/\n`post.failed` webhooks and by polling GET /posts/{pid}. Set `scheduled_at` to queue the\npost for future publication. With neither flag the post is saved as a draft (this is the\ndefault, even when targets are provided); publish it later with POST /posts/{pid}/publish.\nSet `stagger` to publish the targets one after another, separated by a random delay between\n`min_seconds` and `max_seconds`, instead of all at once; the post is then returned with status `scheduled`.\nSet `queue_id` instead of `scheduled_at` to schedule the post at the earliest free time of a Queue; the time is in `scheduled_at` on the response.\nConsumes 1 post credit when the post is published or scheduled; saving a draft is free.", "tags": [ "Posts" ], "summary": "Create or schedule a post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.CreatePostRequest" } } }, "description": "Post content and target accounts", "required": true }, "responses": { "201": { "description": "Post accepted (publishing in background), scheduled, or drafted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.PostResponse" } } } }, "207": { "description": "Some accounts published, some failed (fast completion)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.PostResponse" } } } }, "400": { "description": "Invalid body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "A target account must be reconnected before it can publish now (account.reconnection_required; the error names the account). Scheduled posts and drafts are still accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "queue_id names a Queue that does not exist, or the Brand has no default Queue (queue.not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "409": { "description": "The Queue is paused or has no free time within 366 days (queue.paused, queue.full)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "422": { "description": "A target account's platform does not support publishing posts, such as Telegram or WhatsApp (account.platform_unsupported), or publishing.delivery.all_failed (fast completion)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.PostResponse" } } } }, "429": { "description": "Monthly post limit exceeded, or the target account is over its posting velocity cap (publishing.velocity_limit; see the Retry-After header)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/posts/import": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Upload a CSV file to create multiple posts. Use dry_run=true to validate without creating. Columns, in order: text, title, account_ids, scheduled_at, visibility, first_comment, platform_data, board_id. Only text is required. account_ids is pipe separated.", "tags": [ "Posts" ], "summary": "Bulk import posts from CSV", "parameters": [ { "description": "Validate only, do not create", "name": "dry_run", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "description": "CSV file (max 5 MB)", "type": "string", "format": "binary" } }, "required": [ "file" ] } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ImportPostsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/posts/validate": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns media and text constraints for all supported platforms. Cacheable.", "tags": [ "Posts" ], "summary": "Get platform constraints", "parameters": [ { "description": "Filter to a single platform", "name": "platform", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.PlatformConstraintsResponse" } } } }, "400": { "description": "Unknown platform", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Dry-run validation. Returns errors for hard limit violations and warnings for best-practice issues.", "tags": [ "Posts" ], "summary": "Validate post content", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ValidatePostRequest" } } }, "description": "Content to validate", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ValidatePostResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/posts/{pid}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Fetch a post with all platform delivery details. Accepts the SocialAPI post ID or a platform post ID (the platform's native ID for a published target).", "tags": [ "Posts" ], "summary": "Get a single post", "parameters": [ { "description": "SocialAPI post ID (UUID) or platform post ID", "name": "pid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.PostResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "409": { "description": "Platform post ID matches multiple posts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Deletes a draft/scheduled/failed post locally, or deletes a published post from every platform that supports it. Platforms that do not support deletion (or fail) keep their copy live and the post is kept rather than removed. Returns a per-platform result.", "tags": [ "Posts" ], "summary": "Delete or cancel a post", "parameters": [ { "description": "Post ID", "name": "pid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delete result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.DeletePostResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Post not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "description": "Updates the text, media, schedule time, targets, or hidden status of a pending post.\nOnly posts in `draft`, `scheduled`, or `failed` status can be updated.\n`queue_id` moves the post to another Queue, and `queue_id: null` takes it out of its Queue and keeps its time.\nOmit `targets` to keep the current ones. Sending `targets` replaces them all.\n`scheduled_at` must be in the future, and a scheduled post must keep at least one target.", "tags": [ "Posts" ], "summary": "Update a post", "parameters": [ { "description": "Post ID", "name": "pid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.UpdatePostRequest" } } }, "description": "Updated content", "required": true }, "responses": { "200": { "description": "Post updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.PostResponse" } } } }, "400": { "description": "Invalid body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Post not found, or queue_id names a Queue that does not exist (queue.not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "409": { "description": "Post is not in an editable state, or the Queue is paused, has no free time, or already holds a post at the requested time (queue.paused, queue.full, queue.slot_conflict)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "422": { "description": "A target account's platform does not support publishing posts, such as Telegram or WhatsApp (account.platform_unsupported)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/posts/{pid}/analytics": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns daily history for a published post: how its engagement counters accrued, one point per day. This is the history route. For the post's current figures, use GET /v1/posts/{pid}/metrics instead.\nHistory does not extend back before the post was first tracked, so an older post may have no earlier points.", "tags": [ "Analytics" ], "summary": "Get post analytics history", "parameters": [ { "description": "SocialAPI post ID (UUID)", "name": "pid", "in": "path", "required": true, "schema": { "type": "string" } }, { "example": "2026-08-23", "description": "First day, YYYY-MM-DD. Defaults to 29 days before to.", "name": "from", "in": "query", "schema": { "type": "string" } }, { "example": "2026-09-21", "description": "Last day, YYYY-MM-DD. Defaults to today (UTC).", "name": "to", "in": "query", "schema": { "type": "string" } }, { "description": "Comma-separated metric names. Defaults to every stored metric.", "name": "metrics", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.AnalyticsResponseWrapper" } } } }, "400": { "description": "Malformed or inverted range, or a range wider than 400 days", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Post not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/posts/{pid}/metrics": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Fetches engagement metrics from platform APIs for a published post. Accepts the SocialAPI post ID or a platform post ID.\nInstagram targets add views, reach and interactions, plus follows, profile visits and profile actions on feed posts, and watch time, skip rate and crossposted views on Reels. A metric the platform does not report for a post is omitted. If an Instagram target returns none of them, reconnect the account to grant the insights permission.", "tags": [ "Posts" ], "summary": "Get post metrics", "parameters": [ { "description": "SocialAPI post ID (UUID) or platform post ID", "name": "pid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.MetricsResponseWrapper" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Post not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "409": { "description": "Platform post ID matches multiple posts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/posts/{pid}/publish": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Publishes a post in `draft` or `scheduled` status immediately. The post is accepted\nwith status `publishing` and delivery runs in the background (so slow reel/video uploads\ndo not block the request); the terminal status arrives via the `post.published`/\n`post.partial`/`post.failed` webhooks and by polling GET /posts/{pid}. Use this to publish\na post that was saved as a draft, or to publish a scheduled post ahead of its time.\nA post in a Queue publishes now and leaves the Queue.\nConsumes 1 post credit.", "tags": [ "Posts" ], "summary": "Publish a draft post now", "parameters": [ { "description": "Post ID", "name": "pid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Post accepted, publishing in the background", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.PostResponse" } } } }, "207": { "description": "Some accounts published, some failed (fast completion)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.PostResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "A target account must be reconnected before it can publish (account.reconnection_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Post not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "409": { "description": "Post is not in a publishable state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "422": { "description": "publishing.delivery.all_failed (fast completion)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.PostResponse" } } } }, "429": { "description": "Monthly post limit exceeded, or the target account is over its posting velocity cap (publishing.velocity_limit; see the Retry-After header)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/posts/{pid}/retry": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Re-attempts publication of a post in `failed` or `partial` status. Consumes 1 post credit.", "tags": [ "Posts" ], "summary": "Retry a failed post", "parameters": [ { "description": "Post ID", "name": "pid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Post re-enqueued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.SuccessResponse" } } } }, "400": { "description": "Post is not retryable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "A target account must be reconnected before it can publish (account.reconnection_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Post not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "409": { "description": "Post is not in a retryable state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "429": { "description": "Monthly post limit exceeded, or the target account is over its posting velocity cap (publishing.velocity_limit; see the Retry-After header)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/posts/{pid}/unpublish": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Unpublishes a published post from a specific account (if account_id provided) or all accounts.", "tags": [ "Posts" ], "summary": "Unpublish a post", "parameters": [ { "description": "Post ID", "name": "pid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.UnpublishRequest" } } }, "description": "Optional account_id to unpublish from" }, "responses": { "200": { "description": "Post unpublished", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.SuccessResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Post not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "501": { "description": "resource.not_supported: a target platform cannot unpublish (content stays live)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/queues": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Lists your Queues, grouped by Brand, oldest first. Filter to one Brand with brand_id.", "tags": [ "Queues" ], "summary": "List Queues", "parameters": [ { "description": "Brand ID", "name": "brand_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.QueueListResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "The key's scopes do not include posts:read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates a Queue on a Brand: a weekly list of posting times in one timezone. A post created with queue_id takes the earliest free time. day is a lowercase English weekday name and time is HH:MM, both in the Queue's timezone. A Brand holds at most 20 Queues and always has exactly one default. The first Queue of a Brand becomes its default, and is_default: true makes this one the default.", "tags": [ "Queues" ], "summary": "Create a Queue", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/social-api_ai_core_api_service.CreateQueueParams" } } }, "description": "Queue definition", "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/social-api_ai_core_api_service.Queue" } } } }, "400": { "description": "Missing brand_id, invalid timezone, slots or name (validation.field_required, validation.field_invalid)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "The key's scopes do not include posts:write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Brand not found (brand.not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "409": { "description": "The Brand already has 20 Queues (queue.limit_reached)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/queues/{qid}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns one Queue.", "tags": [ "Queues" ], "summary": "Get a Queue", "parameters": [ { "example": "que_01J9Z8Y7X6W5V4T3S2R1Q0P9N8", "description": "Queue ID", "name": "qid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/social-api_ai_core_api_service.Queue" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "The key's scopes do not include posts:read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Queue not found (queue.not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Deletes a Queue. Its posts keep their scheduled times and are no longer queued; released_count is how many there were. If it was the default, the Brand's oldest remaining Queue becomes the default.", "tags": [ "Queues" ], "summary": "Delete a Queue", "parameters": [ { "example": "que_01J9Z8Y7X6W5V4T3S2R1Q0P9N8", "description": "Queue ID", "name": "qid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.DeleteQueueResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "The key's scopes do not include posts:write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Queue not found (queue.not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "description": "Updates the fields you send and keeps the rest. slots replaces the whole list. Set active to false to pause the Queue: posts already in it keep their times, and no new post can join it. is_default can only be set to true, which makes this Queue the Brand's default; to change the default, set another Queue's is_default to true. Posts already queued keep their times unless you send reshuffle_existing: true, which moves them onto the new slots in their current order and returns reshuffled_count.", "tags": [ "Queues" ], "summary": "Update a Queue", "parameters": [ { "example": "que_01J9Z8Y7X6W5V4T3S2R1Q0P9N8", "description": "Queue ID", "name": "qid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/social-api_ai_core_api_service.UpdateQueueParams" } } }, "description": "Fields to change", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.UpdateQueueResponse" } } } }, "400": { "description": "Invalid timezone, slots, name or is_default (validation.field_invalid)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "The key's scopes do not include posts:write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Queue not found (queue.not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "409": { "description": "reshuffle_existing found no free time for a post within 366 days (queue.full)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/queues/{qid}/preview": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Lists the next free times of a Queue as RFC 3339 with the Queue's local offset, soonest first. Works on a paused Queue. A forecast, not a reservation: send queue_id, never copy a previewed time into scheduled_at.", "tags": [ "Queues" ], "summary": "Preview a Queue's next times", "parameters": [ { "example": "que_01J9Z8Y7X6W5V4T3S2R1Q0P9N8", "description": "Queue ID", "name": "qid", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Number of times, 1 to 100, default 10", "name": "count", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.QueuePreviewResponse" } } } }, "400": { "description": "count is not an integer from 1 to 100 (validation.field_invalid)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "403": { "description": "The key's scopes do not include posts:read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Queue not found (queue.not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/usage": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns brands, posts, and interactions consumed during the current billing period alongside the plan limits. -1 means unlimited (all paid plans). Period boundaries follow your subscription cycle, or a rolling 30-day window on the free plan.", "tags": [ "Usage" ], "summary": "Get resource usage for the current billing period", "responses": { "200": { "description": "Resource usage for the current billing period", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.UsageResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/users/me": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the authenticated user's profile (id, email, plan tier, onboarding flag, beta_tester flag, allowed_platforms list, billing_blocked state).", "tags": [ "Users" ], "summary": "Get current user", "responses": { "200": { "description": "User profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.UserMeResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Permanently deletes the authenticated user account and all associated data (API keys, connected accounts, usage logs). Any active subscription is cancelled immediately, with no refund for the remainder of the current billing period. This action is irreversible.", "tags": [ "Users" ], "summary": "Delete user account", "responses": { "200": { "description": "User deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.OKResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "description": "Updates the authenticated user's profile. Supports setting onboarding=false to mark onboarding as complete, and optionally recording use_case, referral, job_role and signup_metadata. The response reflects the current billing_blocked state, unaffected by this update. The response includes the caller's team role: \"admin\", \"developer\", or \"\" for the account owner.", "tags": [ "Users" ], "summary": "Update current user", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.PatchMeRequest" } } }, "description": "Fields to update", "required": true }, "responses": { "200": { "description": "Updated user profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.UserMeResponse" } } } }, "400": { "description": "Invalid request body or onboarding value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/webhooks": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns all webhook endpoints for the authenticated user.", "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "responses": { "200": { "description": "List of webhook endpoints", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.WebhooksListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Registers a new webhook endpoint and performs a live reachability ping. If the endpoint is unreachable or returns an unexpected response, the request fails with 400 (webhook_verification_failed). The generated secret is returned once - store it securely.", "tags": [ "Webhooks" ], "summary": "Create webhook endpoint", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.CreateWebhookRequest" } } }, "description": "Endpoint config", "required": true }, "responses": { "201": { "description": "Endpoint created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.CreateWebhookResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/webhooks/events": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the catalog of webhook event types you can subscribe to, grouped by category (posts, inbox, accounts).", "tags": [ "Webhooks" ], "summary": "List available webhook event types", "responses": { "200": { "description": "Catalog of webhook event types", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ListWebhookEventsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/webhooks/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the configuration and aggregate delivery stats for a single webhook endpoint owned by the caller.", "tags": [ "Webhooks" ], "summary": "Get webhook endpoint", "parameters": [ { "description": "Webhook endpoint ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.WebhookDetailResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Removes a webhook endpoint. Future events will not be delivered to this URL.", "tags": [ "Webhooks" ], "summary": "Delete webhook endpoint", "parameters": [ { "description": "Webhook endpoint ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.OKResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "description": "Partially updates a webhook endpoint. All fields are optional; at least one must be provided.", "tags": [ "Webhooks" ], "summary": "Update webhook endpoint", "parameters": [ { "description": "Webhook endpoint ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.UpdateWebhookRequest" } } }, "description": "Fields to update", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.WebhookEndpointItem" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/webhooks/{id}/deliveries": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns recent delivery attempts for a webhook endpoint. Optionally filter by status (success, failed, pending) or event_type. Cursor-paginated.", "tags": [ "Webhooks" ], "summary": "List webhook deliveries", "parameters": [ { "description": "Webhook endpoint ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Filter by delivery status", "name": "status", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by event type", "name": "event_type", "in": "query", "schema": { "type": "string" } }, { "description": "Pagination cursor", "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "description": "Page size (1-100, default 50)", "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.DeliveryListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/webhooks/{id}/deliveries/{did}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the full record of a single webhook delivery attempt, including request payload, response status, response body excerpt, and timing.", "tags": [ "Webhooks" ], "summary": "Get webhook delivery", "parameters": [ { "description": "Webhook endpoint ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Delivery ID", "name": "did", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.DeliveryDetailResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/webhooks/{id}/deliveries/{did}/retry": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Requeues a failed webhook delivery for another attempt. Returns the updated delivery record.", "tags": [ "Webhooks" ], "summary": "Retry webhook delivery", "parameters": [ { "description": "Webhook endpoint ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Delivery ID", "name": "did", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.DeliveryDetailResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } }, "/webhooks/{id}/test": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Sends a synthetic event payload to the webhook endpoint to validate signature, reachability, and consumer handling. Returns the delivery result.", "tags": [ "Webhooks" ], "summary": "Send test webhook delivery", "parameters": [ { "description": "Webhook endpoint ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.TestWebhookRequest" } } }, "description": "Event type and payload to send", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.TestDeliveryResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_endpoints.ErrorResponse" } } } } } } } }, "servers": [ { "url": "https://api.social-api.ai/v1" } ], "components": { "securitySchemes": { "BearerAuth": { "description": "Prefix your API key with \"Bearer \". Example: `Authorization: Bearer sapi_key_...`", "type": "apiKey", "name": "Authorization", "in": "header" } }, "schemas": { "api_endpoints.AccountPageResponse": { "type": "object", "properties": { "about": { "type": "string" }, "category": { "type": "string" }, "cover_photo_url": { "type": "string" }, "enriched_at": { "type": "string" }, "followers_count": { "type": "integer" }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "is_default": { "type": "boolean" }, "link": { "type": "string" }, "name": { "type": "string" }, "platform_page_id": { "type": "string" }, "profile_picture_url": { "type": "string" }, "username": { "type": "string" }, "verification_status": { "type": "string" } } }, "api_endpoints.AccountPostsSyncResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/api_endpoints.AccountPostsSyncStatus" } } }, "api_endpoints.AccountPostsSyncStatus": { "type": "object", "properties": { "error": { "description": "Error says why the last sync failed. Empty unless State is \"failed\".", "type": "string", "example": "" }, "finished_at": { "type": "string" }, "last_synced_at": { "type": "string" }, "started_at": { "type": "string" }, "state": { "description": "State is \"idle\", \"syncing\", or \"failed\". A finished sync is idle with a\nnewer LastSyncedAt.", "type": "string", "enum": [ "idle", "syncing", "failed" ], "example": "syncing" } } }, "api_endpoints.AccountsListResponse": { "type": "object", "properties": { "count": { "type": "integer", "example": 2 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.Account" } } } }, "api_endpoints.AnalyticsOverviewResponseWrapper": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/social-api_ai_core_api_service.AnalyticsOverview" } } }, "api_endpoints.AnalyticsResponseWrapper": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/social-api_ai_core_api_service.AnalyticsResponse" } } }, "api_endpoints.AnnouncementItem": { "type": "object", "properties": { "body": { "type": "string", "example": "We are upgrading our database infrastructure." }, "id": { "type": "string", "example": "9c1e7f2a-3b4d-4e5f-8a9b-0c1d2e3f4a5b" }, "kind": { "type": "string", "example": "maintenance" }, "link_label": { "type": "string", "example": "Status page" }, "link_url": { "type": "string", "example": "https://status.social-api.ai" }, "seen": { "type": "boolean", "example": false }, "title": { "type": "string", "example": "Scheduled maintenance" }, "window_end": { "type": "string", "example": "2026-08-02T04:00:00Z" }, "window_start": { "type": "string", "example": "2026-08-02T02:00:00Z" } } }, "api_endpoints.AnnouncementsListResponse": { "type": "object", "properties": { "count": { "type": "integer", "example": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.AnnouncementItem" } } } }, "api_endpoints.AssignLinkedInProfileRequest": { "type": "object", "properties": { "brand_id": { "type": "string", "example": "b7f9..." } } }, "api_endpoints.AssignLocationRequest": { "type": "object", "properties": { "brand_id": { "type": "string", "example": "b7f9..." } } }, "api_endpoints.AssignLocationResponse": { "type": "object", "properties": { "account_id": { "type": "string", "example": "acc_01J..." }, "brand_id": { "type": "string" }, "platform_account_id": { "type": "string" } } }, "api_endpoints.AssignPageRequest": { "type": "object", "properties": { "brand_id": { "type": "string", "example": "b7f9..." } } }, "api_endpoints.AssignPageResponse": { "type": "object", "properties": { "account_id": { "type": "string", "example": "acc_01J..." }, "brand_id": { "type": "string" }, "platform_page_id": { "type": "string" } } }, "api_endpoints.AutomationListResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.Automation" } } } }, "api_endpoints.BillingPlan": { "type": "object", "properties": { "annual_price_eur": { "type": "integer", "example": 929 }, "annual_price_usd": { "type": "integer", "example": 1044 }, "limits": { "$ref": "#/components/schemas/api_endpoints.BillingPlanLimits" }, "monthly_price_eur": { "type": "integer", "example": 97 }, "monthly_price_usd": { "type": "integer", "example": 109 }, "name": { "type": "string", "example": "Full Send" }, "popular": { "type": "boolean", "example": true }, "tagline": { "type": "string", "example": "For growing teams and products" }, "tier": { "type": "string", "example": "pro" } } }, "api_endpoints.BillingPlanLimits": { "type": "object", "properties": { "event_retention_days": { "type": "integer", "example": 30 }, "exports_per_month": { "type": "integer", "example": 20 }, "interactions_per_month": { "type": "integer", "example": -1 }, "posts_per_month": { "type": "integer", "example": -1 }, "profiles": { "type": "integer", "example": 50 }, "storage_bytes": { "type": "integer", "example": -1 } } }, "api_endpoints.BillingPlansResponse": { "type": "object", "properties": { "plans": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.BillingPlan" } } } }, "api_endpoints.BrandListItem": { "type": "object", "properties": { "accounts_count": { "type": "integer", "example": 3 }, "created_at": { "type": "string", "example": "2026-03-14T09:00:00Z" }, "id": { "type": "string", "example": "b_01HZ9X3Q4R5M6N7P8V2K0W1J" }, "name": { "type": "string", "example": "Acme Corporation" }, "updated_at": { "type": "string", "example": "2026-03-14T09:00:00Z" } } }, "api_endpoints.BrandResponse": { "type": "object", "properties": { "accounts_count": { "type": "integer", "example": 0 }, "created_at": { "type": "string", "example": "2026-03-14T09:00:00Z" }, "id": { "type": "string", "example": "b_01HZ9X3Q4R5M6N7P8V2K0W1J" }, "name": { "type": "string", "example": "Acme Corporation" }, "updated_at": { "type": "string", "example": "2026-03-14T09:00:00Z" } } }, "api_endpoints.BrandsListResponse": { "type": "object", "properties": { "count": { "type": "integer", "example": 2 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.BrandListItem" } } } }, "api_endpoints.CommentCapabilities": { "type": "object", "properties": { "can_delete": { "type": "boolean", "example": true }, "can_hide": { "type": "boolean", "example": true }, "can_like": { "type": "boolean", "example": true }, "can_private_reply": { "type": "boolean", "example": true }, "can_reply": { "type": "boolean", "example": true } } }, "api_endpoints.CommentWithCapabilities": { "type": "object", "properties": { "author_headline": { "type": "string" }, "author_id": { "type": "string" }, "author_name": { "type": "string" }, "author_picture": { "type": "string" }, "author_profile_url": { "type": "string" }, "author_username": { "type": "string" }, "capabilities": { "$ref": "#/components/schemas/api_endpoints.CommentCapabilities" }, "created_at": { "type": "string" }, "has_replies": { "type": "boolean" }, "id": { "description": "ID is the canonical SocialAPI interaction id (sapi_cmt_…). Prefer it over\nplatform_id, which is retained for backward compatibility.", "type": "string", "example": "sapi_cmt_TT974YVQH4RAHNN2HY2DJSNY9111D7LMTP1XXPCVQVL" }, "is_hidden": { "type": "boolean" }, "is_owner": { "type": "boolean" }, "like_count": { "type": "integer" }, "liked_by_viewer": { "description": "LikedByViewer is true when the connected account has liked this comment.\nLinkedIn reports it directly. Instagram and Facebook do not report it on\nthe comment read, so there it means \"liked through SocialAPI\": a like made\nin the platform's own app is not reflected.", "type": "boolean" }, "moderation_status": { "description": "ModerationStatus is the platform's moderation state for this comment, when\nexposed: \"published\", \"held_for_review\", \"likely_spam\", or \"rejected\".\nEmpty when unknown or not applicable. [platform: youtube]", "type": "string" }, "parent_id": { "type": "string" }, "platform": { "type": "string" }, "platform_id": { "type": "string" }, "reply_count": { "description": "ReplyCount is kept for backward compatibility but deprecated: prefer\nHasReplies. Not all platforms report an exact count.", "type": "integer" }, "text": { "type": "string" } } }, "api_endpoints.CommentedPostsListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.InboxPostRow" } }, "pagination": { "$ref": "#/components/schemas/api_endpoints.InboxPaginationOpt" } } }, "api_endpoints.CommentsWithCapsListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.CommentWithCapabilities" } }, "pagination": { "$ref": "#/components/schemas/api_endpoints.InboxPagination" } } }, "api_endpoints.ConnectAccountResponse": { "type": "object", "properties": { "account_id": { "type": "string", "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" }, "brand_id": { "description": "BrandID is the brand the account was connected to. When the connect request named no brand, this is the brand created for it.", "type": "string", "example": "b7e3c1a2-4f5d-4e8a-9b1c-2d3e4f5a6b7c" }, "display_name": { "type": "string", "example": "Acme Corp" }, "platform": { "type": "string", "example": "instagram" }, "username": { "type": "string", "example": "acmecorp" } } }, "api_endpoints.ConnectOAuthResponse": { "type": "object", "properties": { "auth_url": { "type": "string", "example": "https://www.instagram.com/oauth/authorize/?..." }, "message": { "type": "string", "example": "Redirect the user to auth_url" }, "metadata": { "type": "object", "additionalProperties": {} }, "state": { "type": "string", "example": "4a8f2c1e9b3d7f06a5c2e8b4d1f3a7e2" } } }, "api_endpoints.ConnectRequest": { "type": "object", "properties": { "brand_id": { "description": "BrandID optionally specifies which brand to attach the account to. If omitted, a new brand is auto-created.", "type": "string", "example": "b_01HZ9X3Q4R5M6N7P8V2K0W1J" }, "metadata": { "description": "Metadata contains platform-specific connection data. For tiktok, connection_type \"creator\" connects through TikTok's Content Posting API instead of the default Business API (\"business\"). For linkedin, connection_type \"profile\" or \"organization\" limits the connect to the member profile or to company Pages; without it, one authorization offers both, and the user picks one when there are several.", "type": "object", "additionalProperties": {} }, "onboarding": { "description": "Onboarding applies to WhatsApp only. cloud_api (default) connects the number for use through the API alone. business_app connects a number that stays in use on the WhatsApp Business app, and imports its recent chats.", "type": "string", "enum": [ "cloud_api", "business_app" ], "example": "cloud_api" }, "permissions": { "description": "Permissions are the permissions to request for this account. If omitted, the brand's existing selection for this platform applies, and a brand with none gets every permission. Valid values: posts.read, posts.write, comments.read, comments.write, messages.read, messages.write, reviews.read, reviews.write, analytics.read.", "type": "array", "items": { "type": "string" }, "example": [ "comments.read", "comments.write" ] }, "platform": { "description": "Platform identifies the social platform to connect (e.g. instagram, facebook, google, threads, tiktok, linkedin).", "type": "string", "example": "instagram" }, "redirect_uri": { "description": "RedirectURI is the customer's URL to redirect the user to after OAuth completes.\nIf you have registered redirect URIs in the dashboard, the value must match one of them.\nIf you have none registered, any valid https URI is accepted. If omitted, the default HTML success page is shown.", "type": "string", "example": "https://app.acme.com/oauth/done" }, "state": { "description": "CustomerState is an opaque value echoed back to the customer's redirect URI. Max 512 chars.", "type": "string", "example": "session_abc123" } } }, "api_endpoints.ConversationResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/social-api_ai_core_api_service.ConversationRow" } } }, "api_endpoints.ConversationsListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.ConversationRow" } }, "last_synced_at": { "type": "string" }, "pagination": { "$ref": "#/components/schemas/api_endpoints.InboxPagination" }, "sync_state": { "description": "SyncState is \"idle\", \"syncing\", or \"failed\" for this account's\nconversation-list sync. Reading it never triggers a sync, and a client\nthat ignores it sees exactly the previous response.", "type": "string", "enum": [ "idle", "syncing", "failed" ], "example": "idle" } } }, "api_endpoints.CreateBoardRequest": { "type": "object", "properties": { "description": { "type": "string", "example": "Weeknight dinners" }, "name": { "type": "string", "example": "Recipes" }, "privacy": { "type": "string", "enum": [ "PUBLIC", "PROTECTED", "SECRET" ], "example": "PUBLIC" } } }, "api_endpoints.CreateBrandRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Acme Corporation" } } }, "api_endpoints.CreateExportRequest": { "type": "object", "properties": { "include_transcript": { "type": "boolean", "example": true }, "include_vision": { "type": "boolean", "example": false } } }, "api_endpoints.CreateGoogleMediaRequest": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "COVER", "PROFILE", "LOGO", "EXTERIOR", "INTERIOR", "PRODUCT", "AT_WORK", "FOOD_AND_DRINK", "MENU", "COMMON_AREA", "ROOMS", "TEAMS", "ADDITIONAL" ], "example": "INTERIOR" }, "description": { "type": "string", "example": "Main dining room" }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.MediaInput" } } } }, "api_endpoints.CreateInviteRequest": { "type": "object", "properties": { "brand_id": { "type": "string", "example": "b_01HZ9X3Q4R5M6N7P8V2K0W1J" }, "expires_in_days": { "type": "integer", "example": 7 }, "permissions": { "description": "The permissions the connected account gets, which are the only ones the invited person is asked to grant. Omit it to keep the brand's current permissions for this platform, or to give every permission if it has none. Valid values: posts.read, posts.write, comments.read, comments.write, messages.read, messages.write, reviews.read, reviews.write, analytics.read.", "type": "array", "items": { "type": "string" }, "example": [ "comments.read", "comments.write" ] }, "platform": { "type": "string", "example": "facebook" } } }, "api_endpoints.CreateKeyRequest": { "type": "object", "properties": { "brand_ids": { "description": "BrandIDs restricts the key to specific brands. Empty means all brands.", "type": "array", "items": { "type": "string" } }, "name": { "type": "string", "example": "My App" }, "scopes": { "description": "Scopes restricts the key to specific actions. Empty means full access.", "type": "array", "items": { "type": "string" }, "example": [ "posts:write", "inbox:read" ] } } }, "api_endpoints.CreateKeyResponse": { "type": "object", "properties": { "brand_ids": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "message": { "type": "string", "example": "Store this key securely. It will not be shown again." }, "name": { "type": "string" }, "raw_key": { "type": "string", "example": "sapi_key_..." }, "scopes": { "type": "array", "items": { "type": "string" }, "example": [ "posts:write", "inbox:read" ] } } }, "api_endpoints.CreatePostRequest": { "type": "object", "properties": { "first_comment": { "description": "FirstComment is auto-posted as the first comment after publishing (Instagram, Facebook, YouTube). Ignored by every other platform, and by Facebook Page Stories.", "type": "string", "example": "Follow us for more updates!" }, "media": { "description": "Media is the ordered, agnostic media list. Each item is a url, a media_id,\nor a platform_attachment_id; order and mixing are preserved. Supersedes media_ids.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.MediaInput" } }, "media_ids": { "description": "MediaIDs are previously uploaded media file IDs to attach.\n\nDeprecated: use Media with source_type \"media_id\". Ignored when media is set.", "type": "array", "items": { "type": "string" } }, "platform_data": { "description": "PlatformData passes platform-specific fields keyed by platform name (e.g. {\"instagram\": {\"content_type\": \"feed\"}}). Folded into each matching target; a target's own platform_data wins on conflicts.", "type": "object", "additionalProperties": {} }, "publish_now": { "description": "PublishNow publishes immediately when targets are provided (ignores scheduled_at). Without this flag (and without scheduled_at) the post is saved as a draft; publish it later with POST /posts/{pid}/publish.", "type": "boolean", "example": false }, "queue_id": { "description": "QueueID puts the post in a Queue: it takes the Queue's earliest free time and is scheduled. Send a Queue ID, or \"default\" for the default Queue of the targets' Brand. Requires targets, all in one Brand. Cannot be combined with scheduled_at, publish_now or a target's scheduled_at.", "type": "string", "example": "que_01J9Z8Y7X6W5V4T3S2R1Q0P9N8" }, "scheduled_at": { "description": "ScheduledAt queues the post for future publication (RFC3339). When set, the post is scheduled rather than drafted.", "type": "string", "example": "2026-04-01T10:00:00Z" }, "segments": { "description": "Segments are continuation posts that publish as a native thread on X. Threads chaining is temporarily unavailable.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.SegmentRequest" } }, "skip_duplicate_check": { "description": "SkipDuplicateCheck bypasses the duplicate content detection.", "type": "boolean", "example": false }, "skip_validation": { "description": "SkipValidation bypasses pre-publish validation. The post is scheduled/published as-is and may fail at the platform.", "type": "boolean", "example": false }, "stagger": { "description": "Stagger spreads the targets out in time instead of publishing them all at once. Requires scheduled_at or publish_now. See StaggerRequest.", "allOf": [ { "$ref": "#/components/schemas/api_endpoints.StaggerRequest" } ] }, "targets": { "description": "Targets specifies which connected accounts to publish to, with optional per-target overrides.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.TargetRequest" } }, "text": { "description": "Text is the post body content. Required, unless every target supplies a\nbody of its own through text or a platform_data field the connector uses\nas the body (e.g. Pinterest's platform_data.description IS the pin body).", "type": "string", "example": "Check out our new product launch! #newproduct" }, "title": { "description": "Title is an optional post title (used by LinkedIn, Google).", "type": "string", "example": "Exciting News from Acme Corp" }, "visibility": { "description": "Visibility controls who can see the post. Platform-dependent values: public, private, connections_only, logged_in.", "type": "string", "enum": [ "public", "private", "connections_only", "logged_in" ], "example": "public" } } }, "api_endpoints.CreateRedirectURIRequest": { "type": "object", "properties": { "label": { "description": "Label is an optional human-readable label for this URI.", "type": "string", "example": "production" }, "uri": { "description": "URI is the redirect URI to whitelist (must be https, or http for localhost).", "type": "string", "example": "https://app.acme.com/oauth/done" } } }, "api_endpoints.CreateWebhookRequest": { "type": "object", "required": [ "events" ], "properties": { "events": { "description": "Events is the list of event types to subscribe to.", "type": "array", "items": { "type": "string", "enum": [ "post.scheduled", "post.published", "post.failed", "post.partial", "post.updated", "post.deleted", "post.unpublished", "post.retried", "comment.received", "dm.received", "dm.sent", "dm.referral", "dm.postback", "dm.deleted", "dm.status.sent", "dm.status.delivered", "dm.status.read", "dm.status.failed", "review.received", "review.updated", "mention.received", "account.connected", "account.disconnected", "account.updated", "page.removed" ] }, "example": [ "comment.received", "dm.received" ] }, "url": { "description": "URL is the HTTPS endpoint that will receive webhook POST requests.", "type": "string", "example": "https://example.com/webhooks/socialapi" } } }, "api_endpoints.CreateWebhookResponse": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "string" }, "example": [ "comment.received", "dm.received" ] }, "id": { "type": "string", "example": "wh_01HZ9X3Q4R5M6N7P8V2K0W1J" }, "message": { "type": "string", "example": "Store the secret securely. It will not be shown again." }, "secret": { "type": "string", "example": "4f3c2a1b9e8d7c6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2" }, "url": { "type": "string", "example": "https://example.com/webhooks/socialapi" } } }, "api_endpoints.CreatorInfoResponse": { "type": "object", "properties": { "avatar_url": { "description": "[platform: tiktok] Empty on other platforms", "type": "string" }, "can_post": { "description": "[platform: tiktok] Always false on other platforms", "type": "boolean" }, "interaction_settings": { "description": "[platform: tiktok] Nil on other platforms", "allOf": [ { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.InteractionSettings" } ] }, "max_video_duration_sec": { "description": "[platform: tiktok] Zero on other platforms", "type": "integer" }, "nickname": { "description": "[platform: tiktok] Empty on other platforms", "type": "string" }, "platform": { "description": "[always]", "type": "string" }, "privacy_level_options": { "description": "[platform: tiktok] Nil on other platforms", "type": "array", "items": { "type": "string" } } } }, "api_endpoints.DMAttachmentInput": { "type": "object", "properties": { "caption": { "description": "Caption is text shown with this attachment instead of as a separate message.\nSupported on WhatsApp (not on audio) and Telegram; ignored on platforms whose\nSend API has no caption, where an attachment is always a bare bubble.", "type": "string", "example": "The damaged panel" }, "source": { "description": "Source is the attachment reference; its meaning is given by source_type.", "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "source_type": { "description": "SourceType selects how Source is interpreted:\n - \"url\": Source is a publicly reachable media URL the platform fetches directly.\n - \"media_id\": Source is a file id in your SocialAPI media library\n (GET /v1/media).\n - \"platform_attachment_id\": Source is an id of media already uploaded to the\n target platform (for example a Meta attachment_id) to reuse without re-upload.", "type": "string", "enum": [ "url", "media_id", "platform_attachment_id" ], "example": "media_id" }, "type": { "description": "Type is the media kind. Optional for url and media_id sources (inferred from\nthe file), required for platform_attachment_id (the platform exposes no URL\nto infer from).", "type": "string", "enum": [ "image", "video", "audio", "file" ], "example": "image" }, "voice": { "description": "Voice sends an audio attachment as a native voice note (waveform and\nplayback-speed controls) instead of a file bubble. WhatsApp only, and only\nfor audio whose file is Ogg encoded with the OPUS codec; WhatsApp rejects\nany other container or codec. Ignored on other platforms.", "type": "boolean", "example": true } } }, "api_endpoints.DeletePostResponse": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.TargetDeleteOutcomeResponse" } }, "success": { "type": "boolean", "example": true } } }, "api_endpoints.DeleteQueueResponse": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "string" }, "released_count": { "description": "Number of posts that were in the Queue. They keep their scheduled times and are no longer queued.", "type": "integer" } } }, "api_endpoints.DeliveryDetailResponse": { "type": "object", "properties": { "attempt_count": { "type": "integer" }, "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.DeliveryAttempt" } }, "created_at": { "type": "string" }, "description": { "type": "string" }, "endpoint_id": { "type": "string" }, "event_type": { "type": "string" }, "id": { "type": "string" }, "payload": { "type": "array", "items": { "type": "integer" } }, "response_duration_ms": { "type": "integer" }, "response_status_code": { "type": "integer" }, "status": { "type": "string" } } }, "api_endpoints.DeliveryListResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.DeliveryListItem" } }, "next_cursor": { "type": "string" } } }, "api_endpoints.EditYouTubeCommentRequest": { "type": "object", "properties": { "account_id": { "type": "string" }, "post_id": { "type": "string" }, "text": { "type": "string" } } }, "api_endpoints.ErrorBody": { "type": "object", "properties": { "code": { "type": "string", "example": "resource.not_found" }, "message": { "type": "string", "example": "Account not found" }, "meta": { "type": "object", "additionalProperties": {} } } }, "api_endpoints.ErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/api_endpoints.ErrorBody" }, "request_id": { "description": "RequestID matches the X-Request-ID response header. Include it when contacting support.", "type": "string", "example": "01HZ9X3Q4R5M6N7P8V2K0W1J" } } }, "api_endpoints.EventResponse": { "type": "object", "properties": { "account_id": { "type": "string" }, "action": { "type": "string", "example": "publish" }, "category": { "type": "string", "example": "post" }, "created_at": { "type": "string", "example": "2026-03-27T10:00:00Z" }, "duration_ms": { "type": "integer", "example": 230 }, "error_category": { "type": "string", "example": "validation" }, "error_message": { "type": "string" }, "id": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "platform": { "type": "string", "example": "instagram" }, "resource_id": { "type": "string" }, "status": { "type": "string", "example": "success" }, "status_code": { "type": "integer", "example": 400 }, "summary": { "type": "string", "example": "Published to Instagram" } } }, "api_endpoints.EventsListResponse": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.EventResponse" } }, "pagination": { "$ref": "#/components/schemas/api_endpoints.PaginationInfo" }, "retention_days": { "type": "integer", "example": 30 } } }, "api_endpoints.EventsSummaryResponse": { "type": "object", "properties": { "by_category": { "type": "object", "additionalProperties": { "type": "integer" } }, "by_error_category": { "type": "object", "additionalProperties": { "type": "integer" } }, "failed": { "type": "integer" }, "inbox_breakdown": { "type": "object", "additionalProperties": { "type": "integer" } }, "retention_days": { "type": "integer" }, "total": { "type": "integer" }, "total_previous": { "type": "integer" } } }, "api_endpoints.ExchangeRequest": { "type": "object", "properties": { "code": { "description": "Code is the authorization code received from the platform callback.", "type": "string", "example": "AQDtbPB9X..." }, "metadata": { "description": "Metadata must include redirect_uri and state for CSRF validation.", "type": "object", "additionalProperties": {} }, "platform": { "description": "Platform identifies the social platform (must match the connect call).", "type": "string", "example": "instagram" } } }, "api_endpoints.ExportAcceptedResponse": { "type": "object", "properties": { "account_id": { "type": "string" }, "created_at": { "type": "string" }, "id": { "type": "string" }, "platform": { "type": "string" }, "status": { "type": "string" } } }, "api_endpoints.ExportItem": { "type": "object", "properties": { "account_id": { "type": "string" }, "completed_at": { "type": "string" }, "created_at": { "type": "string" }, "error": { "type": "string" }, "expires_at": { "type": "string" }, "id": { "type": "string" }, "platform": { "type": "string" }, "processed_videos": { "type": "integer" }, "status": { "type": "string" }, "total_videos": { "type": "integer" } } }, "api_endpoints.ExportResultURLs": { "type": "object", "properties": { "excel_url": { "type": "string" }, "report_url": { "type": "string" } } }, "api_endpoints.ExportStatusResponse": { "type": "object", "properties": { "account_id": { "type": "string" }, "completed_at": { "type": "string" }, "created_at": { "type": "string" }, "error": { "type": "string" }, "expires_at": { "type": "string" }, "id": { "type": "string" }, "platform": { "type": "string" }, "processed_videos": { "type": "integer" }, "result": { "$ref": "#/components/schemas/api_endpoints.ExportResultURLs" }, "status": { "type": "string" }, "total_videos": { "type": "integer" } } }, "api_endpoints.ExportVideoItem": { "type": "object", "properties": { "comment_count": { "type": "integer" }, "cover_image_url": { "type": "string" }, "create_time": { "type": "string" }, "description": { "type": "string" }, "duration_seconds": { "type": "integer" }, "height": { "type": "integer" }, "like_count": { "type": "integer" }, "platform": { "type": "string" }, "platform_video_id": { "type": "string" }, "share_count": { "type": "integer" }, "share_url": { "type": "string" }, "title": { "type": "string" }, "transcript": { "type": "string" }, "transcript_lang": { "type": "string" }, "view_count": { "type": "integer" }, "vision_category": { "type": "string" }, "vision_elements": { "type": "array", "items": { "type": "string" } }, "vision_summary": { "type": "string" }, "width": { "type": "integer" } } }, "api_endpoints.ExportVideosResponse": { "type": "object", "properties": { "account_id": { "type": "string" }, "platform": { "type": "string" }, "videos": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.ExportVideoItem" } } } }, "api_endpoints.ExportsListResponse": { "type": "object", "properties": { "exports": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.ExportItem" } } } }, "api_endpoints.FacebookAccountSummaryResponse": { "type": "object", "properties": { "follower_count": { "type": "integer" }, "interactions": { "type": "integer" }, "net_follows": { "type": "integer" }, "period_end": { "type": "string" }, "period_start": { "type": "string" }, "reach": { "type": "integer" }, "views": { "type": "integer" } } }, "api_endpoints.FacebookDailyInsightsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.DailyInsight" } } } }, "api_endpoints.FacebookLoginPagesResponse": { "type": "object", "properties": { "count": { "type": "integer", "example": 3 }, "login_id": { "type": "string", "example": "cred_01J..." }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.PendingPage" } } } }, "api_endpoints.FiringListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.Firing" } }, "next_cursor": { "description": "Pass as cursor to fetch the next page. Empty on the last page", "type": "string" } } }, "api_endpoints.GoogleInsightsResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPInsights" } } }, "api_endpoints.GoogleLocation": { "type": "object", "properties": { "assignable": { "type": "boolean" }, "assigned_account_id": { "type": "string" }, "assigned_brand_id": { "type": "string" }, "assigned_brand_name": { "type": "string" }, "bio": { "type": "string", "example": "Wood-fired pizza since 1998" }, "category": { "description": "Category is the location's primary Google category, localized.", "type": "string", "example": "Pizza restaurant" }, "details": { "description": "Details is the rest of what Google publishes about the location: address,\nphone numbers, categories, opening hours, service area, and the Maps and\nreview links. Fields are omitted when Google returns no value, so a\nservice-area business has no storefront_address rather than an empty one.", "allOf": [ { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPLocationDetails" } ] }, "maps_uri": { "description": "MapsURI is the location's page on Google Maps.", "type": "string", "example": "https://maps.google.com/?cid=123" }, "name": { "type": "string", "example": "Joe's Pizza (Downtown)" }, "platform_account_id": { "type": "string", "example": "accounts/123/locations/456" } } }, "api_endpoints.GoogleLoginLocationsResponse": { "type": "object", "properties": { "count": { "type": "integer", "example": 3 }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.GoogleLocation" } }, "login_email": { "type": "string", "example": "joe@example.com" }, "login_id": { "type": "string", "example": "cred_01J..." }, "login_name": { "type": "string", "example": "joe@example.com" } } }, "api_endpoints.GoogleMediaAttribution": { "type": "object", "properties": { "profile_name": { "type": "string", "example": "Jane S." }, "profile_photo_url": { "type": "string" }, "profile_url": { "type": "string" }, "takedown_url": { "type": "string" } } }, "api_endpoints.GoogleMediaItem": { "type": "object", "properties": { "attribution": { "$ref": "#/components/schemas/api_endpoints.GoogleMediaAttribution" }, "category": { "type": "string", "example": "INTERIOR" }, "created_at": { "type": "string", "example": "2026-03-01T12:00:00Z" }, "description": { "type": "string", "example": "Main dining room" }, "height_pixels": { "type": "integer", "example": 1200 }, "id": { "type": "string", "example": "accounts/123/locations/456/media/789" }, "media": { "$ref": "#/components/schemas/api_endpoints.MediaRef" }, "thumbnail_url": { "type": "string" }, "width_pixels": { "type": "integer", "example": 1600 } } }, "api_endpoints.GoogleMediaListResponse": { "type": "object", "properties": { "count": { "type": "integer", "example": 12 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.GoogleMediaItem" } }, "next_cursor": { "type": "string" }, "total_count": { "description": "TotalCount is the total number of media items on the location, across all\npages. Zero means an empty gallery.", "type": "integer", "example": 42 } } }, "api_endpoints.GoogleSearchKeywordsResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPKeywordsPage" } } }, "api_endpoints.ImportPostsResponse": { "type": "object", "properties": { "created": { "type": "integer", "example": 8 }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.ImportRowError" } }, "failed": { "type": "integer", "example": 2 }, "posts": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.PostResponse" } }, "total_rows": { "type": "integer", "example": 10 } } }, "api_endpoints.ImportRowError": { "type": "object", "properties": { "message": { "type": "string", "example": "invalid date format for scheduled_at" }, "row": { "type": "integer", "example": 3 } } }, "api_endpoints.InboxPagination": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" } } }, "api_endpoints.InboxPaginationOpt": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" } } }, "api_endpoints.InboxSyncRequest": { "type": "object", "properties": { "account_id": { "type": "string", "example": "acc_01H..." }, "conversation_id": { "type": "string", "example": "6f1c..." } } }, "api_endpoints.InboxSyncResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/api_endpoints.InboxSyncStatus" } } }, "api_endpoints.InboxSyncStatus": { "type": "object", "properties": { "error": { "type": "string", "example": "" }, "finished_at": { "type": "string" }, "last_synced_at": { "type": "string" }, "started_at": { "type": "string" }, "state": { "description": "State is \"idle\", \"syncing\", or \"failed\". A finished sync is idle with a\nfresher LastSyncedAt; there is no terminal \"done\".", "type": "string", "enum": [ "idle", "syncing", "failed" ], "example": "syncing" }, "synced": { "description": "Synced is how many items the last completed sync brought in. Display only.", "type": "integer", "example": 12 } } }, "api_endpoints.InstagramAccountSummaryResponse": { "type": "object", "properties": { "accounts_engaged": { "type": "integer" }, "display_name": { "type": "string" }, "follower_count": { "type": "integer" }, "following_count": { "type": "integer" }, "interactions": { "type": "integer" }, "media_count": { "type": "integer" }, "net_follows": { "type": "integer" }, "period_end": { "type": "string" }, "period_start": { "type": "string" }, "picture_url": { "type": "string" }, "reach": { "type": "integer" }, "username": { "type": "string" }, "views": { "type": "integer" } } }, "api_endpoints.InstagramCollaboratorsResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.Collaborator" } } } }, "api_endpoints.InstagramParticipantProfileResponse": { "type": "object", "properties": { "follower_count": { "type": "integer" }, "id": { "type": "string" }, "is_business_follow_user": { "type": "boolean" }, "is_user_follow_business": { "type": "boolean" }, "is_verified_user": { "type": "boolean" }, "name": { "type": "string" }, "profile_pic": { "description": "ProfilePic URLs expire after a few days; never persist one as durable.", "type": "string" }, "username": { "type": "string" } } }, "api_endpoints.InstagramStoriesResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.Post" } }, "next_cursor": { "type": "string" } } }, "api_endpoints.InviteListItem": { "type": "object", "properties": { "created_at": { "type": "string", "example": "2026-03-27T12:00:00Z" }, "expires_at": { "type": "string", "example": "2026-04-03T12:00:00Z" }, "id": { "type": "string", "example": "inv_01HZ9X3Q4R5M6N7P8V2K0W1J" }, "is_active": { "type": "boolean", "example": true }, "permissions": { "description": "The permissions chosen when the invite was created. null means the brand's current permissions for this platform apply when the invite is used, or every permission if it has none.", "type": "array", "items": { "type": "string" }, "example": [ "comments.read", "comments.write" ] }, "platform": { "type": "string", "example": "facebook" }, "token": { "type": "string", "example": "a55755cf..." }, "url": { "type": "string", "example": "https://api.social-api.ai/invite/a55755cf..." } } }, "api_endpoints.InviteListResponse": { "type": "object", "properties": { "count": { "type": "integer", "example": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.InviteListItem" } } } }, "api_endpoints.InviteResponse": { "type": "object", "properties": { "expires_at": { "type": "string", "example": "2026-04-03T12:00:00Z" }, "id": { "type": "string", "example": "inv_01HZ9X3Q4R5M6N7P8V2K0W1J" }, "permissions": { "description": "The permissions chosen when the invite was created. null means the brand's current permissions for this platform apply when the invite is used, or every permission if it has none.", "type": "array", "items": { "type": "string" }, "example": [ "comments.read", "comments.write" ] }, "platform": { "type": "string", "example": "facebook" }, "token": { "type": "string", "example": "a55755cf75f73b56deb3dfe0c993fd36fc4c2bfa7" }, "url": { "type": "string", "example": "https://api.social-api.ai/invite/a55755cf..." } } }, "api_endpoints.KeyListItem": { "type": "object", "properties": { "brand_ids": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "example": "2026-02-28T12:00:00Z" }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "last_used_at": { "type": "string", "example": "2026-02-28T12:00:00Z" }, "name": { "type": "string" }, "preview": { "type": "string", "example": "sapi_key_a1b2c..." }, "scopes": { "type": "array", "items": { "type": "string" }, "example": [ "posts:write", "inbox:read" ] } } }, "api_endpoints.KeyScopeItem": { "type": "object", "properties": { "description": { "type": "string", "example": "Create, edit, publish, and delete posts" }, "group": { "type": "string", "example": "Posts" }, "name": { "type": "string", "example": "posts:write" } } }, "api_endpoints.KeyScopesResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.KeyScopeItem" } } } }, "api_endpoints.KeysListResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.KeyListItem" } } } }, "api_endpoints.LinkedInInsightsResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.PageInsights" } } }, "api_endpoints.LinkedInLoginProfile": { "type": "object", "properties": { "assignable": { "type": "boolean" }, "assigned_account_id": { "type": "string" }, "assigned_brand_id": { "type": "string" }, "assigned_brand_name": { "type": "string" }, "connection_type": { "description": "ConnectionType is \"profile\" for the member, \"organization\" for a company Page.", "type": "string", "enum": [ "profile", "organization" ], "example": "organization" }, "name": { "type": "string", "example": "Acme Corp" }, "picture_url": { "type": "string" }, "platform_account_id": { "type": "string", "example": "urn:li:organization:123456" }, "username": { "type": "string", "example": "acme-corp" } } }, "api_endpoints.LinkedInLoginProfilesResponse": { "type": "object", "properties": { "count": { "type": "integer", "example": 2 }, "login_id": { "type": "string", "example": "cred_01J..." }, "login_name": { "description": "LoginName is the name of the LinkedIn member who authorized the login.", "type": "string", "example": "Jane Doe" }, "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.LinkedInLoginProfile" } } } }, "api_endpoints.ListWebhookEventsResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.WebhookEventInfo" } } } }, "api_endpoints.LostPageAccess": { "type": "object", "properties": { "brand_id": { "type": "string" }, "brand_name": { "type": "string" }, "name": { "type": "string" }, "platform_page_id": { "type": "string" } } }, "api_endpoints.MediaInput": { "type": "object", "properties": { "source": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "source_type": { "type": "string", "enum": [ "url", "media_id", "platform_attachment_id" ], "example": "media_id" }, "type": { "type": "string", "enum": [ "image", "video", "audio", "file" ], "example": "image" } } }, "api_endpoints.MediaItemResponse": { "type": "object", "properties": { "content_type": { "type": "string", "example": "image/jpeg" }, "created_at": { "type": "string", "example": "2026-03-20T09:00:00Z" }, "filename": { "type": "string", "example": "photo.jpg" }, "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "size_bytes": { "type": "integer", "example": 2048576 }, "status": { "type": "string", "example": "ready" }, "url": { "type": "string", "example": "https://s3.example.com/media/..." } } }, "api_endpoints.MediaListResponse": { "type": "object", "properties": { "count": { "type": "integer", "example": 42 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.MediaItemResponse" } }, "next_cursor": { "type": "string" } } }, "api_endpoints.MediaRef": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video" ], "example": "image" }, "url": { "type": "string", "example": "https://lh3.googleusercontent.com/p/abc" } } }, "api_endpoints.MediaUploadInfoResponse": { "type": "object", "properties": { "expires_at": { "type": "string", "example": "2026-03-14T09:15:00Z" }, "media_id": { "type": "string" }, "upload_url": { "type": "string" } } }, "api_endpoints.MediaUploadResponse": { "type": "object", "properties": { "media_id": { "type": "string" } } }, "api_endpoints.MentionsListResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.Interaction" } }, "next_cursor": { "type": "string" } } }, "api_endpoints.MessageButton": { "type": "object", "properties": { "payload": { "type": "string", "example": "VIEW_ORDER" }, "title": { "type": "string", "example": "View order" }, "type": { "type": "string", "enum": [ "url", "postback" ], "example": "url" }, "url": { "type": "string", "example": "https://shop.example.com/orders/1" } } }, "api_endpoints.MessageCard": { "type": "object", "properties": { "buttons": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.MessageButton" } }, "image_url": { "type": "string", "example": "https://cdn.example.com/p.jpg" }, "subtitle": { "type": "string", "example": "Short description" }, "title": { "type": "string", "example": "Product name" } } }, "api_endpoints.MessageListRow": { "type": "object", "properties": { "description": { "type": "string", "example": "3 posts waiting" }, "id": { "type": "string", "example": "menu:review_drafts" }, "title": { "type": "string", "example": "Review drafts" } } }, "api_endpoints.MessageListSection": { "type": "object", "properties": { "rows": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.MessageListRow" } }, "title": { "type": "string", "example": "This week" } } }, "api_endpoints.MessageQuickReply": { "type": "object", "properties": { "payload": { "type": "string", "example": "TRACK_ORDER" }, "title": { "type": "string", "example": "Track my order" } } }, "api_endpoints.MessagesListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.MessageRow" } }, "last_synced_at": { "type": "string" }, "pagination": { "$ref": "#/components/schemas/api_endpoints.InboxPagination" }, "sync_state": { "description": "SyncState is \"idle\", \"syncing\", or \"failed\" for this thread's message sync.", "type": "string", "enum": [ "idle", "syncing", "failed" ], "example": "idle" } } }, "api_endpoints.MetricsResponse": { "type": "object", "properties": { "post_id": { "type": "string" }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.PostTargetResponse" } } } }, "api_endpoints.MetricsResponseWrapper": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/api_endpoints.MetricsResponse" } } }, "api_endpoints.MigrationAssessment": { "type": "object", "properties": { "brands": { "description": "Brands needed across all profiles.", "type": "integer" }, "pages_per_brand": { "description": "Most Pages any one Brand needs on a single platform.", "type": "integer" }, "profiles": { "description": "One entry per profile at your provider.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.MigrationProfile" } }, "recommended_plan": { "description": "Cheapest plan that fits.", "allOf": [ { "$ref": "#/components/schemas/api_endpoints.MigrationPlan" } ] }, "servable_accounts": { "description": "Accounts SocialAPI can serve.", "type": "integer" }, "stays_with_provider": { "description": "Accounts that stay with your provider, by platform.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.MigrationUnsupported" } } } }, "api_endpoints.MigrationAuthorisation": { "type": "object", "properties": { "text": { "type": "string" }, "version": { "type": "string" } } }, "api_endpoints.MigrationPlan": { "type": "object", "properties": { "brands_limit": { "type": "integer" }, "name": { "type": "string" }, "pages_per_brand": { "type": "integer" }, "tier": { "type": "string", "example": "starter" } } }, "api_endpoints.MigrationProfile": { "type": "object", "properties": { "brands": { "type": "integer" }, "id": { "type": "string" }, "name": { "type": "string" }, "pages_per_brand": { "type": "integer" }, "servable_accounts": { "type": "integer" }, "splits": { "description": "Why the profile needs more than one Brand, one line per reason.", "type": "array", "items": { "type": "string" } } } }, "api_endpoints.MigrationResponse": { "type": "object", "properties": { "assessed_at": { "description": "When the accounts were last read, RFC 3339. Null until the first read succeeds.", "type": "string" }, "assessment": { "description": "Your accounts and how they map to SocialAPI. Null until started, or when your provider could not be read.", "allOf": [ { "$ref": "#/components/schemas/api_endpoints.MigrationAssessment" } ] }, "assessment_error": { "description": "Why `assessment` is null on a started migration: `migration.key_invalid`, `migration.key_restricted` or `migration.source_unavailable`.", "type": "string" }, "authorisation": { "description": "Text to accept before starting, and its version.", "allOf": [ { "$ref": "#/components/schemas/api_endpoints.MigrationAuthorisation" } ] }, "authorisation_version": { "description": "Version of the authorisation text accepted. Null until started.", "type": "string" }, "authorised_at": { "description": "When the authorisation was accepted, RFC 3339. Null until started.", "type": "string" }, "base_url": { "description": "Base URL to set in your existing client. Null until started.", "type": "string", "example": "https://z.social-api.ai/api" }, "created_at": { "description": "When the migration started, RFC 3339. Null until started.", "type": "string" }, "cut_over": { "description": "Accounts already reconnected to SocialAPI.", "type": "integer" }, "forwarded_calls": { "description": "Requests sent through the base URL since the migration started.", "type": "integer" }, "key_hint": { "description": "Start and end of the key in use. Null until started.", "type": "string" }, "started": { "description": "True once a migration has started.", "type": "boolean" } } }, "api_endpoints.MigrationUnsupported": { "type": "object", "properties": { "count": { "type": "integer" }, "platform": { "description": "Platform name as your provider reports it.", "type": "string" }, "reason": { "description": "Why the accounts stay: \"unserved platform\", \"ads\", \"telephony\", \"commerce\", \"unknown platform\" or \"linked to another account\".", "type": "string" } } }, "api_endpoints.ModerateYouTubeCommentRequest": { "type": "object", "properties": { "account_id": { "type": "string" }, "ban_author": { "type": "boolean" }, "post_id": { "type": "string" }, "status": { "type": "string" } } }, "api_endpoints.OKResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } } }, "api_endpoints.PagesListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.AccountPage" } } } }, "api_endpoints.PaginationInfo": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "limit": { "type": "integer", "example": 25 }, "next_cursor": { "type": "string" } } }, "api_endpoints.PatchMeRequest": { "type": "object", "properties": { "job_role": { "description": "JobRole records what best describes the user. Surrounding whitespace is\ntrimmed, an empty value leaves the current one unchanged, and values\nlonger than 120 characters are truncated.", "type": "string", "example": "Founder / CEO" }, "lock_accounts_to_brand": { "description": "LockAccountsToBrand toggles whether a social account already connected to\none brand may be re-connected (moved) to a different brand. When true, such\na connect attempt is rejected with 409 account.already_linked.", "type": "boolean", "example": true }, "onboarding": { "type": "boolean", "example": false }, "referral": { "type": "string", "example": "Google search" }, "signup_metadata": { "description": "SignupMetadata adds keys to the signup answers on record: a shallow\nmerge, so keys sent replace the same keys and others are kept. At most\n4096 bytes once encoded.", "type": "object", "additionalProperties": {} }, "use_case": { "type": "string", "example": "Managing my own brand's social accounts" } } }, "api_endpoints.PendingConnectionDetailResponse": { "type": "object", "properties": { "connection_id": { "type": "string" }, "expires_at": { "type": "string", "example": "2026-07-04T12:30:00Z" }, "login_id": { "description": "login_id identifies the login and is set for Facebook, Google and LinkedIn.\npages and lost_access are Facebook page-selection only.", "type": "string" }, "lost_access": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.LostPageAccess" } }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.PendingPage" } }, "platform": { "type": "string", "example": "google" }, "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.PendingProfile" } } } }, "api_endpoints.PendingConnectionResponse": { "type": "object", "properties": { "connection_id": { "type": "string", "example": "pc_4a8f2c1e9b3d7f06a5c2e8b4d1f3a7e2" }, "login_id": { "description": "login_id identifies the login and is set for Facebook, Google and LinkedIn.\npages and lost_access are Facebook page-selection only.", "type": "string" }, "lost_access": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.LostPageAccess" } }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.PendingPage" } }, "platform": { "type": "string", "example": "google" }, "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.PendingProfile" } }, "status": { "type": "string", "example": "selection_required" } } }, "api_endpoints.PendingPage": { "type": "object", "properties": { "assignable": { "type": "boolean" }, "assigned_account_id": { "type": "string" }, "assigned_brand_id": { "type": "string" }, "assigned_brand_name": { "type": "string" }, "category": { "type": "string" }, "name": { "type": "string", "example": "Acme Bakery" }, "picture_url": { "type": "string" }, "platform_page_id": { "type": "string", "example": "17841400000000000" } } }, "api_endpoints.PendingProfile": { "type": "object", "properties": { "bio": { "type": "string", "example": "Wood-fired pizza since 1998" }, "display_name": { "type": "string", "example": "Joe's Pizza (Downtown)" }, "platform_account_id": { "type": "string", "example": "accounts/123/locations/456" }, "profile_picture_url": { "type": "string", "example": "" }, "username": { "type": "string", "example": "" } } }, "api_endpoints.PinterestBoardItem": { "type": "object", "properties": { "board_id": { "type": "string", "example": "8828" }, "id": { "type": "string", "example": "sapi_board_01HZ9X3Q4R5M6N7P8V2K0W1J" }, "name": { "type": "string", "example": "Recipes" }, "privacy": { "type": "string", "enum": [ "PUBLIC", "PROTECTED", "SECRET" ], "example": "PUBLIC" } } }, "api_endpoints.PinterestBoardsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.PinterestBoardItem" } } } }, "api_endpoints.PinterestPinItem": { "type": "object", "properties": { "board_id": { "type": "string", "example": "8828" }, "created_at": { "type": "string", "example": "2026-08-01T12:00:00Z" }, "id": { "type": "string", "example": "813744South" }, "media_url": { "type": "string", "example": "https://i.pinimg.com/x.jpg" }, "permalink": { "type": "string", "example": "https://www.pinterest.com/pin/813744/" }, "title": { "description": "Title carries the pin's description, not Pinterest's separate title field.", "type": "string", "example": "Roast chicken" } } }, "api_endpoints.PinterestPinsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.PinterestPinItem" } } } }, "api_endpoints.PinterestSummaryResponse": { "type": "object", "properties": { "board_count": { "type": "integer", "example": 23 }, "follower_count": { "type": "integer", "example": 12400 }, "monthly_views": { "type": "integer", "example": 1200000 }, "pin_count": { "type": "integer", "example": 847 }, "profile_image": { "type": "string", "example": "https://i.pinimg.com/x.jpg" }, "username": { "type": "string", "example": "boardandco" } } }, "api_endpoints.PlatformConstraintsResponse": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/social-api_ai_core_api_service.PlatformConstraints" } } } }, "api_endpoints.PostResponse": { "type": "object", "properties": { "created_at": { "type": "string", "example": "2026-03-14T09:00:00Z" }, "hidden": { "type": "boolean", "example": false }, "id": { "type": "string", "example": "p_01HZ9X3Q4R5M6N7P8V2K0W1J" }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.MediaInput" } }, "media_ids": { "description": "Deprecated: use media.", "type": "array", "items": { "type": "string" } }, "published_at": { "type": "string", "example": "2026-04-01T10:00:05Z" }, "queue_id": { "description": "ID of the Queue the post is in. null when the post is not queued.", "type": "string", "example": "que_01J9Z8Y7X6W5V4T3S2R1Q0P9N8" }, "retry_count": { "type": "integer", "example": 0 }, "scheduled_at": { "type": "string", "example": "2026-04-01T10:00:00Z" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "partial", "failed", "cancelled" ], "example": "published" }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.PostTargetResponse" } }, "text": { "type": "string", "example": "Check out our new product launch!" }, "title": { "type": "string", "example": "Exciting News" }, "updated_at": { "type": "string", "example": "2026-03-14T09:00:00Z" }, "visibility": { "type": "string", "enum": [ "public", "private", "connections_only", "logged_in" ], "example": "public" } } }, "api_endpoints.PostTargetErrorResponse": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "validation", "auth", "rate_limit", "platform", "system" ], "example": "validation" }, "caused_by": { "type": "string", "enum": [ "user", "platform", "system" ], "example": "user" }, "code": { "type": "string", "example": "platform.tiktok.media_required" }, "message": { "type": "string", "example": "Video posts require at least one media URL" } } }, "api_endpoints.PostTargetMetricsResponse": { "type": "object", "properties": { "avg_watch_time_ms": { "description": "Average time a viewer spent watching the video, in milliseconds.", "type": "integer", "example": 7400 }, "calls": { "description": "Taps on the profile's call button.", "type": "integer", "example": 2 }, "comments": { "type": "integer", "example": 23 }, "crossposted_views": { "description": "Views of the copy shared to another network, for a post shared there too.", "type": "integer", "example": 310 }, "directions": { "description": "Taps on the profile's directions button.", "type": "integer", "example": 1 }, "emails": { "description": "Taps on the profile's email button.", "type": "integer", "example": 2 }, "extra": { "type": "object", "additionalProperties": {} }, "follows": { "description": "Accounts that followed after seeing the post.", "type": "integer", "example": 12 }, "interactions": { "description": "Likes, comments, saves and shares combined, as the platform counts them.", "type": "integer", "example": 204 }, "likes": { "type": "integer", "example": 142 }, "profile_actions": { "description": "Actions taken on the account's profile after visiting it from the post. website_clicks, calls, directions, emails and texts break it down.", "type": "integer", "example": 15 }, "profile_visits": { "description": "Visits to the account's profile from the post.", "type": "integer", "example": 48 }, "reach": { "description": "Unique accounts that saw the post.", "type": "integer", "example": 3870 }, "reposts": { "description": "Times other accounts reposted the post.", "type": "integer", "example": 6 }, "saves": { "type": "integer", "example": 31 }, "shares": { "type": "integer", "example": 8 }, "skip_rate": { "description": "Percentage of viewers who skipped the video near its start.", "type": "number", "example": 42.5 }, "texts": { "description": "Taps on the profile's text message button.", "type": "integer", "example": 1 }, "total_watch_time_ms": { "description": "Total time all viewers spent watching the video, in milliseconds.", "type": "integer", "example": 37888000 }, "views": { "description": "Times the post was shown or played.", "type": "integer", "example": 5120 }, "website_clicks": { "description": "Clicks on the profile's website link.", "type": "integer", "example": 9 } } }, "api_endpoints.PostTargetResponse": { "type": "object", "properties": { "account_id": { "type": "string", "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" }, "board_id": { "type": "string", "example": "8828" }, "error": { "$ref": "#/components/schemas/api_endpoints.PostTargetErrorResponse" }, "first_comment": { "type": "string" }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.MediaInput" } }, "media_ids": { "description": "Deprecated: use media.", "type": "array", "items": { "type": "string" } }, "media_type": { "type": "string", "enum": [ "feed", "reel", "stories", "carousel" ], "example": "reel" }, "metadata": { "type": "object", "additionalProperties": {} }, "metrics": { "$ref": "#/components/schemas/api_endpoints.PostTargetMetricsResponse" }, "metrics_synced_at": { "type": "string", "example": "2026-04-01T12:00:00Z" }, "page_id": { "type": "string", "example": "sapi_page_01HZ9X3Q4R5M6N7P8V2K0W1J" }, "permalink": { "type": "string", "example": "https://www.instagram.com/p/ABC123/" }, "platform": { "type": "string", "enum": [ "instagram", "facebook", "threads", "tiktok", "linkedin", "google", "zalo", "youtube", "twitter", "bluesky", "whatsapp", "pinterest" ], "example": "instagram" }, "platform_data": { "description": "The platform-specific options set on this target, as sent in platform_data when the post was created or last updated. Chain continuation posts are returned in segments, not here.", "type": "object", "additionalProperties": {} }, "platform_media": { "description": "Every image and video Instagram or Facebook reports on the published post: carousel slides or album photos in order, with a cover image for each video. The links are temporary: download the files rather than keeping the links, and call POST /v1/accounts/{id}/sync to get fresh ones. Absent on Facebook link and share posts and on other platforms.", "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.PlatformMediaItem" } }, "platform_post_id": { "type": "string", "example": "17895695668004550" }, "published_at": { "type": "string", "example": "2026-04-01T10:00:05Z" }, "scheduled_at": { "type": "string", "example": "2026-04-01T10:00:00Z" }, "settings": { "description": "Publish settings Instagram or Facebook reports for the published post, such as the AI info label, alt text, tagged place or audience targeting. Absent when the platform reported none.", "allOf": [ { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.PostSettings" } ] }, "status": { "type": "string", "enum": [ "pending", "publishing", "published", "failed" ], "example": "published" }, "text": { "type": "string" }, "title": { "type": "string" }, "visibility": { "type": "string", "example": "public" } } }, "api_endpoints.PostsListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.PostResponse" } }, "pagination": { "$ref": "#/components/schemas/api_endpoints.PaginationInfo" } } }, "api_endpoints.PrivateReplyAttachmentInput": { "type": "object", "properties": { "source": { "description": "Source is the attachment reference; its meaning is given by source_type.", "type": "string", "example": "https://cdn.example.com/guide.pdf" }, "source_type": { "description": "SourceType selects how Source is interpreted:\n - \"url\": Source is a publicly reachable media URL the platform fetches directly.\n - \"media_id\": Source is a file id in your SocialAPI media library\n (GET /v1/media).\n - \"platform_attachment_id\": Source is an id of media already uploaded to the\n target platform (for example a Meta attachment_id).", "type": "string", "enum": [ "url", "media_id", "platform_attachment_id" ], "example": "url" }, "type": { "description": "Type is the media kind. Optional for url and media_id sources (inferred from\nthe file), required for platform_attachment_id.", "type": "string", "enum": [ "image", "video", "audio", "file" ], "example": "file" } } }, "api_endpoints.PrivateReplyRequest": { "type": "object", "properties": { "account_id": { "type": "string" }, "attachment": { "description": "Attachment sends one image, video, audio or file as the private reply,\ninstead of text. Leave text and buttons empty when you set it.", "allOf": [ { "$ref": "#/components/schemas/api_endpoints.PrivateReplyAttachmentInput" } ] }, "buttons": { "description": "Buttons renders a button template (1-3 buttons); uses text as the bubble body.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.MessageButton" } }, "text": { "type": "string" } } }, "api_endpoints.QueueListResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.Queue" } } } }, "api_endpoints.QueuePreviewResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.QueuedTime" } } } }, "api_endpoints.ReactToMessageRequest": { "type": "object", "properties": { "account_id": { "type": "string" }, "reaction": { "type": "string", "example": "🎉" } } }, "api_endpoints.RedirectURIListResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.RedirectURIResponse" } } } }, "api_endpoints.RedirectURIResponse": { "type": "object", "properties": { "created_at": { "type": "string", "example": "2026-04-10T12:00:00Z" }, "id": { "type": "string", "example": "sapi_ruri_a1b2c3d4e5f6" }, "label": { "type": "string", "example": "production" }, "uri": { "type": "string", "example": "https://app.acme.com/oauth/done" } } }, "api_endpoints.ReplyReviewRequest": { "type": "object", "properties": { "account_id": { "type": "string" }, "text": { "type": "string" } } }, "api_endpoints.ReplyToCommentSuccessResponse": { "type": "object", "properties": { "comment_id": { "type": "string" }, "success": { "type": "boolean" } } }, "api_endpoints.ReplyToReviewResponse": { "type": "object", "properties": { "reply_id": { "type": "string", "example": "r_abc123" }, "state": { "type": "string", "example": "PENDING" }, "success": { "type": "boolean", "example": true } } }, "api_endpoints.ReviewAccountRow": { "type": "object", "properties": { "account_id": { "type": "string", "example": "acc_01HZ..." }, "average_rating": { "type": "number", "example": 4.2 }, "last_review_at": { "type": "string", "example": "2026-06-22T02:24:05Z" }, "name": { "type": "string", "example": "SocialAPI Profile" }, "platform": { "type": "string", "example": "google" }, "status": { "type": "string", "enum": [ "ok", "reconnection_required", "error" ], "example": "ok" }, "total_count": { "type": "integer", "example": 87 } } }, "api_endpoints.ReviewAccountsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.ReviewAccountRow" } } } }, "api_endpoints.ReviewItem": { "type": "object", "properties": { "author": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.Author" }, "created_at": { "type": "string", "example": "2026-06-20T18:24:31Z" }, "id": { "type": "string", "example": "sapi_rev_TXY..." }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.ReviewMediaDTO" } }, "rating": { "type": "integer", "example": 3 }, "reply": { "$ref": "#/components/schemas/api_endpoints.ReviewReplyDTO" }, "reply_url": { "description": "ReplyURL is the platform-hosted page for replying to this review, when\nthe platform exposes one (Google). Empty elsewhere.", "type": "string", "example": "https://business.google.com/reviews/reply/abc" }, "text": { "type": "string", "example": "Great school" }, "title": { "description": "Title is the review's headline, on platforms whose reviews have one (App Store Connect).", "type": "string", "example": "Love it" }, "updated_at": { "type": "string", "example": "2026-06-20T18:24:31Z" } } }, "api_endpoints.ReviewMediaDTO": { "type": "object", "properties": { "thumbnail_label": { "type": "string", "example": "Photo 1" }, "thumbnail_url": { "type": "string", "example": "https://lh3.googleusercontent.com/p/abc" }, "video_url": { "type": "string", "example": "https://lh3.googleusercontent.com/v/xyz" } } }, "api_endpoints.ReviewReplyDTO": { "type": "object", "properties": { "policy_violation": { "description": "PolicyViolation explains a REJECTED reply, passed through verbatim from\nthe platform. Absent otherwise.", "type": "object" }, "state": { "description": "State is the moderation outcome: PENDING, APPROVED, or REJECTED.\nOmitted on platforms that report no moderation state (App Store Connect).", "type": "string", "example": "APPROVED" }, "text": { "type": "string", "example": "Thanks for the feedback!" }, "updated_at": { "type": "string", "example": "2026-06-21T10:00:00Z" } } }, "api_endpoints.ReviewSummaryResponse": { "type": "object", "properties": { "average_rating": { "type": "number", "example": 4.2 }, "total_count": { "type": "integer", "example": 87 } } }, "api_endpoints.ReviewsListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.ReviewItem" } }, "pagination": { "$ref": "#/components/schemas/api_endpoints.InboxPagination" }, "summary": { "$ref": "#/components/schemas/api_endpoints.ReviewSummaryResponse" } } }, "api_endpoints.SegmentRequest": { "type": "object", "properties": { "media": { "description": "Media is the ordered, agnostic media list. Each item is a url, a media_id,\nor a platform_attachment_id; order and mixing are preserved. Supersedes media_ids.\nCurrently ignored: X drops segment media, and Threads chaining is temporarily unavailable.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.MediaInput" } }, "media_ids": { "description": "MediaIDs attach media to this segment.\n\nDeprecated: use Media with source_type \"media_id\". Ignored when media is set.", "type": "array", "items": { "type": "string" } }, "text": { "description": "Text is the post body for this segment. Required.", "type": "string", "example": "And here's the second post in the thread." } } }, "api_endpoints.SelectProfileRequest": { "type": "object", "properties": { "page_ids": { "description": "PageIDs selects the Facebook Pages to assign to the brand (Facebook pending connections only).", "type": "array", "items": { "type": "string" } }, "platform_account_id": { "description": "PlatformAccountID selects the Google Business Profile to connect (Google\npending connections only).", "type": "string", "example": "accounts/123/locations/456" } } }, "api_endpoints.SendFeedbackRequest": { "type": "object", "properties": { "message": { "description": "Message is the feedback content.", "type": "string", "example": "It would be great to have a dark mode." }, "type": { "description": "Type is one of: bug, feature_request, general.", "type": "string", "example": "feature_request" } } }, "api_endpoints.SendMessageRequest": { "type": "object", "required": [ "account_id" ], "properties": { "account_id": { "type": "string", "example": "acc_abc123" }, "attachment_url": { "description": "AttachmentURL is a single-attachment shorthand. Ignored when attachments is\nnon-empty; its type is inferred from the URL extension.\n\nDeprecated: use Attachments instead, which supersedes it and supports one or\nmany items.", "type": "string", "example": "https://cdn.example.com/photo.jpg" }, "attachments": { "description": "Attachments sends one or more media items, each as its own message bubble.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.DMAttachmentInput" } }, "buttons": { "description": "Buttons renders a button template (1-3 buttons); uses text as the bubble body.\nOn WhatsApp every button must be type postback with a unique payload.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.MessageButton" } }, "cards": { "description": "Cards renders a generic/carousel template (up to 10 cards).", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.MessageCard" } }, "list_button": { "description": "ListButton is the label on the button that opens the list. Required with\nlist_sections, max 20 characters.", "type": "string", "example": "View options" }, "list_sections": { "description": "ListSections renders a tappable list behind a single button, for menus wider\nthan the 3 buttons a reply-button message allows (up to 10 rows in total,\nacross up to 10 sections). WhatsApp only; requires text and list_button.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.MessageListSection" } }, "message_tag": { "description": "MessageTag sends the DM outside the standard 24-hour window. Instagram\nconnected through Instagram Login only, which accepts only HUMAN_AGENT and\nextends the window to 7 days; any other value returns 400\nvalidation.invalid_message_tag. On Facebook, on Instagram connected\nthrough Facebook Login, and on every other platform, the DM is sent\nuntagged and the 24-hour window applies.", "type": "string", "example": "HUMAN_AGENT" }, "quick_replies": { "description": "QuickReplies renders up to 13 tappable chips above the keyboard; requires text.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.MessageQuickReply" } }, "reply_to_message_id": { "description": "ReplyToMessageID makes the first sent bubble a reply to a specific prior\nmessage (Meta reply_to.mid). Instagram/Facebook only.", "type": "string", "example": "m_1234567890" }, "text": { "type": "string", "example": "Thanks for your message!" } } }, "api_endpoints.SendMessageResponse": { "type": "object", "properties": { "message_id": { "description": "MessageID is the first sent message's ID; for a multi-attachment send it is\nonly the first of several IDs.\n\nDeprecated: use MessageIDs instead.", "type": "string", "example": "m_1234567890" }, "message_ids": { "description": "MessageIDs holds every sent message's ID, in send order.", "type": "array", "items": { "type": "string" }, "example": [ "m_1234567890" ] }, "success": { "type": "boolean", "example": true } } }, "api_endpoints.StaggerRequest": { "type": "object", "properties": { "max_seconds": { "description": "MaxSeconds is the longest delay between two consecutive targets. Must be at least min_seconds and at most 86400 (24 hours).", "type": "integer", "maximum": 86400, "minimum": 0, "example": 300 }, "min_seconds": { "description": "MinSeconds is the shortest delay between two consecutive targets. Must be 0 or more.", "type": "integer", "maximum": 86400, "minimum": 0, "example": 60 } } }, "api_endpoints.StartMigrationRequest": { "type": "object", "required": [ "authorisation_version", "key", "provider" ], "properties": { "authorisation_version": { "description": "Version of the authorisation text you accepted, as returned in `authorisation.version`.", "type": "string" }, "key": { "description": "API key from your account with that provider. It needs read access to profiles and accounts.", "type": "string" }, "provider": { "description": "Identifier of the provider you are moving from.", "type": "string" } } }, "api_endpoints.StorageUsageResponse": { "type": "object", "properties": { "count": { "type": "integer", "example": 12 }, "limit_bytes": { "type": "integer", "example": 104857600 }, "used_bytes": { "type": "integer", "example": 52428800 } } }, "api_endpoints.SuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } }, "api_endpoints.TargetDeleteOutcomeResponse": { "type": "object", "properties": { "account_id": { "type": "string", "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" }, "message": { "type": "string", "example": "Operation not supported for this platform" }, "outcome": { "type": "string", "enum": [ "deleted", "not_supported", "failed" ], "example": "not_supported" }, "platform": { "type": "string", "example": "tiktok" } } }, "api_endpoints.TargetRequest": { "type": "object", "properties": { "account_id": { "description": "AccountID is the connected account to publish to. Required.", "type": "string", "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" }, "board_id": { "description": "BoardID targets a specific board within a Pinterest account. Pinterest\ntargets use board_id; page_id is also accepted as an alias, but supplying\nboth is an error.", "type": "string", "example": "8828" }, "first_comment": { "description": "FirstComment overrides the post-level first comment for this target.", "type": "string" }, "media": { "description": "Media is the ordered, agnostic media list. Each item is a url, a media_id,\nor a platform_attachment_id; order and mixing are preserved. Supersedes media_ids.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.MediaInput" } }, "media_ids": { "description": "MediaIDs overrides the post-level media for this target.\n\nDeprecated: use Media with source_type \"media_id\". Ignored when media is set.", "type": "array", "items": { "type": "string" } }, "page_id": { "description": "PageID optionally targets a specific page within the account (e.g. Facebook Page).", "type": "string", "example": "sapi_page_01JRQX..." }, "platform_data": { "description": "PlatformData passes platform-specific fields (e.g. TikTok privacy settings, LinkedIn article metadata).", "type": "object", "additionalProperties": {} }, "scheduled_at": { "description": "ScheduledAt overrides the post-level schedule time for this target.", "type": "string", "example": "2026-04-01T10:00:00Z" }, "text": { "description": "Text overrides the post-level text for this target.", "type": "string", "example": "Platform-specific version of the post" }, "title": { "description": "Title overrides the post-level title for this target.", "type": "string", "example": "Custom title for LinkedIn" }, "visibility": { "description": "Visibility overrides the post-level visibility for this target.", "type": "string", "enum": [ "public", "private", "connections_only", "logged_in" ], "example": "public" } } }, "api_endpoints.TestDeliveryResponse": { "type": "object", "properties": { "delivery_id": { "type": "string" }, "response_body": { "type": "string" }, "response_duration_ms": { "type": "integer" }, "response_status_code": { "type": "integer" }, "status": { "type": "string" } } }, "api_endpoints.TestWebhookRequest": { "type": "object", "properties": { "event_type": { "type": "string" }, "payload": { "type": "array", "items": { "type": "integer" } } } }, "api_endpoints.ThreadsInsightsResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.ThreadsInsights" } } }, "api_endpoints.ThreadsProfileResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.ThreadsPublicProfile" } } }, "api_endpoints.TikTokAccountSummaryResponse": { "type": "object", "properties": { "avatar_url": { "type": "string" }, "bio_description": { "type": "string" }, "display_name": { "type": "string" }, "follower_count": { "type": "integer" }, "following_count": { "type": "integer" }, "is_verified": { "type": "boolean" }, "likes_count": { "type": "integer" }, "profile_deep_link": { "type": "string" }, "username": { "type": "string" }, "video_count": { "type": "integer" } } }, "api_endpoints.TwitterBYOKRequest": { "type": "object", "properties": { "client_id": { "type": "string" }, "client_secret": { "type": "string" } } }, "api_endpoints.TwitterByokItem": { "type": "object", "properties": { "brand_id": { "type": "string" }, "client_id_hint": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "api_endpoints.TwitterByokListResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.TwitterByokItem" } } } }, "api_endpoints.TwitterByokTestResponse": { "type": "object", "properties": { "reason": { "type": "string" }, "valid": { "type": "boolean" } } }, "api_endpoints.UnpublishRequest": { "type": "object", "properties": { "account_id": { "description": "AccountID optionally scopes the unpublish to a single platform target.", "type": "string", "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" } } }, "api_endpoints.UpdateAccountPermissionsRequest": { "type": "object", "properties": { "permissions": { "description": "Permissions replaces the account's permissions and is required. Send null to give the account every permission, including ones added later. An empty list is rejected. Removing a permission immediately deletes the comments, messages, analytics and posts not published through SocialAPI that it covers; posts published through SocialAPI are kept. Valid values: posts.read, posts.write, comments.read, comments.write, messages.read, messages.write, reviews.read, reviews.write, analytics.read.", "type": "array", "items": { "type": "string" }, "example": [ "comments.read", "comments.write" ], "nullable": true } } }, "api_endpoints.UpdateBoardRequest": { "type": "object", "properties": { "description": { "type": "string", "example": "Weeknight dinners" }, "name": { "type": "string", "example": "Recipes" }, "privacy": { "type": "string", "enum": [ "PUBLIC", "SECRET" ], "example": "PUBLIC" } } }, "api_endpoints.UpdateBrandRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Acme Corp" } } }, "api_endpoints.UpdateConversationRequest": { "type": "object", "properties": { "status": { "description": "Status must be \"active\" or \"archived\".", "type": "string", "enum": [ "active", "archived" ], "example": "archived" } } }, "api_endpoints.UpdateGoogleLocationResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPLocationDetails" }, "validated": { "description": "Validated is true when the request ran with validate_only, meaning Google\naccepted the change as valid and wrote nothing. Data is empty in that case.", "type": "boolean" } } }, "api_endpoints.UpdateKeyRequest": { "type": "object", "properties": { "brand_ids": { "description": "BrandIDs restricts the key to specific brands. Empty means all brands.", "type": "array", "items": { "type": "string" } }, "name": { "type": "string", "example": "My App" }, "scopes": { "description": "Scopes restricts the key to specific actions. Empty means full access.", "type": "array", "items": { "type": "string" }, "example": [ "posts:write", "inbox:read" ] } } }, "api_endpoints.UpdateKeyResponse": { "type": "object", "properties": { "brand_ids": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" }, "example": [ "posts:write", "inbox:read" ] } } }, "api_endpoints.UpdatePageRequest": { "type": "object", "properties": { "is_active": { "type": "boolean" }, "is_default": { "type": "boolean" } } }, "api_endpoints.UpdatePostRequest": { "type": "object", "properties": { "first_comment": { "description": "FirstComment replaces the auto-first-comment.", "type": "string" }, "hidden": { "description": "Hidden archives the post from default list views when true.", "type": "boolean", "example": false }, "media": { "description": "Media is the ordered, agnostic media list. Each item is a url, a media_id,\nor a platform_attachment_id; order and mixing are preserved. Supersedes media_ids.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.MediaInput" } }, "media_ids": { "description": "MediaIDs replaces the attached media files.\n\nDeprecated: use Media with source_type \"media_id\". Ignored when media is set.", "type": "array", "items": { "type": "string" } }, "platform_data": { "description": "PlatformData passes platform-specific fields keyed by platform name (e.g. {\"instagram\": {\"content_type\": \"feed\"}}). Folded into each matching target; a target's own platform_data wins on conflicts.", "type": "object", "additionalProperties": {} }, "queue_id": { "description": "QueueID moves the post to another Queue, which gives it that Queue's earliest free time and frees its old one. Send null to take the post out of its Queue and keep its time. Send \"default\" for the Brand's default Queue.", "type": "string", "example": "que_01J9Z8Y7X6W5V4T3S2R1Q0P9N8" }, "scheduled_at": { "description": "ScheduledAt changes the scheduled publication time (RFC3339).", "type": "string", "example": "2026-04-02T14:00:00Z" }, "segments": { "description": "Segments are continuation posts that publish as a native thread on X. Threads chaining is temporarily unavailable.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.SegmentRequest" } }, "skip_validation": { "description": "SkipValidation bypasses pre-publish validation. The post is scheduled/published as-is and may fail at the platform.", "type": "boolean", "example": false }, "targets": { "description": "Targets replaces or updates per-platform target configuration.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.TargetRequest" } }, "text": { "description": "Text replaces the post body. Only for draft/scheduled/failed posts.", "type": "string", "example": "Updated post content" }, "title": { "description": "Title replaces the post title.", "type": "string", "example": "Updated Title" }, "visibility": { "description": "Visibility changes who can see the post.", "type": "string", "enum": [ "public", "private", "connections_only", "logged_in" ], "example": "public" } } }, "api_endpoints.UpdateQueueResponse": { "type": "object", "properties": { "active": { "description": "False when the Queue is paused: no new post can join it.", "type": "boolean", "example": true }, "brand_id": { "description": "ID of the Brand the Queue belongs to.", "type": "string" }, "created_at": { "description": "When the Queue was created.", "type": "string" }, "id": { "description": "Queue ID.", "type": "string", "example": "que_01J9Z8Y7X6W5V4T3S2R1Q0P9N8" }, "is_default": { "description": "True for the Brand's default Queue, the one queue_id \"default\" refers to.", "type": "boolean", "example": true }, "name": { "description": "Queue name.", "type": "string", "example": "Evenings" }, "reshuffled_count": { "description": "Number of queued posts moved to the new times. Present only when the request sent reshuffle_existing: true.", "type": "integer" }, "slots": { "description": "Weekly posting times, sorted by day (Monday first) then time.", "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.Slot" } }, "timezone": { "description": "IANA timezone the slots are expressed in.", "type": "string", "example": "Europe/Paris" }, "updated_at": { "description": "When the Queue was last changed.", "type": "string" } } }, "api_endpoints.UpdateWebhookRequest": { "type": "object", "properties": { "events": { "description": "Events replaces the subscribed event types.", "type": "array", "items": { "type": "string", "enum": [ "post.scheduled", "post.published", "post.failed", "post.partial", "post.updated", "post.deleted", "post.unpublished", "post.retried", "comment.received", "dm.received", "dm.sent", "dm.referral", "dm.postback", "dm.deleted", "dm.status.sent", "dm.status.delivered", "dm.status.read", "dm.status.failed", "review.received", "review.updated", "mention.received", "account.connected", "account.disconnected", "account.updated", "page.removed" ] } }, "is_active": { "description": "IsActive enables or disables delivery to this endpoint.", "type": "boolean", "example": true }, "url": { "description": "URL changes the webhook delivery endpoint. Must be HTTPS.", "type": "string", "example": "https://example.com/webhooks/socialapi" } } }, "api_endpoints.UpdateYouTubeVideoRequest": { "type": "object", "properties": { "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "title": { "type": "string" }, "visibility": { "description": "public | unlisted | private", "type": "string" } } }, "api_endpoints.UsageLimitsResponse": { "type": "object", "additionalProperties": { "type": "integer" } }, "api_endpoints.UsageResponse": { "type": "object", "properties": { "brands_limit": { "type": "integer", "example": 10 }, "brands_used": { "type": "integer", "example": 3 }, "interactions_limit": { "type": "integer", "example": 5000 }, "interactions_used": { "type": "integer", "example": 1200 }, "page_allowance": { "type": "integer", "example": 5 }, "page_billing_exempt": { "type": "boolean", "example": false }, "period_end": { "type": "string", "example": "2026-03-15T00:00:00Z" }, "period_start": { "type": "string", "example": "2026-02-15T00:00:00Z" }, "posts_limit": { "type": "integer", "example": 200 }, "posts_used": { "type": "integer", "example": 42 }, "profile_units_limit": { "type": "integer", "example": 10 }, "profile_units_used": { "type": "integer", "example": 4 } } }, "api_endpoints.UserMeResponse": { "type": "object", "properties": { "allowed_platforms": { "type": "array", "items": { "type": "string" }, "example": [ "instagram", "facebook" ] }, "avatar_url": { "type": "string", "example": "https://example.com/avatar.jpg" }, "beta_tester": { "type": "boolean", "example": false }, "billing_block_reason": { "description": "BillingBlockReason is why access is paused, empty when it is not.\n\"past_due\": a payment failed, and settling it restores access.\n\"ban\": the account was suspended for a Terms of Service violation.\nPaying does not lift it, and every route except this one returns\n403 auth.suspended. Contact support to appeal.", "type": "string", "example": "past_due" }, "billing_blocked": { "description": "BillingBlocked is true when API access and webhook delivery are paused.\nRead BillingBlockReason to tell why and whether paying lifts it.", "type": "boolean", "example": false }, "billing_blocked_at": { "description": "BillingBlockedAt is when the block began, or null when not blocked.", "type": "string" }, "billing_currency": { "description": "BillingCurrency is the currency your subscription is billed in: \"usd\"\nor \"eur\". A subscription never changes currency, so plan changes are\npriced in it. Kept after a cancellation; \"\" when you never subscribed.", "type": "string", "example": "usd" }, "email": { "type": "string", "example": "user@example.com" }, "experiment_enrolled": { "description": "ExperimentEnrolled is true only when ExperimentVariant was assigned by\nthe experiment itself. False means the \"control\" above is a fallback\n(not enrolled, flag off, or evaluation failed) and must not be recorded\nas the caller's arm.", "type": "boolean", "example": false }, "experiment_variant": { "description": "ExperimentVariant is the caller's variant for staged feature rollouts:\n\"control\" or \"treatment\". \"control\" unless the caller is enrolled.", "type": "string", "example": "control" }, "facebook_page_selection": { "description": "FacebookPageSelection, when true, makes a Facebook connection (and an\nInstagram connection through Facebook Login) end with\nstatus=selection_required so you choose the Pages. Read-only.", "type": "boolean", "example": false }, "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "job_role": { "description": "JobRole is what best describes the user, as answered during\nonboarding. Null until answered.", "type": "string", "example": "Founder / CEO" }, "lock_accounts_to_brand": { "description": "LockAccountsToBrand, when true, rejects connecting a social account that is\nalready connected to another of your brands (409 account.already_linked)\ninstead of moving it. Default false.", "type": "boolean", "example": false }, "onboarding": { "type": "boolean", "example": true }, "plan": { "type": "string", "example": "free" }, "role": { "description": "Role is the caller's team role: \"admin\", \"developer\", or \"\" for the\naccount Owner, who holds no Role. An API key and an OAuth token both\nread \"\".", "type": "string", "example": "admin" }, "signup_metadata": { "description": "SignupMetadata holds open-ended answers recorded at signup, such as\nreferral_source and search_query. An empty object until answered.", "type": "object", "additionalProperties": {} }, "use_case": { "type": "string", "example": "Managing clients' accounts (agency)" } } }, "api_endpoints.ValidatePostRequest": { "type": "object", "properties": { "account_ids": { "description": "AccountIDs lists connected account IDs - their platforms are resolved automatically.", "type": "array", "items": { "type": "string" } }, "media": { "description": "Media is the ordered, agnostic media list. Each item is a url, a media_id,\nor a platform_attachment_id; order and mixing are preserved. Supersedes media_ids.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.MediaInput" } }, "media_ids": { "description": "MediaIDs are media file IDs to validate (checks count and type limits).\n\nDeprecated: use Media with source_type \"media_id\". Ignored when media is set.", "type": "array", "items": { "type": "string" } }, "platform_data": { "description": "PlatformData passes platform-specific fields keyed by platform name (e.g. {\"instagram\": {\"content_type\": \"feed\"}}). Folded into each matching target; a target's own platform_data wins on conflicts.", "type": "object", "additionalProperties": {} }, "platforms": { "description": "Platforms lists platform names to validate against (e.g. [\"instagram\", \"linkedin\"]).", "type": "array", "items": { "type": "string" } }, "scheduled_at": { "description": "ScheduledAt validates the schedule time (must be in the future, within platform limits).", "type": "string", "example": "2026-04-01T10:00:00Z" }, "segments": { "description": "Segments are continuation posts that publish as a native thread on X. Threads chaining is temporarily unavailable.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.SegmentRequest" } }, "targets": { "description": "Targets validates per-target overrides if provided.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.TargetRequest" } }, "text": { "description": "Text is the post content to validate against platform constraints.", "type": "string", "example": "Check out our new product! #launch" } } }, "api_endpoints.ValidatePostResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.ValidationIssue" } }, "valid": { "type": "boolean" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.ValidationIssue" } } } }, "api_endpoints.ValidationIssue": { "type": "object", "properties": { "field": { "type": "string", "example": "text" }, "message": { "type": "string", "example": "exceeds 2200 character limit (2350/2200)" }, "platform": { "type": "string", "example": "instagram" }, "segment_index": { "description": "SegmentIndex pins the issue to a continuation segment (0-based); nil for the main post.", "type": "integer", "example": 0 }, "target": { "type": "string", "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" } } }, "api_endpoints.WebhookDetailResponse": { "type": "object", "properties": { "created_at": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "secret_hint": { "type": "string" }, "stats": { "$ref": "#/components/schemas/social-api_ai_core_api_service.WebhookStats" }, "url": { "type": "string" } } }, "api_endpoints.WebhookEndpointItem": { "type": "object", "properties": { "created_at": { "type": "string", "example": "2026-03-14T09:00:00Z" }, "events": { "type": "array", "items": { "type": "string" }, "example": [ "comment.received", "dm.received" ] }, "id": { "type": "string", "example": "wh_01HZ9X3Q4R5M6N7P8V2K0W1J" }, "is_active": { "type": "boolean", "example": true }, "url": { "type": "string", "example": "https://example.com/webhooks/socialapi" } } }, "api_endpoints.WebhooksListResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.WebhookEndpointItem" } } } }, "api_endpoints.WhatsAppBusinessProfile": { "type": "object", "properties": { "about": { "description": "About is the profile tagline shown in the chat header.", "type": "string", "example": "Reach us 9-5 weekdays." }, "address": { "description": "Address is the business address (max 256 characters).", "type": "string", "example": "1 Hacker Way, Menlo Park, CA" }, "description": { "description": "Description is the business description.", "type": "string", "example": "Acme Corp customer support." }, "email": { "description": "Email is the contact email.", "type": "string", "example": "support@acme.com" }, "messaging_product": { "description": "MessagingProduct is always \"whatsapp\".", "type": "string", "example": "whatsapp" }, "profile_picture_url": { "description": "ProfilePictureURL is the public URL of the current profile picture (read-only; use profile_picture_handle to update).", "type": "string", "example": "https://cdn.example.com/logo.png" }, "vertical": { "description": "Vertical is the business category.", "type": "string", "enum": [ "OTHER", "AUTO", "BEAUTY", "APPAREL", "EDU", "ENTERTAIN", "EVENT_PLAN", "FINANCE", "GROCERY", "GOVT", "HOTEL", "HEALTH", "NONPROFIT", "PROF_SERVICES", "RETAIL", "TRAVEL", "RESTAURANT", "ALCOHOL" ], "example": "RETAIL" }, "websites": { "description": "Websites lists the business websites (max 2).", "type": "array", "items": { "type": "string" }, "example": [ "https://acme.com" ] } } }, "api_endpoints.WhatsAppContact": { "type": "object", "properties": { "input": { "type": "string", "example": "15551234567" }, "wa_id": { "type": "string", "example": "15551234567" } } }, "api_endpoints.WhatsAppCreateTemplateRequest": { "type": "object", "properties": { "category": { "description": "Category is the message category. Marketing intent in a UTILITY template triggers automatic rejection.", "type": "string", "enum": [ "MARKETING", "UTILITY", "AUTHENTICATION" ], "example": "UTILITY" }, "components": { "description": "Components define the template body, optional header, optional footer, and optional buttons.\nAt minimum one BODY component is required.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.WhatsAppTemplateComponentDef" } }, "language": { "description": "Language is the BCP-47 language code (e.g. en_US, fr_FR, pt_BR).", "type": "string", "example": "en_US" }, "name": { "description": "Name is the template identifier. Lowercase letters, digits, underscores only; no spaces.", "type": "string", "example": "order_confirmation" } } }, "api_endpoints.WhatsAppCursors": { "type": "object", "properties": { "after": { "type": "string", "example": "QVFIUjN..." }, "before": { "type": "string", "example": "QVFIUjJ..." } } }, "api_endpoints.WhatsAppEditTemplateRequest": { "type": "object", "properties": { "components": { "description": "Components replaces the template's components.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.WhatsAppTemplateComponentDef" } } } }, "api_endpoints.WhatsAppMessageRef": { "type": "object", "properties": { "id": { "type": "string", "example": "wamid.HBgLMTU1NTEyMzQ1NjcVAgARGBI..." }, "message_status": { "type": "string", "example": "accepted" } } }, "api_endpoints.WhatsAppRegisterRequest": { "type": "object", "properties": { "pin": { "description": "PIN is the 6-digit two-step verification PIN to set on the phone number.\nThis PIN is required for future re-registration and must be stored securely.", "type": "string", "example": "123456" } } }, "api_endpoints.WhatsAppRequestCodeRequest": { "type": "object", "properties": { "language": { "description": "Language is the BCP-47 locale used for the verification message (e.g. en_US, fr_FR).", "type": "string", "example": "en_US" }, "method": { "description": "Method is the verification channel. WhatsApp Business API requires SMS or VOICE.", "type": "string", "enum": [ "SMS", "VOICE" ], "example": "SMS" } } }, "api_endpoints.WhatsAppSendTemplateRequest": { "type": "object", "properties": { "components": { "description": "Components carries header/body/button variable substitutions.\nEach component matches WhatsApp's template component schema (type + parameters).", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.WhatsAppTemplateComponent" } }, "language": { "description": "Language is the BCP-47 code matching the template's approved language (e.g. en_US, fr_FR).", "type": "string", "example": "en_US" }, "template_name": { "description": "TemplateName is the approved template name to send.", "type": "string", "example": "order_confirmation" }, "to": { "description": "To is the recipient phone number in E.164 format without the leading \"+\".", "type": "string", "example": "15551234567" } } }, "api_endpoints.WhatsAppSendTemplateResponse": { "type": "object", "properties": { "contacts": { "description": "Contacts maps the input phone number to its canonical WhatsApp ID.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.WhatsAppContact" } }, "message_id": { "description": "MessageID is the SocialAPI message ID for the send, matching the \"id\"\nfield on the dm.status.* webhooks for this message. Empty when WhatsApp\nreturned no wamid or no canonical wa_id, since an ID built from half the\npair would collide across conversations.", "type": "string", "example": "sapi_dm_TT974YVQH4RAHNN2HY2DJSNY9111D7LMTP1XXPCVQVL" }, "messages": { "description": "Messages contains one entry per delivered message, with its platform ID.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.WhatsAppMessageRef" } }, "messaging_product": { "description": "MessagingProduct is always \"whatsapp\".", "type": "string", "example": "whatsapp" } } }, "api_endpoints.WhatsAppTemplateButtonDef": { "type": "object", "properties": { "example": { "description": "Example carries the button's sample value(s), forwarded verbatim: a dynamic\nURL example ([\"https://...\"]) or a COPY_CODE sample (\"250FF\").", "type": "object" }, "phone_number": { "description": "PhoneNumber is required when Type is PHONE_NUMBER. E.164 format with leading \"+\".", "type": "string", "example": "+15551234567" }, "text": { "description": "Text is the button label. Not required for COPY_CODE (WhatsApp auto-labels it).", "type": "string", "example": "Visit" }, "type": { "description": "Type is the button kind.", "type": "string", "enum": [ "QUICK_REPLY", "URL", "PHONE_NUMBER", "COPY_CODE" ], "example": "URL" }, "url": { "description": "URL is required when Type is URL. May contain a single {{1}} placeholder.", "type": "string", "example": "https://example.com/{{1}}" } } }, "api_endpoints.WhatsAppTemplateComponent": { "type": "object", "properties": { "parameters": { "description": "Parameters lists variable substitutions for this component.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.WhatsAppTemplateParameter" } }, "type": { "description": "Type is the component slot: header, body, or button.", "type": "string", "enum": [ "header", "body", "button" ], "example": "body" } } }, "api_endpoints.WhatsAppTemplateComponentDef": { "type": "object", "properties": { "buttons": { "description": "Buttons populate a BUTTONS component (one of QUICK_REPLY, URL, PHONE_NUMBER, COPY_CODE).", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.WhatsAppTemplateButtonDef" } }, "example": { "description": "Example carries WhatsApp's sample values, forwarded verbatim. For a TEXT\nBODY/HEADER it is {\"body_text\":[[\"v1\",\"v2\"]]} / {\"header_text\":[\"v1\"]}; for\na media HEADER it is {\"header_handle\":[\"\"]}. Required for\napproval when the component contains variables.", "type": "object" }, "format": { "description": "Format is required for HEADER components.", "type": "string", "enum": [ "TEXT", "IMAGE", "VIDEO", "DOCUMENT" ], "example": "TEXT" }, "text": { "description": "Text is the literal text for HEADER (when Format is TEXT), BODY, or FOOTER components.\nMay contain 1-indexed placeholders such as {{1}}, {{2}}.", "type": "string", "example": "Hello {{1}}, your order {{2}} is confirmed." }, "type": { "description": "Type is the component slot.", "type": "string", "enum": [ "HEADER", "BODY", "FOOTER", "BUTTONS" ], "example": "BODY" } } }, "api_endpoints.WhatsAppTemplateCreateResponse": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "AUTHENTICATION", "MARKETING", "UTILITY" ], "example": "UTILITY" }, "id": { "type": "string", "example": "1234567890123456" }, "status": { "type": "string", "enum": [ "APPROVED", "PENDING", "REJECTED" ], "example": "PENDING" } } }, "api_endpoints.WhatsAppTemplateInfo": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "AUTHENTICATION", "MARKETING", "UTILITY" ], "example": "UTILITY" }, "components": { "description": "Components is the raw WhatsApp template component definition." }, "id": { "type": "string", "example": "1234567890123456" }, "language": { "type": "string", "example": "en_US" }, "name": { "type": "string", "example": "order_confirmation" }, "status": { "type": "string", "enum": [ "APPROVED", "PENDING", "REJECTED", "PAUSED", "DISABLED" ], "example": "APPROVED" } } }, "api_endpoints.WhatsAppTemplateListPaging": { "type": "object", "properties": { "cursors": { "$ref": "#/components/schemas/api_endpoints.WhatsAppCursors" }, "next": { "type": "string", "example": "https://graph.facebook.com/..." } } }, "api_endpoints.WhatsAppTemplateListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.WhatsAppTemplateInfo" } }, "paging": { "$ref": "#/components/schemas/api_endpoints.WhatsAppTemplateListPaging" } } }, "api_endpoints.WhatsAppTemplateParameter": { "type": "object", "properties": { "text": { "description": "Text is the substituted value when Type is \"text\".", "type": "string", "example": "John" }, "type": { "description": "Type is the parameter type. Only \"text\" is supported today.", "type": "string", "enum": [ "text" ], "example": "text" } } }, "api_endpoints.WhatsAppTemplateValidationIssue": { "type": "object", "properties": { "component_index": { "description": "ComponentIndex pins the issue to a components[] entry (0-based); nil for\ntop-level fields such as name, category, or language.", "type": "integer", "example": 0 }, "field": { "description": "Field is the offending request field (e.g. \"name\", \"components.format\",\n\"components.buttons[0].url\").", "type": "string", "example": "name" }, "message": { "description": "Message is a developer-facing description of the problem.", "type": "string", "example": "name must contain only lowercase letters, digits, and underscores (no spaces or capitals)" } } }, "api_endpoints.WhatsAppUpdateBusinessProfileRequest": { "type": "object", "properties": { "about": { "description": "About is the profile tagline (max 139 characters).", "type": "string", "example": "Reach us 9-5 weekdays." }, "address": { "description": "Address is the business address (max 256 characters).", "type": "string", "example": "1 Hacker Way, Menlo Park, CA" }, "description": { "description": "Description is the business description.", "type": "string", "example": "Acme Corp customer support." }, "email": { "description": "Email is the contact email.", "type": "string", "example": "support@acme.com" }, "profile_picture_handle": { "description": "ProfilePictureHandle is a handle returned by the Resumable Upload API.\nUse this to change the profile picture; the picture URL is read-only.", "type": "string", "example": "4::aW1hZ2UvanBlZw==" }, "vertical": { "description": "Vertical is the business category.", "type": "string", "enum": [ "OTHER", "AUTO", "BEAUTY", "APPAREL", "EDU", "ENTERTAIN", "EVENT_PLAN", "FINANCE", "GROCERY", "GOVT", "HOTEL", "HEALTH", "NONPROFIT", "PROF_SERVICES", "RETAIL", "TRAVEL", "RESTAURANT", "ALCOHOL" ], "example": "RETAIL" }, "websites": { "description": "Websites lists the business websites (max 2).", "type": "array", "items": { "type": "string" }, "example": [ "https://acme.com" ] } } }, "api_endpoints.WhatsAppValidateTemplateResponse": { "type": "object", "properties": { "errors": { "description": "Errors are hard violations WhatsApp would reject at submission.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.WhatsAppTemplateValidationIssue" } }, "valid": { "description": "Valid is true when there are no errors (warnings do not affect validity).", "type": "boolean" }, "warnings": { "description": "Warnings are best-practice issues or items that cannot be fully verified offline.", "type": "array", "items": { "$ref": "#/components/schemas/api_endpoints.WhatsAppTemplateValidationIssue" } } } }, "api_endpoints.WhatsAppVerifyCodeRequest": { "type": "object", "properties": { "code": { "description": "Code is the 6-digit verification code received via SMS or voice.", "type": "string", "example": "123456" } } }, "api_endpoints.YouTubeChannelSummaryResponse": { "type": "object", "properties": { "handle": { "type": "string" }, "subscriber_count": { "type": "integer" }, "thumbnail_url": { "type": "string" }, "title": { "type": "string" }, "video_count": { "type": "integer" }, "view_count": { "type": "integer" } } }, "social-api_ai_core_api_connectors_base.Account": { "type": "object", "properties": { "bio": { "description": "[optional] Profile biography or description", "type": "string" }, "brand_id": { "description": "[always] SocialAPI brand ID this account belongs to", "type": "string" }, "connection_type": { "description": "[optional] LinkedIn only: \"profile\" for a member profile, \"organization\" for a company Page. Absent for every other account", "type": "string", "enum": [ "profile", "organization" ], "example": "profile" }, "effective_permissions": { "description": "[always] The permissions this account can use right now: the requested permissions the platform supports, minus any the platform did not grant or has since refused. Uses the same names as permissions. An empty list when none apply", "type": "array", "items": { "type": "string" } }, "id": { "description": "[always]", "type": "string", "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" }, "login_id": { "description": "[optional] Login id shared by accounts connected in the same authorization (facebook, google, linkedin)", "type": "string" }, "metadata": { "description": "[optional] Platform-specific keys for this account", "type": "object", "additionalProperties": {} }, "name": { "description": "[always] Display name of the account or page", "type": "string", "example": "Acme Corp" }, "page_name": { "description": "[optional] Name of the single active page bound to this account; set only when exactly one page is active (e.g. facebook), so clients can label the tile with the page instead of the login identity", "type": "string" }, "permissions": { "description": "[always] The permissions requested for this account: one or more of posts.read, posts.write, comments.read, comments.write, messages.read, messages.write, reviews.read, reviews.write, analytics.read. null means every permission, including ones added later", "type": "array", "items": { "type": "string" } }, "platform": { "description": "[always]", "type": "string", "example": "instagram" }, "profile_picture_url": { "description": "[optional] Profile picture URL", "type": "string" }, "reconnect_reason": { "description": "[optional] Human-readable reason; only set when Status == \"reconnect_required\"", "type": "string" }, "status": { "description": "[always] One of: active, reconnect_required", "type": "string", "example": "active" }, "username": { "description": "[always] May equal Name on platforms without a distinct handle", "type": "string", "example": "acmecorp" } } }, "social-api_ai_core_api_connectors_base.Author": { "type": "object", "properties": { "avatar_url": { "type": "string", "example": "https://example.com/avatar.jpg" }, "id": { "type": "string", "example": "17841405793187218" }, "name": { "type": "string", "example": "Jane Smith" }, "username": { "type": "string", "example": "janesmith" } } }, "social-api_ai_core_api_connectors_base.Collaborator": { "type": "object", "properties": { "id": { "type": "string", "example": "17841405793187218" }, "status": { "type": "string", "example": "pending" }, "username": { "type": "string", "example": "janesmith" } } }, "social-api_ai_core_api_connectors_base.Content": { "type": "object", "properties": { "media": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.Media" } }, "text": { "type": "string", "example": "Love this product! Really glad I found it." } } }, "social-api_ai_core_api_connectors_base.DailyInsight": { "type": "object", "properties": { "date": { "description": "Day in YYYY-MM-DD.", "type": "string", "example": "2026-09-27" }, "followers": { "type": "integer" }, "interactions": { "type": "integer" }, "reach": { "type": "integer" }, "views": { "type": "integer" } } }, "social-api_ai_core_api_connectors_base.GBPAddressUpdate": { "type": "object", "properties": { "address_lines": { "type": "array", "items": { "type": "string" } }, "administrative_area": { "type": "string" }, "locality": { "type": "string", "example": "Paris" }, "organization": { "type": "string" }, "postal_code": { "type": "string", "example": "75001" }, "region_code": { "type": "string", "example": "FR" }, "sorting_code": { "type": "string" }, "sublocality": { "type": "string" } } }, "social-api_ai_core_api_connectors_base.GBPCategoriesUpdate": { "type": "object", "properties": { "additional_categories": { "description": "AdditionalCategories replaces the whole list: Google has no way to add or\nremove a single category, so a partial list drops the rest.", "type": "array", "items": { "type": "string" } }, "primary_category": { "type": "string", "example": "categories/gcid:pizza_restaurant" } } }, "social-api_ai_core_api_connectors_base.GBPCategory": { "type": "object", "properties": { "display_name": { "type": "string", "example": "Pizza restaurant" }, "name": { "type": "string", "example": "categories/gcid:pizza_restaurant" } } }, "social-api_ai_core_api_connectors_base.GBPFreeFormService": { "type": "object", "properties": { "category": { "type": "string" }, "label": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPLabel" } } }, "social-api_ai_core_api_connectors_base.GBPHoursUpdate": { "type": "object", "properties": { "periods": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPTimePeriod" } } } }, "social-api_ai_core_api_connectors_base.GBPInsights": { "type": "object", "properties": { "end_date": { "type": "string" }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPMetricSeries" } }, "start_date": { "type": "string" } } }, "social-api_ai_core_api_connectors_base.GBPInsightsPoint": { "type": "object", "properties": { "date": { "type": "string" }, "value": { "type": "integer" } } }, "social-api_ai_core_api_connectors_base.GBPKeywordsPage": { "type": "object", "properties": { "keywords": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPSearchKeyword" } }, "next_cursor": { "type": "string" } } }, "social-api_ai_core_api_connectors_base.GBPLabel": { "type": "object", "properties": { "description": { "type": "string" }, "display_name": { "type": "string", "example": "Emergency unlock" }, "language_code": { "type": "string", "example": "en" } } }, "social-api_ai_core_api_connectors_base.GBPLatLng": { "type": "object", "properties": { "latitude": { "type": "number", "example": 48.8566 }, "longitude": { "type": "number", "example": 2.3522 } } }, "social-api_ai_core_api_connectors_base.GBPLocationDetails": { "type": "object", "properties": { "ad_phone": { "description": "AdPhone is the alternate number shown on Google Ads extensions.", "type": "string" }, "additional_categories": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPCategory" } }, "additional_phones": { "type": "array", "items": { "type": "string" } }, "can_delete": { "description": "CanDelete reports whether the location can be deleted. Absent when Google\nsaid nothing.", "type": "boolean" }, "can_have_business_calls": { "type": "boolean" }, "can_have_food_menus": { "type": "boolean" }, "can_modify_service_list": { "type": "boolean" }, "can_operate_health_data": { "type": "boolean" }, "can_operate_local_post": { "type": "boolean" }, "can_operate_lodging_data": { "type": "boolean" }, "can_reopen": { "description": "CanReopen is set on a temporarily closed location that can be reopened.", "type": "boolean" }, "duplicate_location": { "description": "DuplicateLocation names the location this one was flagged a duplicate of.", "type": "string" }, "has_google_updated": { "type": "boolean" }, "has_pending_edits": { "type": "boolean" }, "has_voice_of_merchant": { "description": "HasVoiceOfMerchant reports whether the merchant controls the profile.\nWhen false, posting and replying fail until they resolve it in Google\nBusiness Profile. Absent when Google said nothing.", "type": "boolean" }, "is_particularly_personal_place": { "type": "boolean" }, "labels": { "type": "array", "items": { "type": "string" } }, "language_code": { "type": "string", "example": "en" }, "latlng": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPLatLng" }, "maps_uri": { "description": "MapsURI is the location's Google Maps page.", "type": "string", "example": "https://maps.google.com/?cid=123" }, "more_hours": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPMoreHours" } }, "new_review_uri": { "description": "NewReviewURI is the short link that opens the review form for this\nlocation, for review-request campaigns.", "type": "string", "example": "https://g.page/r/abc/review" }, "open_status": { "description": "OpenStatus is OPEN, CLOSED_PERMANENTLY or CLOSED_TEMPORARILY.", "type": "string", "example": "OPEN" }, "opening_date": { "description": "OpeningDate is set on a location that has not opened yet.", "type": "string", "example": "2026-09-01" }, "place_id": { "description": "PlaceID is the standard Google Places identifier, so a location can be\njoined to Places, Maps and Geocoding results.", "type": "string", "example": "ChIJabc" }, "primary_category": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPCategory" }, "primary_phone": { "type": "string", "example": "+33 1 23 45 67 89" }, "regular_hours": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPTimePeriod" } }, "relationship_data": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPRelationshipData" }, "service_area": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPServiceArea" }, "service_items": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPServiceItem" } }, "special_hours": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPSpecialHourPeriod" } }, "store_code": { "type": "string", "example": "JP-01" }, "storefront_address": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPPostalAddress" }, "website_uri": { "type": "string", "example": "https://joes.example" } } }, "social-api_ai_core_api_connectors_base.GBPLocationUpdate": { "type": "object", "properties": { "ad_phone": { "description": "AdPhone is the alternate number shown on Google Ads extensions.", "type": "string" }, "categories": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPCategoriesUpdate" }, "description": { "type": "string", "example": "Wood-fired pizza since 1998" }, "labels": { "type": "array", "items": { "type": "string" } }, "latlng": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPLatLng" }, "more_hours": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPMoreHours" } }, "open_status": { "description": "OpenStatus is OPEN, CLOSED_PERMANENTLY or CLOSED_TEMPORARILY.", "type": "string", "example": "OPEN" }, "phone_numbers": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPPhoneNumbersUpdate" }, "regular_hours": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPHoursUpdate" }, "service_area": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPServiceAreaUpdate" }, "special_hours": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPSpecialHoursUpdate" }, "store_code": { "type": "string", "example": "JP-01" }, "storefront_address": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPAddressUpdate" }, "title": { "type": "string", "example": "Joe's Pizza (Downtown)" }, "website_uri": { "type": "string", "example": "https://joes.example" } } }, "social-api_ai_core_api_connectors_base.GBPMetricSeries": { "type": "object", "properties": { "metric": { "type": "string" }, "points": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPInsightsPoint" } }, "total": { "type": "integer" } } }, "social-api_ai_core_api_connectors_base.GBPMoney": { "type": "object", "properties": { "currency_code": { "type": "string", "example": "EUR" }, "nanos": { "description": "Nanos is the fractional part of the price, in billionths. Zero is a real\nvalue, not an absent one.", "type": "integer" }, "units": { "type": "string", "example": "80" } } }, "social-api_ai_core_api_connectors_base.GBPMoreHours": { "type": "object", "properties": { "hours_type_id": { "type": "string", "example": "DRIVE_THROUGH" }, "periods": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPTimePeriod" } } } }, "social-api_ai_core_api_connectors_base.GBPPhoneNumbersUpdate": { "type": "object", "properties": { "additional_phones": { "description": "AdditionalPhones replaces the whole list; an empty list clears it.", "type": "array", "items": { "type": "string" } }, "primary_phone": { "type": "string", "example": "+33 1 23 45 67 89" } } }, "social-api_ai_core_api_connectors_base.GBPPlaceInfo": { "type": "object", "properties": { "place_id": { "type": "string" }, "place_name": { "type": "string", "example": "Paris" } } }, "social-api_ai_core_api_connectors_base.GBPPostalAddress": { "type": "object", "properties": { "address_lines": { "type": "array", "items": { "type": "string" } }, "administrative_area": { "type": "string", "example": "Île-de-France" }, "locality": { "type": "string", "example": "Paris" }, "organization": { "type": "string" }, "postal_code": { "type": "string", "example": "75001" }, "region_code": { "type": "string", "example": "FR" }, "sorting_code": { "type": "string" }, "sublocality": { "type": "string" } } }, "social-api_ai_core_api_connectors_base.GBPRelationshipData": { "type": "object", "properties": { "children_locations": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPRelevantLocation" } }, "parent_chain": { "type": "string" }, "parent_location": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPRelevantLocation" } } }, "social-api_ai_core_api_connectors_base.GBPRelevantLocation": { "type": "object", "properties": { "place_id": { "type": "string" }, "relation_type": { "type": "string", "example": "DEPARTMENT_OF" } } }, "social-api_ai_core_api_connectors_base.GBPSearchKeyword": { "type": "object", "properties": { "is_threshold": { "type": "boolean" }, "keyword": { "type": "string" }, "threshold": { "type": "integer" }, "value": { "type": "integer" } } }, "social-api_ai_core_api_connectors_base.GBPServiceArea": { "type": "object", "properties": { "business_type": { "description": "BusinessType is CUSTOMER_LOCATION_ONLY or CUSTOMER_AND_BUSINESS_LOCATION.", "type": "string", "example": "CUSTOMER_LOCATION_ONLY" }, "places": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPPlaceInfo" } }, "region_code": { "type": "string", "example": "FR" } } }, "social-api_ai_core_api_connectors_base.GBPServiceAreaUpdate": { "type": "object", "properties": { "business_type": { "description": "BusinessType is CUSTOMER_LOCATION_ONLY or CUSTOMER_AND_BUSINESS_LOCATION.", "type": "string", "example": "CUSTOMER_LOCATION_ONLY" }, "place_ids": { "description": "PlaceIDs replaces the covered areas, as Google place ids.", "type": "array", "items": { "type": "string" } } } }, "social-api_ai_core_api_connectors_base.GBPServiceItem": { "type": "object", "properties": { "free_form_service_item": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPFreeFormService" }, "price": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPMoney" }, "structured_service_item": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPStructuredService" } } }, "social-api_ai_core_api_connectors_base.GBPSpecialHourPeriod": { "type": "object", "properties": { "close_time": { "type": "string" }, "closed": { "description": "Closed marks the location shut for the whole period, in which case the\ntimes are absent. Absent when Google said nothing.", "type": "boolean" }, "end_date": { "type": "string", "example": "2026-12-25" }, "open_time": { "type": "string" }, "start_date": { "type": "string", "example": "2026-12-25" } } }, "social-api_ai_core_api_connectors_base.GBPSpecialHoursUpdate": { "type": "object", "properties": { "periods": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.GBPSpecialHourPeriod" } } } }, "social-api_ai_core_api_connectors_base.GBPStructuredService": { "type": "object", "properties": { "description": { "type": "string" }, "service_type_id": { "type": "string" } } }, "social-api_ai_core_api_connectors_base.GBPTimePeriod": { "type": "object", "properties": { "close_day": { "type": "string", "example": "MONDAY" }, "close_time": { "type": "string", "example": "17:30" }, "open_day": { "type": "string", "example": "MONDAY" }, "open_time": { "type": "string", "example": "09:00" } } }, "social-api_ai_core_api_connectors_base.Interaction": { "type": "object", "properties": { "account_id": { "description": "[always]", "type": "string", "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" }, "author": { "description": "[always] Fields are populated only when the source platform exposes them; absent fields are omitted from JSON", "allOf": [ { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.Author" } ] }, "content": { "description": "[always] Text may be empty for attachment-only or referral interactions", "allOf": [ { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.Content" } ] }, "conversation_id": { "description": "[optional] SocialAPI conversation ID; set on Facebook, Instagram, WhatsApp and Telegram DMs that belong to a conversation", "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "id": { "description": "[always] SocialAPI interaction ID (sapi_cmt_/sapi_rev_/sapi_dm_/sapi_mnt_ prefix)", "type": "string", "example": "sapi_cmt_TT974YVQH4RAHNN2HY2DJSNY9111D7LMTP1XXPCVQVL" }, "metadata": { "description": "[optional] Platform-specific keys: google sets \"star_rating\"; facebook mentions set \"permalink_url\"; instagram sets \"media_id\" or \"referral\"", "type": "object", "additionalProperties": {} }, "page_id": { "description": "[platform: facebook] SocialAPI page ID identifying which Page received the event. Set for Facebook Page-scoped events; empty for platforms without a multi-page account model (e.g. Instagram), where account_id already identifies the account.", "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "permalink": { "description": "[optional] Public URL of the post this interaction belongs to; set for instagram comments", "type": "string", "example": "https://www.instagram.com/p/C8xY2AbC/" }, "platform": { "description": "[always]", "type": "string", "example": "instagram" }, "platform_id": { "description": "[optional] Platform-native message id, byte-identical to the platform_id of the matching row from GET /v1/inbox/conversations/{id}/messages. Set on Instagram, Facebook and WhatsApp dm.received and dm.sent, on Telegram dm.received, and on Instagram and Facebook dm.postback, so a delivered event can be joined to a message from that endpoint: id is a SocialAPI interaction id, which the messages endpoint does not return, so without this the two carry no field in common. Empty for dm.referral, which has no platform message id.", "type": "string", "example": "m_AbCdEf123" }, "platform_post_id": { "description": "[optional] Platform-native post ID; empty when not available", "type": "string", "example": "17895695668004550" }, "post_id": { "description": "[optional] SocialAPI post ID; empty when the interaction is not linked to a post", "type": "string", "example": "01HZ9X3Q4R5M6N7P8V2K0W1J42" }, "received_at": { "description": "[always]", "type": "string", "example": "2026-02-15T14:30:00Z" }, "recipient": { "description": "[platform: instagram, facebook, whatsapp] Non-nil for echo/sent DM events; nil for all other interaction types", "allOf": [ { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.Author" } ] }, "reply_to": { "description": "[platform: telegram, instagram, facebook] The earlier message this DM replies to; same value as reply_to on the matching row from GET /v1/inbox/conversations/{id}/messages. Absent when the DM is not a reply", "allOf": [ { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.MessageRef" } ] }, "story": { "description": "[platform: instagram] Set when the interaction is a reply to one of the account's stories", "allOf": [ { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.Story" } ] }, "type": { "description": "[always] One of: comment, review, dm, mention (or dm.sent/dm.received/dm.referral for webhook events)", "type": "string", "example": "comment" } } }, "social-api_ai_core_api_connectors_base.InteractionSettings": { "type": "object", "properties": { "comment_disabled": { "description": "[platform: tiktok]", "type": "boolean" }, "duet_disabled": { "description": "[platform: tiktok]", "type": "boolean" }, "stitch_disabled": { "description": "[platform: tiktok]", "type": "boolean" } } }, "social-api_ai_core_api_connectors_base.Media": { "type": "object", "properties": { "type": { "type": "string", "example": "image" }, "url": { "type": "string", "example": "https://cdn.example.com/photo.jpg" } } }, "social-api_ai_core_api_connectors_base.MessageRef": { "type": "object", "properties": { "platform_id": { "description": "Platform-native id of the referenced message, as platform_id on GET /v1/inbox/conversations/{id}/messages", "type": "string", "example": "m_AbCdEf123" } } }, "social-api_ai_core_api_connectors_base.PageInsights": { "type": "object", "properties": { "follower_count": { "type": "integer" }, "kind": { "description": "Kind is \"organization\" for a LinkedIn Page and \"member\" for a personal profile.", "type": "string", "enum": [ "organization", "member" ], "example": "organization" }, "posts": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.PostInsight" } } } }, "social-api_ai_core_api_connectors_base.PlatformMediaItem": { "type": "object", "properties": { "thumbnail_url": { "description": "Link to a video's cover image, hosted by the platform. Temporary, like url. Absent on images.", "type": "string", "example": "https://scontent.cdninstagram.com/v/t51.29350-15/456_n.jpg" }, "type": { "description": "image or video.", "type": "string", "enum": [ "image", "video" ], "example": "image" }, "url": { "description": "Link to the file, hosted by the platform. Temporary: download the file rather than keeping the link. Absent when the platform withholds the file, as Instagram does for media with licensed audio.", "type": "string", "example": "https://scontent.cdninstagram.com/v/t51.29350-15/123_n.jpg" } } }, "social-api_ai_core_api_connectors_base.Post": { "type": "object", "properties": { "account_id": { "description": "[always]", "type": "string" }, "caption": { "description": "[always] Post text body; may be empty for media-only posts", "type": "string" }, "comments_count": { "description": "[platform: instagram, facebook, tiktok] Zero on other platforms", "type": "integer" }, "id": { "description": "[always] Platform-native post/video/media ID", "type": "string" }, "like_count": { "description": "[platform: instagram, facebook, tiktok] Zero on other platforms", "type": "integer" }, "media_type": { "description": "[platform: instagram, facebook, threads, tiktok, youtube] Empty on linkedin and google", "type": "string" }, "media_url": { "description": "[platform: instagram, tiktok, youtube] Cover image or media URL; empty on facebook, threads, linkedin, google", "type": "string" }, "metadata": { "description": "[optional] Platform-specific keys; facebook sets \"page_id\" and \"page_name\"", "type": "object", "additionalProperties": {} }, "permalink": { "description": "[platform: instagram, facebook, threads, tiktok, youtube, google, linkedin]", "type": "string" }, "platform": { "description": "[always]", "type": "string" }, "platform_media": { "description": "[platform: instagram, facebook] Every image and video on the post, carousel slides or album photos in order", "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.PlatformMediaItem" } }, "settings": { "description": "[platform: instagram, facebook] Settings the platform reports for the post", "allOf": [ { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.PostSettings" } ] }, "shares_count": { "description": "[platform: facebook] Zero on other platforms", "type": "integer" }, "timestamp": { "description": "[always]", "type": "string" }, "view_count": { "description": "[platform: youtube, tiktok] Zero on other platforms", "type": "integer" } } }, "social-api_ai_core_api_connectors_base.PostChildAttachment": { "type": "object", "properties": { "description": { "description": "Description text of the card.", "type": "string" }, "link": { "description": "Destination URL of the card.", "type": "string" }, "name": { "description": "Title of the card.", "type": "string" }, "picture": { "description": "Image URL of the card.", "type": "string" } } }, "social-api_ai_core_api_connectors_base.PostInsight": { "type": "object", "properties": { "clicks": { "type": "integer" }, "comments": { "type": "integer" }, "created_at": { "type": "string" }, "engagement_rate": { "type": "number" }, "impressions": { "type": "integer" }, "likes": { "type": "integer" }, "permalink": { "type": "string" }, "post_id": { "type": "string" }, "shares": { "type": "integer" }, "text": { "type": "string" }, "unique_views": { "type": "integer" } } }, "social-api_ai_core_api_connectors_base.PostPlace": { "type": "object", "properties": { "id": { "description": "Platform id of the tagged place.", "type": "string" }, "name": { "description": "Name of the tagged place.", "type": "string" } } }, "social-api_ai_core_api_connectors_base.PostSettings": { "type": "object", "properties": { "alt_text": { "description": "Image description set on the Instagram post.", "type": "string" }, "audio_type": { "description": "Kind of audio on an Instagram Reel.", "type": "string", "enum": [ "MUSIC", "ORIGINAL_SOUND" ] }, "child_attachments": { "description": "Cards of a Facebook multi-link post.", "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.PostChildAttachment" } }, "comments_enabled": { "description": "True when comments are open on the Instagram post.", "type": "boolean" }, "countries": { "description": "ISO 3166-1 alpha-2 countries the Facebook post is restricted to.", "type": "array", "items": { "type": "string" }, "example": [ "FR", "BE" ] }, "cta_link": { "description": "Call-to-action destination on the Facebook post.", "type": "string" }, "cta_type": { "description": "Call-to-action button type on the Facebook post.", "type": "string", "example": "SHOP_NOW" }, "is_ai_generated": { "description": "True when Instagram shows the AI info label on the post.", "type": "boolean" }, "max_age": { "description": "Maximum audience age set on the Facebook post.", "type": "integer", "example": 65 }, "min_age": { "description": "Minimum audience age set on the Facebook post.", "type": "integer", "example": 18 }, "multi_share_end_card": { "description": "True when the multi-link post shows an end card.", "type": "boolean" }, "multi_share_optimized": { "description": "True when Facebook picks the card order.", "type": "boolean" }, "place": { "description": "Location tagged on the Facebook post.", "allOf": [ { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.PostPlace" } ] }, "product_type": { "description": "Instagram surface the post lives on.", "type": "string", "enum": [ "FEED", "REELS", "STORY", "AD" ] }, "share_to_feed": { "description": "True when an Instagram Reel also appears in the main profile feed.", "type": "boolean" } } }, "social-api_ai_core_api_connectors_base.Story": { "type": "object", "properties": { "expires_at": { "description": "when media_url stops working; omitted when it cannot be determined", "type": "string", "example": "2026-09-12T14:03:00Z" }, "id": { "description": "platform-native story id", "type": "string", "example": "17901" }, "media_type": { "description": "[platform: facebook] photo or video", "type": "string", "example": "photo" }, "media_url": { "description": "downloadable media link", "type": "string", "example": "https://lookaside.fbsbx.com/ig_messaging_cdn/?asset_id=17901" }, "permalink": { "description": "[platform: facebook] story permalink", "type": "string", "example": "https://facebook.com/stories/1784" } } }, "social-api_ai_core_api_connectors_base.ThreadsBreakdownResult": { "type": "object", "properties": { "dimension": { "description": "Dimension is the breakdown value, such as a country code, a city, an age range or a gender.", "type": "string" }, "value": { "type": "integer" } } }, "social-api_ai_core_api_connectors_base.ThreadsInsights": { "type": "object", "properties": { "metrics": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.ThreadsMetricValue" } } } }, "social-api_ai_core_api_connectors_base.ThreadsMetricValue": { "type": "object", "properties": { "breakdown": { "description": "Breakdown is set only for follower_demographics.", "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.ThreadsBreakdownResult" } }, "value": { "type": "integer" }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_connectors_base.ThreadsTimeSeriesPoint" } } } }, "social-api_ai_core_api_connectors_base.ThreadsPublicProfile": { "type": "object", "properties": { "biography": { "type": "string" }, "follower_count": { "type": "integer" }, "is_verified": { "type": "boolean" }, "likes_count": { "type": "integer" }, "name": { "type": "string" }, "profile_picture_url": { "type": "string" }, "quotes_count": { "type": "integer" }, "reposts_count": { "type": "integer" }, "username": { "type": "string" }, "views_count": { "type": "integer" } } }, "social-api_ai_core_api_connectors_base.ThreadsTimeSeriesPoint": { "type": "object", "properties": { "end_time": { "type": "string" }, "value": { "type": "integer" } } }, "social-api_ai_core_api_connectors_whatsapp.PhoneNumberStatusResponse": { "type": "object", "properties": { "registered": { "type": "boolean" }, "verified": { "type": "boolean" } } }, "social-api_ai_core_api_service.AccountPage": { "type": "object", "properties": { "about": { "type": "string" }, "category": { "type": "string" }, "cover_photo_url": { "type": "string" }, "enriched_at": { "type": "string" }, "followers_count": { "type": "integer" }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "is_default": { "type": "boolean" }, "link": { "type": "string" }, "name": { "type": "string" }, "platform_page_id": { "type": "string" }, "profile_picture_url": { "type": "string" }, "username": { "type": "string" }, "verification_status": { "type": "string" } } }, "social-api_ai_core_api_service.Action": { "type": "object", "properties": { "private_reply": { "description": "DM to the comment's author. Free", "allOf": [ { "$ref": "#/components/schemas/social-api_ai_core_api_service.TextAction" } ] }, "reply_comment": { "description": "Public reply to the comment. Costs 1 credit", "allOf": [ { "$ref": "#/components/schemas/social-api_ai_core_api_service.TextAction" } ] }, "send_dm": { "description": "DM in the conversation. Costs 1 credit", "allOf": [ { "$ref": "#/components/schemas/social-api_ai_core_api_service.TextAction" } ] }, "type": { "type": "string", "enum": [ "hide_comment", "reply_comment", "private_reply", "send_dm" ], "example": "private_reply" } } }, "social-api_ai_core_api_service.ActionOutcome": { "type": "object", "properties": { "action": { "type": "string", "example": "private_reply" }, "error_code": { "description": "The error code the same API call would have returned", "type": "string", "example": "platform.instagram.private_reply_ineligible" }, "status": { "type": "string", "enum": [ "sent", "failed" ], "example": "sent" } } }, "social-api_ai_core_api_service.AnalyticsOverview": { "type": "object", "properties": { "accounts_excluded": { "description": "AccountsExcluded is how many accounts in scope were left out because\nthey lack the analytics.read permission.", "type": "integer", "example": 0 }, "activity": { "description": "Activity is the daily count of replies, DMs and moderation SocialAPI\nperformed for the accounts in scope, the same series shape as the\nhistory routes.", "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.MetricSeries" } }, "best_times": { "$ref": "#/components/schemas/social-api_ai_core_api_service.OverviewBestTimes" }, "by_day": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.OverviewDay" } }, "by_format": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.OverviewFormat" } }, "by_platform": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.OverviewPlatform" } }, "from": { "type": "string", "example": "2026-10-07" }, "metrics_synced_at": { "description": "MetricsSyncedAt is the most recent counter refresh among the posts in\nrange. Absent when none has been refreshed yet.", "type": "string", "example": "2026-11-05T08:00:00Z" }, "previous": { "description": "Previous is the same figures for the window of equal length that ends\nthe day before from.", "allOf": [ { "$ref": "#/components/schemas/social-api_ai_core_api_service.OverviewTotals" } ] }, "to": { "type": "string", "example": "2026-11-05" }, "top_posts": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.OverviewTopPost" } }, "totals": { "$ref": "#/components/schemas/social-api_ai_core_api_service.OverviewTotals" }, "tz": { "type": "string", "example": "Europe/Paris" } } }, "social-api_ai_core_api_service.AnalyticsPoint": { "type": "object", "properties": { "change": { "description": "Change is the difference from the previous point in this series. Present\non gauges only, and absent on the first point of a range, which has no\npredecessor to diff against.", "type": "integer", "example": 18 }, "day": { "description": "Day is YYYY-MM-DD, cut on the boundary named by the series' day_tz.", "type": "string", "example": "2026-09-19" }, "days_spanned": { "description": "DaysSpanned is how many days Change covers. It is 1 in the normal case\nand larger when a day is missing from the series. A chart must divide by\nit and style the segment as interpolated: otherwise a gap draws a spike\nthat never happened.", "type": "integer", "example": 1 }, "subjects_counted": { "description": "SubjectsCounted is how many Subjects contributed to this point's summed\nvalue. Always at least 1. Read it before charting: a day on which not\nevery Subject reported sums lower, and without the count that reads as a\ndecline instead of a gap.", "type": "integer", "example": 3 }, "value": { "description": "Value is the figure for that day, verbatim from the platform for a\nreported point.", "type": "integer", "example": 12430 } } }, "social-api_ai_core_api_service.AnalyticsResponse": { "type": "object", "properties": { "from": { "description": "From and To are the resolved range, echoed so a caller that named neither\nknows what it got.", "type": "string", "example": "2026-08-21" }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.MetricSeries" } }, "to": { "type": "string", "example": "2026-09-19" } } }, "social-api_ai_core_api_service.Automation": { "type": "object", "properties": { "account_id": { "type": "string", "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" }, "created_at": { "type": "string" }, "failed_count": { "description": "Actions that failed", "type": "integer" }, "fired_count": { "description": "Events the Automation ran against", "type": "integer" }, "id": { "type": "string", "example": "aut_01J9Z8Y7X6W5V4T3S2R1Q0P9N8" }, "name": { "type": "string", "example": "Send the link" }, "once_per_person": { "description": "Reach each person at most once. A run in which every action failed does not count", "type": "boolean" }, "post_ids": { "description": "Up to 100 platform post ids, each 1 to 100 characters, a comment must be on. Omitted means every post. Comment trigger only", "type": "array", "items": { "type": "string" } }, "sent_count": { "description": "Actions carried out successfully", "type": "integer" }, "status": { "type": "string", "enum": [ "active", "paused" ], "example": "active" }, "steps": { "description": "Up to 10 Steps forming a graph. One must have the key \"start\"", "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.Step" } }, "trigger": { "description": "The kind of inbound event that fires the Automation", "type": "string", "enum": [ "comment", "dm" ], "example": "comment" }, "updated_at": { "type": "string" } } }, "social-api_ai_core_api_service.CarouselConstraints": { "type": "object", "properties": { "allow_video": { "description": "can carousel include video items", "type": "boolean" }, "images_only": { "description": "only image items allowed", "type": "boolean" }, "max_items": { "type": "integer" }, "min_items": { "type": "integer" }, "photos_only": { "description": "only photo items (no video, no gif - stricter than ImagesOnly)", "type": "boolean" }, "supported": { "type": "boolean" } } }, "social-api_ai_core_api_service.ConversationRow": { "type": "object", "properties": { "account_id": { "type": "string" }, "created_at": { "type": "string" }, "id": { "type": "string" }, "last_message": { "type": "string" }, "last_message_at": { "type": "string" }, "page_id": { "type": "string" }, "participant_id": { "type": "string" }, "participant_name": { "type": "string" }, "participant_picture": { "type": "string" }, "platform": { "type": "string" }, "platform_id": { "type": "string" }, "status": { "type": "string" }, "unread_count": { "type": "integer" }, "updated_at": { "type": "string" }, "user_id": { "type": "string" } } }, "social-api_ai_core_api_service.CreateAutomationParams": { "type": "object", "properties": { "account_id": { "type": "string", "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" }, "follow_gate": { "description": "Builds the three-step Follow gate. Instagram, comment trigger only. Send instead of steps", "allOf": [ { "$ref": "#/components/schemas/social-api_ai_core_api_service.FollowGate" } ] }, "name": { "description": "1 to 100 characters", "type": "string", "example": "Send the link" }, "once_per_person": { "description": "Reach each person at most once. A run in which every action failed does not count. Defaults to false", "type": "boolean" }, "post_ids": { "description": "Up to 100 platform post ids, each 1 to 100 characters, a comment must be on. Omitted means every post. Comment trigger only", "type": "array", "items": { "type": "string" } }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.Step" } }, "trigger": { "type": "string", "enum": [ "comment", "dm" ], "example": "comment" } } }, "social-api_ai_core_api_service.CreateQueueParams": { "type": "object", "properties": { "active": { "description": "Set false to create the Queue paused. Defaults to true.", "type": "boolean", "example": true }, "brand_id": { "description": "ID of the Brand to create the Queue on. Required.", "type": "string" }, "is_default": { "description": "Set true to make this the Brand's default Queue. The Brand's first Queue is always the default.", "type": "boolean", "example": false }, "name": { "description": "Queue name. Required.", "type": "string", "example": "Evenings" }, "slots": { "description": "Weekly posting times, 1 to 100. Required.", "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.Slot" } }, "timezone": { "description": "IANA timezone the slots are expressed in. Required.", "type": "string", "example": "Europe/Paris" } } }, "social-api_ai_core_api_service.DeliveryAttempt": { "type": "object", "properties": { "attempt_number": { "type": "integer" }, "created_at": { "type": "string" }, "duration_ms": { "type": "integer" }, "error_message": { "type": "string" }, "response_body": { "type": "string" }, "status_code": { "type": "integer" } } }, "social-api_ai_core_api_service.DeliveryListItem": { "type": "object", "properties": { "attempt_count": { "type": "integer" }, "created_at": { "type": "string" }, "description": { "type": "string" }, "event_type": { "type": "string" }, "id": { "type": "string" }, "response_duration_ms": { "type": "integer" }, "response_status_code": { "type": "integer" }, "status": { "type": "string" } } }, "social-api_ai_core_api_service.DeliveryStatBucket": { "type": "object", "properties": { "delivered": { "type": "integer" }, "failed": { "type": "integer" } } }, "social-api_ai_core_api_service.Filter": { "type": "object", "properties": { "keyword": { "description": "Required when type is keyword", "allOf": [ { "$ref": "#/components/schemas/social-api_ai_core_api_service.KeywordFilter" } ] }, "type": { "description": "follows_account is available on Instagram only and not on the start step", "type": "string", "enum": [ "keyword", "follows_account" ], "example": "keyword" } } }, "social-api_ai_core_api_service.Firing": { "type": "object", "properties": { "created_at": { "type": "string" }, "event_id": { "description": "Platform id of the comment or message", "type": "string", "example": "17858893269577012" }, "id": { "type": "string", "example": "afr_01J9Z8Y7X6W5V4T3S2R1Q0P9N8" }, "outcomes": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.ActionOutcome" } }, "person_id": { "description": "Platform id of the person who commented or messaged", "type": "string", "example": "17841400000000000" }, "step_key": { "description": "Key of the step whose actions ran, or the step the event entered at when no step's filters passed", "type": "string", "example": "start" } } }, "social-api_ai_core_api_service.FollowGate": { "type": "object", "properties": { "button_title": { "description": "Up to 20 characters", "type": "string", "example": "Get the link" }, "keywords": { "description": "Comment keywords that open the gate", "type": "array", "items": { "type": "string" }, "example": [ "link" ] }, "link_texts": { "description": "Sent once the person follows", "type": "array", "items": { "type": "string" }, "example": [ "Here you go: https://example.com" ] }, "not_following_texts": { "description": "Sent when the person does not follow the account yet", "type": "array", "items": { "type": "string" }, "example": [ "Follow us first and tap again" ] }, "opening_texts": { "description": "Private reply sent to the commenter", "type": "array", "items": { "type": "string" }, "example": [ "Tap below to get the link" ] }, "retry_button_title": { "description": "Up to 20 characters", "type": "string", "example": "I followed" } } }, "social-api_ai_core_api_service.InboxPostRow": { "type": "object", "properties": { "account_id": { "type": "string" }, "comment_count": { "type": "integer" }, "content": { "type": "string" }, "created_at": { "type": "string" }, "id": { "type": "string" }, "like_count": { "type": "integer" }, "page_id": { "type": "string" }, "permalink": { "type": "string" }, "platform": { "type": "string" }, "platform_id": { "type": "string" }, "published_at": { "type": "string" }, "thumbnail": { "type": "string" }, "updated_at": { "type": "string" }, "user_id": { "type": "string" } } }, "social-api_ai_core_api_service.KeywordFilter": { "type": "object", "properties": { "keywords": { "description": "1 to 50, each 1 to 100 characters", "type": "array", "items": { "type": "string" }, "example": [ "link", "price" ] }, "match": { "description": "contains: a keyword appears as a whole word or phrase. exact: the whole text equals a keyword", "type": "string", "enum": [ "contains", "exact" ], "example": "contains" } } }, "social-api_ai_core_api_service.MediaConstraints": { "type": "object", "properties": { "max_image_size_bytes": { "description": "0 = not supported", "type": "integer" }, "max_video_duration_sec": { "description": "0 = no max", "type": "integer" }, "max_video_fps": { "description": "0 = no limit", "type": "integer" }, "max_video_size_bytes": { "description": "0 = not supported", "type": "integer" }, "min_video_duration_sec": { "description": "0 = no min", "type": "integer" }, "supported_image_types": { "description": "MIME types, e.g. \"image/jpeg\"", "type": "array", "items": { "type": "string" } }, "supported_video_types": { "description": "MIME types, e.g. \"video/mp4\"", "type": "array", "items": { "type": "string" } } } }, "social-api_ai_core_api_service.MessageReply": { "type": "object", "properties": { "platform_id": { "type": "string" } } }, "social-api_ai_core_api_service.MessageRow": { "type": "object", "properties": { "attachment_type": { "type": "string" }, "attachment_url": { "type": "string" }, "conversation_id": { "type": "string" }, "created_at": { "type": "string" }, "direction": { "type": "string" }, "id": { "type": "string" }, "platform_id": { "type": "string" }, "reply_to": { "description": "ReplyTo is the message this one replies to, or null when it is not a reply.", "allOf": [ { "$ref": "#/components/schemas/social-api_ai_core_api_service.MessageReply" } ] }, "sender_id": { "type": "string" }, "sender_name": { "type": "string" }, "status": { "type": "string" }, "status_updated_at": { "type": "string" }, "text": { "type": "string" } } }, "social-api_ai_core_api_service.MetricSeries": { "type": "object", "properties": { "day_tz": { "description": "DayTZ names the boundary these days were cut on, or mixed when a rollup\ncombines platforms that cut differently. A Brand rollup genuinely mixes\nboundaries: up to eight hours of activity sits on the wrong side of a day\nedge for Meta platforms next to a UTC-cut platform in the same sum. The\nerror is bounded and does not compound, and this field is how a reader\ntells it from a real discrepancy.", "type": "string", "example": "America/Los_Angeles" }, "kind": { "description": "Kind is gauge (a level, diff it) or flow (a per-day count, sum it).", "type": "string", "example": "gauge" }, "metric": { "description": "Metric is the platform's own name for a platform Metric.", "type": "string", "example": "page_follows" }, "points": { "description": "Points are ordered oldest first.", "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.AnalyticsPoint" } }, "source": { "description": "Source is reported, sampled, owned, or mixed when a rollup combines more\nthan one.", "type": "string", "example": "reported" } } }, "social-api_ai_core_api_service.OverviewBestTimeCell": { "type": "object", "properties": { "avg_engagements": { "description": "AvgEngagements is the mean engagements of the posts published in this\nhour. It describes your past posts, not when your audience is online.", "type": "number", "example": 118.4 }, "hour": { "description": "Hour is 0 to 23.", "type": "integer", "example": 9 }, "posts": { "type": "integer", "example": 5 }, "weekday": { "description": "Weekday is 1 (Monday) to 7 (Sunday).", "type": "integer", "example": 4 } } }, "social-api_ai_core_api_service.OverviewBestTimes": { "type": "object", "properties": { "cells": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.OverviewBestTimeCell" } }, "posts_considered": { "type": "integer", "example": 42 } } }, "social-api_ai_core_api_service.OverviewDay": { "type": "object", "properties": { "day": { "type": "string", "example": "2026-10-14" }, "engagements": { "type": "integer", "example": 290 }, "posts": { "type": "integer", "example": 3 } } }, "social-api_ai_core_api_service.OverviewFormat": { "type": "object", "properties": { "engagements": { "type": "integer", "example": 1900 }, "media_type": { "description": "MediaType is the platform's own media kind, lowercased (image, video,\nreel, carousel_album, ...), or unknown when the platform did not say.", "type": "string", "example": "reel" }, "posts": { "type": "integer", "example": 12 } } }, "social-api_ai_core_api_service.OverviewPlatform": { "type": "object", "properties": { "comments": { "type": "integer", "example": 412 }, "engagements": { "type": "integer", "example": 3810 }, "likes": { "type": "integer", "example": 3120 }, "platform": { "type": "string", "example": "instagram" }, "posts": { "type": "integer", "example": 42 }, "saves": { "type": "integer", "example": 77 }, "shares": { "type": "integer", "example": 201 }, "views": { "type": "integer", "example": 58200 } } }, "social-api_ai_core_api_service.OverviewPostMetrics": { "type": "object", "properties": { "comments": { "type": "integer", "example": 52 }, "engagements": { "type": "integer", "example": 512 }, "likes": { "type": "integer", "example": 430 }, "saves": { "type": "integer", "example": 9 }, "shares": { "type": "integer", "example": 21 }, "views": { "type": "integer", "example": 10400 } } }, "social-api_ai_core_api_service.OverviewTopPost": { "type": "object", "properties": { "account_id": { "type": "string", "example": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" }, "media_type": { "type": "string", "example": "reel" }, "metrics": { "$ref": "#/components/schemas/social-api_ai_core_api_service.OverviewPostMetrics" }, "permalink": { "type": "string", "example": "https://www.instagram.com/p/C1a2b3c4d5/" }, "platform": { "type": "string", "example": "instagram" }, "post_id": { "type": "string", "example": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }, "published_at": { "type": "string", "example": "2026-10-14T09:30:00Z" }, "text": { "type": "string", "example": "Our autumn menu is here" }, "thumbnail": { "type": "string", "example": "https://scontent.cdninstagram.com/v/t51.29350-15/456_n.jpg" } } }, "social-api_ai_core_api_service.OverviewTotals": { "type": "object", "properties": { "comments": { "type": "integer", "example": 412 }, "engagements": { "type": "integer", "example": 3810 }, "likes": { "type": "integer", "example": 3120 }, "posts": { "type": "integer", "example": 42 }, "saves": { "type": "integer", "example": 77 }, "shares": { "type": "integer", "example": 201 }, "views": { "type": "integer", "example": 58200 } } }, "social-api_ai_core_api_service.PlatformConstraints": { "type": "object", "properties": { "carousel": { "$ref": "#/components/schemas/social-api_ai_core_api_service.CarouselConstraints" }, "media": { "$ref": "#/components/schemas/social-api_ai_core_api_service.MediaConstraints" }, "scheduling": { "$ref": "#/components/schemas/social-api_ai_core_api_service.SchedulingConstraints" }, "supports_mixed_media": { "description": "SupportsMixedMedia reports whether a platform_attachment_id item may be\ncombined with other media (url/media_id) in the same post. When false\n(instagram, threads) a platform_attachment_id must be the only media item.\nMeaningful only when SupportsPlatformAttachmentID is true.", "type": "boolean" }, "supports_platform_attachment_id": { "type": "boolean" }, "text": { "$ref": "#/components/schemas/social-api_ai_core_api_service.TextConstraints" } } }, "social-api_ai_core_api_service.Queue": { "type": "object", "properties": { "active": { "description": "False when the Queue is paused: no new post can join it.", "type": "boolean", "example": true }, "brand_id": { "description": "ID of the Brand the Queue belongs to.", "type": "string" }, "created_at": { "description": "When the Queue was created.", "type": "string" }, "id": { "description": "Queue ID.", "type": "string", "example": "que_01J9Z8Y7X6W5V4T3S2R1Q0P9N8" }, "is_default": { "description": "True for the Brand's default Queue, the one queue_id \"default\" refers to.", "type": "boolean", "example": true }, "name": { "description": "Queue name.", "type": "string", "example": "Evenings" }, "slots": { "description": "Weekly posting times, sorted by day (Monday first) then time.", "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.Slot" } }, "timezone": { "description": "IANA timezone the slots are expressed in.", "type": "string", "example": "Europe/Paris" }, "updated_at": { "description": "When the Queue was last changed.", "type": "string" } } }, "social-api_ai_core_api_service.QueuedTime": { "type": "object", "properties": { "day": { "description": "Lowercase English weekday name.", "type": "string", "example": "tuesday" }, "slot_time": { "description": "The slot's time of day as HH:MM.", "type": "string", "example": "19:00" }, "time": { "description": "The time as RFC 3339 with the Queue's local offset.", "type": "string", "example": "2026-10-20T19:00:00+02:00" } } }, "social-api_ai_core_api_service.SchedulingConstraints": { "type": "object", "properties": { "mode": { "description": "Mode reflects the platform's native scheduling support: \"native\" when the\nplatform can schedule the post itself, \"server_side\" when the platform has\nno native scheduling and SocialAPI holds the post and publishes it at the\nscheduled time. Regardless of mode, scheduled_at is accepted whenever\nSupported is true. Empty when Supported is false.", "type": "string" }, "supported": { "description": "whether scheduled_at is accepted for this platform", "type": "boolean" } } }, "social-api_ai_core_api_service.Slot": { "type": "object", "properties": { "day": { "description": "Lowercase English weekday name.", "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "example": "tuesday" }, "time": { "description": "Time of day as HH:MM, 24-hour, in the Queue's timezone.", "type": "string", "example": "19:00" } } }, "social-api_ai_core_api_service.Step": { "type": "object", "properties": { "actions": { "description": "At most one of each type", "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.Action" } }, "buttons": { "description": "Up to 3, shown under the private_reply or send_dm message. With buttons, each of that message's texts is at most 640 characters", "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.StepButton" } }, "fallthrough_step": { "description": "Key of the Step to run when this Step's filters fail. Not allowed on start", "type": "string" }, "filters": { "description": "Up to 10. All must pass. None means every event passes", "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.Filter" } }, "key": { "description": "Unique within the Automation. The entry step is \"start\"", "type": "string", "example": "start" } } }, "social-api_ai_core_api_service.StepButton": { "type": "object", "properties": { "next_step": { "description": "Key of the Step to run when this button is tapped. Required when type is postback", "type": "string", "example": "check" }, "title": { "description": "Up to 20 characters", "type": "string", "example": "Open" }, "type": { "type": "string", "enum": [ "url", "postback" ], "example": "url" }, "url": { "description": "An http or https URL. Required when type is url", "type": "string", "example": "https://example.com" } } }, "social-api_ai_core_api_service.TextAction": { "type": "object", "properties": { "texts": { "description": "1 to 10 variants, each 1 to 1000 characters, or at most 640 for a private_reply or send_dm whose step has buttons; one is picked at random each time", "type": "array", "items": { "type": "string" }, "example": [ "Here is the link: https://example.com" ] } } }, "social-api_ai_core_api_service.TextConstraints": { "type": "object", "properties": { "counting_mode": { "description": "\"chars\" (default), \"utf16\", \"bytes\"", "type": "string" }, "max_hashtags": { "description": "0 = no limit", "type": "integer" }, "max_length": { "description": "maximum allowed length (in units defined by CountingMode)", "type": "integer" }, "max_mentions": { "description": "0 = no limit", "type": "integer" }, "photo_max_length": { "description": "platform-specific stricter cap for photo-mode captions (e.g. TikTok); 0 = use MaxLength", "type": "integer" } } }, "social-api_ai_core_api_service.UpdateAutomationParams": { "type": "object", "properties": { "name": { "description": "1 to 100 characters", "type": "string" }, "once_per_person": { "type": "boolean" }, "post_ids": { "description": "Up to 100 platform post ids, each 1 to 100 characters, a comment must be on. An empty list means every post. Comment trigger only", "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.Step" } } } }, "social-api_ai_core_api_service.UpdateQueueParams": { "type": "object", "properties": { "active": { "description": "False pauses the Queue, true resumes it.", "type": "boolean", "example": true }, "is_default": { "description": "Only true is accepted: it makes this the Brand's default Queue.", "type": "boolean", "example": true }, "name": { "description": "New name.", "type": "string", "example": "Evenings" }, "reshuffle_existing": { "description": "Set true to move the Queue's posts onto the new slots, in their current order. The response then carries reshuffled_count.", "type": "boolean", "example": false }, "slots": { "description": "Weekly posting times. Replaces the whole list when sent; omit to keep the current list.", "type": "array", "items": { "$ref": "#/components/schemas/social-api_ai_core_api_service.Slot" } }, "timezone": { "description": "New IANA timezone.", "type": "string", "example": "Europe/Paris" } } }, "social-api_ai_core_api_service.WebhookEventInfo": { "type": "object", "properties": { "category": { "description": "\"posts\" | \"inbox\" | \"accounts\"", "type": "string" }, "description": { "type": "string" }, "event": { "type": "string" } } }, "social-api_ai_core_api_service.WebhookStats": { "type": "object", "properties": { "last_24h": { "$ref": "#/components/schemas/social-api_ai_core_api_service.DeliveryStatBucket" }, "last_7d": { "$ref": "#/components/schemas/social-api_ai_core_api_service.DeliveryStatBucket" } } } } } }