> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postlybee.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create posts

> Create drafts, scheduled posts, immediate posts, or social threads for one or more connected accounts.



## OpenAPI

````yaml /api-reference/openapi.json post /public/v1/posts
openapi: 3.0.0
info:
  title: PostlyBee Public API
  description: >-
    Create and manage social posts, upload media, and discover connected
    accounts with the PostlyBee Public API.
  version: 1.0.0
  contact:
    name: PostlyBee Support
    url: https://postlybee.com
    email: support@postlybee.com
  license:
    name: Proprietary
    url: https://postlybee.com/terms
servers:
  - url: https://api.postlybee.com
    description: Production
security: []
tags:
  - name: Posts
    description: Create, list, update, and delete social posts.
  - name: Media
    description: Upload media and use enabled video generators.
  - name: Accounts
    description: Discover connected social accounts.
  - name: Utilities
    description: Verify access and find posting slots.
paths:
  /public/v1/posts:
    post:
      tags:
        - Posts
      summary: Create posts
      description: >-
        Create drafts, scheduled posts, immediate posts, or social threads for
        one or more connected accounts.
      operationId: createPosts
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicApiCreatePostRequestDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PublicApiCreatedPostDto'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiValidationErrorDto'
        '401':
          description: The bearer token is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorDto'
        '403':
          description: The workspace plan does not allow this operation.
        '429':
          description: Hourly API limit exceeded.
      security:
        - public-api: []
components:
  schemas:
    PublicApiCreatePostRequestDto:
      type: object
      properties:
        type:
          type: string
          enum:
            - draft
            - schedule
            - now
          example: schedule
        order:
          type: string
          description: Client-defined ordering value.
        republish:
          type: boolean
          description: Allow a previously published post to be published again.
          default: false
        shortLink:
          type: boolean
          description: Convert eligible links to tracked short links.
          default: false
        autoSchedule:
          type: boolean
          description: Use the posting schedule of each connected account.
          default: false
        autoScheduleOptions:
          $ref: '#/components/schemas/PublicApiAutoScheduleOptionsInputDto'
        date:
          type: string
          description: UTC publish time. Required unless autoSchedule is true.
          example: '2026-09-01T09:00:00.000Z'
        repeat:
          $ref: '#/components/schemas/PublicApiRepeatInputDto'
        recycle:
          $ref: '#/components/schemas/PublicApiRecycleInputDto'
        tags:
          default: []
          type: array
          items:
            $ref: '#/components/schemas/PublicApiTagInputDto'
        posts:
          type: array
          items:
            $ref: '#/components/schemas/PublicApiPostInputDto'
      required:
        - type
        - shortLink
        - tags
        - posts
    PublicApiCreatedPostDto:
      type: object
      properties:
        postId:
          type: string
          example: clz8v2f6r0001k9p8t5m3w7q1
        integration:
          type: string
          description: The connected account ID used to create the post.
          example: clz8tq4ka0001m8p7y6n5r3d2
      required:
        - postId
        - integration
    PublicApiValidationErrorDto:
      type: object
      properties:
        message:
          oneOf:
            - type: string
              example: At least one post is required
            - type: array
              items:
                type: string
              example:
                - date must be a valid ISO 8601 date string
        error:
          type: string
          example: Bad Request
        statusCode:
          type: number
          example: 400
      required:
        - message
    PublicApiErrorDto:
      type: object
      properties:
        msg:
          type: string
          example: Invalid API key
      required:
        - msg
    PublicApiAutoScheduleOptionsInputDto:
      type: object
      properties:
        scheduleAfter:
          type: string
          description: Do not select a queue slot before this UTC time.
          example: '2026-09-01T08:00:00.000Z'
        scheduleBefore:
          type: string
          description: Do not select a queue slot after this UTC time.
          example: '2026-09-30T18:00:00.000Z'
        topOfQueue:
          type: boolean
          default: false
    PublicApiRepeatInputDto:
      type: object
      properties:
        enabled:
          type: boolean
          example: true
        times:
          type: number
          minimum: 1
          maximum: 30
          example: 3
        intervalValue:
          type: number
          minimum: 1
          maximum: 365
          example: 1
        intervalUnit:
          type: string
          enum:
            - DAY
            - WEEK
            - MONTH
          example: WEEK
      required:
        - enabled
        - times
        - intervalValue
        - intervalUnit
    PublicApiRecycleInputDto:
      type: object
      properties:
        enabled:
          type: boolean
          example: true
        intervalValue:
          type: number
          minimum: 1
          maximum: 365
          example: 7
        intervalUnit:
          type: string
          enum:
            - DAY
            - WEEK
            - MONTH
          example: DAY
        maxCycles:
          type: number
          minimum: 1
          maximum: 1000
          example: 10
      required:
        - enabled
        - intervalValue
        - intervalUnit
    PublicApiTagInputDto:
      type: object
      properties:
        value:
          type: string
          description: Tag ID.
          format: uuid
        label:
          type: string
          description: Tag label.
          example: Product launch
      required:
        - value
        - label
    PublicApiPostInputDto:
      type: object
      properties:
        integration:
          $ref: '#/components/schemas/PublicApiIntegrationInputDto'
        value:
          description: One item for a regular post, or multiple items for a thread.
          type: array
          items:
            $ref: '#/components/schemas/PublicApiPostContentInputDto'
        lockTopQueue:
          type: boolean
          description: Place an auto-scheduled post at the top of the queue.
          default: false
        group:
          type: string
          description: Existing post group when editing a draft.
        settings:
          type: object
          additionalProperties: true
          description: Provider-specific settings for the connected account.
          example: {}
      required:
        - integration
        - value
        - settings
    PublicApiIntegrationInputDto:
      type: object
      properties:
        id:
          type: string
          description: Connected account ID returned by GET /public/v1/integrations.
          example: clz8tq4ka0001m8p7y6n5r3d2
      required:
        - id
    PublicApiPostContentInputDto:
      type: object
      properties:
        content:
          type: string
          description: Post text. Add more items to create a thread.
          example: We just shipped a new way to schedule content.
        id:
          type: string
          description: Existing post ID when replacing a draft.
        image:
          description: Media uploaded through a public media endpoint.
          default: []
          type: array
          items:
            $ref: '#/components/schemas/PublicApiMediaInputDto'
      required:
        - content
        - image
    PublicApiMediaInputDto:
      type: object
      properties:
        id:
          type: string
          description: Media ID returned by an upload endpoint.
          example: 4cb8c6af-7111-4e5d-a7cd-846c9293d4c1
        path:
          type: string
          description: Public URL of the uploaded media.
          example: https://postlybee.com/uploads/2026/08/launch-image.png
        alt:
          type: string
          example: Product launch graphic
        thumbnail:
          type: string
          description: Optional thumbnail URL for video media.
          example: https://postlybee.com/uploads/2026/08/video-thumbnail.jpg
      required:
        - id
        - path
  securitySchemes:
    public-api:
      scheme: bearer
      bearerFormat: API key
      type: http
      description: Workspace API key from Settings → Public API.

````