> ## Documentation Index > Fetch the complete documentation index at: https://docs.social-api.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Base URL: https://api.social-api.ai/v1. Send your API key in the Authorization header: Authorization: Bearer . > Every error response from /v1 is JSON: { "error": { "code", "message", "meta" (optional) }, "request_id" }. Branch on error.code; use error.message only for logs. > A 429 response carries a Retry-After header, in seconds, when the limit has a known wait. Authenticated responses can carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset for the per-minute request budget your SocialAPI account shares across every API key (see /guides/rate-limits). > Paginated list endpoints return next_cursor, at the top level or inside pagination (see /guides/pagination). Pass it as the cursor query parameter to get the next page. An absent or empty next_cursor means you have the last page. > Treat every ID as an opaque string: do not parse it or assume a format. > Support differs by platform and by operation. Check /platforms/overview before assuming an operation works on a platform. An unsupported operation returns 501 with error.code resource.not_supported. # Create or schedule a post > Creates a post for one or more connected accounts. Set `publish_now: true` to publish immediately: the post is accepted with status `publishing` and delivery runs in the background (so slow reel/video uploads do not block the request). The terminal status (`published`, `partial`, or `failed`) arrives via the `post.published`/`post.partial`/ `post.failed` webhooks and by polling GET /posts/{pid}. Set `scheduled_at` to queue the post for future publication. With neither flag the post is saved as a draft (this is the default, even when targets are provided); publish it later with POST /posts/{pid}/publish. Set `stagger` to publish the targets one after another, separated by a random delay between `min_seconds` and `max_seconds`, instead of all at once; the post is then returned with status `scheduled`. Set `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. Consumes 1 post credit when the post is published or scheduled; saving a draft is free. ## OpenAPI ````yaml /api-reference/openapi.json post /posts 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' servers: - url: https://api.social-api.ai/v1 security: [] paths: /posts: post: tags: - Posts summary: Create or schedule a post description: >- Creates a post for one or more connected accounts. Set `publish_now: true` to publish immediately: the post is accepted with status `publishing` and delivery runs in the background (so slow reel/video uploads do not block the request). The terminal status (`published`, `partial`, or `failed`) arrives via the `post.published`/`post.partial`/ `post.failed` webhooks and by polling GET /posts/{pid}. Set `scheduled_at` to queue the post for future publication. With neither flag the post is saved as a draft (this is the default, even when targets are provided); publish it later with POST /posts/{pid}/publish. Set `stagger` to publish the targets one after another, separated by a random delay between `min_seconds` and `max_seconds`, instead of all at once; the post is then returned with status `scheduled`. Set `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. Consumes 1 post credit when the post is published or scheduled; saving a draft is free. 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' security: - BearerAuth: [] components: schemas: 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, or 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. Deprecated: 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 body of its own through text or a platform_data field the connector uses as 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.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.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.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.SegmentRequest: type: object properties: media: description: >- Media is the ordered, agnostic media list. Each item is a url, a media_id, or a platform_attachment_id; order and mixing are preserved. Supersedes media_ids. Currently 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. Deprecated: 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.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.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 targets use board_id; page_id is also accepted as an alias, but supplying both 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, or 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. Deprecated: 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.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.ErrorBody: type: object properties: code: type: string example: resource.not_found message: type: string example: Account not found meta: type: object additionalProperties: {} 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 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.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.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.PostPlace: type: object properties: id: description: Platform id of the tagged place. type: string name: description: Name of the tagged place. type: string securitySchemes: BearerAuth: description: >- Prefix your API key with "Bearer ". Example: `Authorization: Bearer sapi_key_...` type: apiKey name: Authorization in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.