> ## 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.

# 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.
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.

        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'
        '422':
          description: publishing.delivery.all_failed (fast completion)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_endpoints.PostResponse'
        '429':
          description: Monthly post limit exceeded
          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
        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
        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.
          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'
        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'
    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.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
          example: instagram
        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'
        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:
        comments:
          type: integer
          example: 23
        extra:
          type: object
          additionalProperties: {}
        likes:
          type: integer
          example: 142
        saves:
          type: integer
          example: 31
        shares:
          type: integer
          example: 8
  securitySchemes:
    BearerAuth:
      description: >-
        Prefix your API key with "Bearer ". Example: `Authorization: Bearer
        sapi_key_...`
      type: apiKey
      name: Authorization
      in: header

````