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

# Create post

> Creates one post on one social account.

- `status: draft` (default) saves a draft.
- `status: scheduled` with `scheduled_at` schedules it at that time; with `queue` (`next` or `top`) it takes a slot of the channel's posting schedule; with `queue_slot` it takes that exact free slot (from `GET /channels/{account}/queue/slots`).
- `status: publishing` publishes it now.

Omitted `content_type` is chosen like the app does: on Pinterest a video makes `pinterest_video_pin` and several images `pinterest_carousel`, on TikTok images only make `tiktok_photo`, every other network takes its default format.

To schedule or publish, the post needs its network's required settings in `meta` (see `PlatformMeta`). Sending `platforms` is refused with `422`; validation errors name the field directly (`meta.board_id`, `content_type`). API keys belong to workspace admins, who publish directly, so a post created through the API is never stored as `pending_approval`.

To post the same text on several channels at once, use `POST /posts/batch`.



## OpenAPI

````yaml /openapi.json post /posts
openapi: 3.1.0
info:
  title: TryPost API
  version: 2.0.0
  description: >-
    REST API for TryPost. Authenticate with a workspace API key as a Bearer
    token.
servers:
  - url: https://app.trypost.it/api
    description: TryPost Cloud
security:
  - bearerAuth: []
tags:
  - name: Posts
    description: Create, read, update, delete and preview posts.
  - name: Post notes
    description: Internal notes on a post, visible to workspace members.
  - name: Approvals
    description: Approve or reject posts waiting for approval.
  - name: Recurrence
    description: Make a post repeat on a schedule.
  - name: Media and uploads
    description: Upload files and attach media to posts.
  - name: Social accounts
    description: Connected social accounts and their network-specific options.
  - name: Channels
    description: A channel's posting schedule and queue.
  - name: Ideas
    description: Ideas on the Create board.
  - name: Idea stages
    description: The groups (columns) of the ideas board.
  - name: Analytics
    description: Workspace and channel insights.
  - name: Labels
    description: Labels to organize posts and ideas.
  - name: Signatures
    description: Reusable text to append to posts.
  - name: Workspace
    description: The workspace the API key belongs to.
  - name: API keys
    description: Personal API keys for this workspace.
  - name: Webhooks
    description: Outgoing webhooks and their delivery logs.
  - name: Repurposes
    description: Automations that republish videos posted outside TryPost.
  - name: Platform
    description: Platform capabilities and content types.
paths:
  /posts:
    post:
      tags:
        - Posts
      summary: Create post
      description: >-
        Creates one post on one social account.


        - `status: draft` (default) saves a draft.

        - `status: scheduled` with `scheduled_at` schedules it at that time;
        with `queue` (`next` or `top`) it takes a slot of the channel's posting
        schedule; with `queue_slot` it takes that exact free slot (from `GET
        /channels/{account}/queue/slots`).

        - `status: publishing` publishes it now.


        Omitted `content_type` is chosen like the app does: on Pinterest a video
        makes `pinterest_video_pin` and several images `pinterest_carousel`, on
        TikTok images only make `tiktok_photo`, every other network takes its
        default format.


        To schedule or publish, the post needs its network's required settings
        in `meta` (see `PlatformMeta`). Sending `platforms` is refused with
        `422`; validation errors name the field directly (`meta.board_id`,
        `content_type`). API keys belong to workspace admins, who publish
        directly, so a post created through the API is never stored as
        `pending_approval`.


        To post the same text on several channels at once, use `POST
        /posts/batch`.
      operationId: createPost
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - social_account_id
              properties:
                content:
                  type:
                    - string
                    - 'null'
                  maxLength: 25000
                  description: >-
                    Post text, at most 25000 characters. When `status` is
                    `scheduled` or `publishing` it must also fit each account's
                    limit (`max_content_length` of the social account, for
                    example 280 on X or 25000 for X accounts with long posts,
                    300 on Bluesky, 500 on Mastodon including the content
                    warning), measured on the text the network receives. A
                    scheduled or published post needs text or media.
                media:
                  type: array
                  items:
                    $ref: '#/components/schemas/MediaReference'
                  description: >-
                    Media in order. Each item is one of `upload_token`, `url` or
                    `id`. Types the channel does not accept are refused.
                status:
                  type: string
                  enum:
                    - draft
                    - scheduled
                    - publishing
                  description: >-
                    `draft` keeps the post editable. `scheduled` schedules it at
                    `scheduled_at` or in the channel queue (`queue`).
                    `publishing` publishes it now.
                  default: draft
                social_account_id:
                  type: string
                  format: uuid
                  description: >-
                    Social account of this workspace. A post has exactly one;
                    use `POST /posts/batch` for several.
                content_type:
                  oneOf:
                    - $ref: '#/components/schemas/ContentType'
                    - type: 'null'
                  description: >-
                    Format; must belong to the account's network. Omitted, it is
                    chosen from the media.
                meta:
                  $ref: '#/components/schemas/PlatformMeta'
                scheduled_at:
                  type:
                    - string
                    - 'null'
                  format: date-time
                  description: >-
                    When to publish, for `status: scheduled`. Any date string;
                    must be in the future and before `2038-01-19`. Cannot be
                    combined with `queue`. Required with `status: scheduled`
                    unless `queue` or `queue_slot` is sent.
                queue:
                  type:
                    - string
                    - 'null'
                  enum:
                    - next
                    - top
                    - null
                  description: >-
                    Queue position, only with `status: scheduled`. `next` takes
                    the channel's first free slot; `top` takes its first slot
                    and moves the queued posts behind it to the next gap. The
                    channel must have posting times (`has_posting_schedule`).
                    Cannot be combined with `scheduled_at`.
                queue_slot:
                  type:
                    - string
                    - 'null'
                  format: date-time
                  description: >-
                    Instant of one free slot from `GET
                    /channels/{account}/queue/slots`, only with `status:
                    scheduled`. Stores the post as a queue post in that slot;
                    refused when the slot is taken or held by a pending approval
                    request. Before `2038-01-19`. Cannot be combined with
                    `queue`. Takes the place of `scheduled_at` when both are
                    sent.
                label_ids:
                  type: array
                  items:
                    type: string
                    format: uuid
                  description: Labels of this workspace.
            examples:
              x_thread:
                summary: X thread with media
                value:
                  content: We just shipped scheduled threads. Here is how they work.
                  status: scheduled
                  scheduled_at: '2026-10-12T14:00:00Z'
                  media:
                    - url: https://example.com/launch.jpg
                      alt: Product launch banner
                  social_account_id: 9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54
                  content_type: x_post
                  meta:
                    thread_replies:
                      - text: 2/ Replies publish under the first post.
                  label_ids:
                    - 9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f
              x_poll:
                summary: X poll
                value:
                  content: Which feature should we ship next?
                  status: scheduled
                  queue: next
                  social_account_id: 9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54
                  content_type: x_poll
                  meta:
                    poll:
                      options:
                        - Calendar sync
                        - Bulk upload
                        - Dark mode
                      duration_minutes: 1440
              linkedin_with_comment:
                summary: LinkedIn post with a comment
                value:
                  content: We just shipped scheduled threads.
                  status: scheduled
                  queue: next
                  social_account_id: 9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54
                  content_type: linkedin_post
                  meta:
                    thread_replies:
                      - text: 'Read more: https://trypost.it/blog/threads'
      responses:
        '201':
          description: The created post.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
              example:
                id: 9d3c1f2a-6b4e-4c8a-9f1e-2a7b5c8d0e41
                post_group_id: 9d3c1f29-e0a1-4b7c-8d2e-5f6a7b8c9d03
                author:
                  id: 9b1e2d3c-4f5a-4b6c-8d7e-9f0a1b2c3d4e
                  name: Ana Souza
                content: We just shipped scheduled threads. Here is how they work.
                media:
                  - id: 9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f
                    path: medias/9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f.jpg
                    url: >-
                      https://media.trypost.it/medias/9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f.jpg
                    type: image
                    mime_type: image/jpeg
                    original_filename: launch.jpg
                    size: 482113
                    meta:
                      width: 1080
                      height: 1350
                      alt_text: Product launch banner
                status: scheduled
                schedule_mode: custom
                scheduled_at: '2026-10-12 14:00:00'
                published_at: null
                approval_requested_by: null
                approval_requested_at: null
                approved_by: null
                approved_at: null
                recurrence: null
                origin: trypost
                publish_status: pending
                platform: x
                content_type: x_post
                meta:
                  thread_replies:
                    - text: 2/ Replies publish under the first post.
                      media: []
                platform_url: null
                error_message: null
                display_name: TryPost
                display_username: trypostit
                display_avatar: >-
                  https://pbs.twimg.com/profile_images/1790000000000000000/avatar_400x400.jpg
                social_account:
                  id: 9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54
                  platform: x
                  display_name: TryPost
                  username: trypostit
                  status: connected
                  has_posting_schedule: true
                  timezone: America/Sao_Paulo
                  posting_goal: 5
                  max_content_length: 280
                  long_posts: false
                  verified_badge: null
                labels:
                  - id: 9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f
                    name: Launch
                    color: '#2563EB'
                    created_at: '2026-09-01 10:00:00'
                    updated_at: '2026-09-01 10:00:00'
                created_at: '2026-10-08 13:20:11'
                updated_at: '2026-10-08 13:20:11'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    MediaReference:
      type: object
      description: >-
        One media item to put on a post. Give **exactly one** of `upload_token`,
        `url` or `id`, otherwise the request fails with `Each media item needs
        exactly one of upload_token, url or id.`
      properties:
        upload_token:
          type: string
          format: uuid
          description: >-
            Token from `POST /uploads` or a signed upload URL. Single use: the
            first post that takes it consumes it. Kept 24 hours.
        url:
          type: string
          format: uri
          maxLength: 2048
          description: >-
            Public `http` or `https` URL of the file itself. Downloaded once per
            request; redirects are not followed and private hosts are refused.
        id:
          type: string
          format: uuid
          description: >-
            Id of a media item already in this workspace (for example
            `media[].id` of another post). The file is copied.
        alt:
          type: string
          maxLength: 2000
          description: >-
            Alt text shorthand. Applies to images only; `meta.alt_text` wins
            when both are sent.
        meta:
          $ref: '#/components/schemas/MediaItemMeta'
      examples:
        - url: https://example.com/launch.jpg
          alt: Product launch banner
    ContentType:
      type: string
      enum:
        - instagram_feed
        - instagram_reel
        - instagram_story
        - linkedin_post
        - linkedin_page_post
        - facebook_post
        - facebook_reel
        - facebook_story
        - tiktok_video
        - tiktok_photo
        - youtube_short
        - x_post
        - x_poll
        - threads_post
        - threads_ghost_post
        - pinterest_pin
        - pinterest_video_pin
        - pinterest_carousel
        - bluesky_post
        - mastodon_post
        - telegram_post
        - discord_message
        - google_business_post
      description: >-
        Post format on one network. It must belong to the destination's network.
        `GET /content-types` lists the formats of each network with their media
        rules. Instagram and Facebook stories publish no text. An X poll
        (`x_poll`) takes no media; its choices and length are in `meta.poll`.
    PlatformMeta:
      description: >-
        Per-network settings of one destination. Pick the shape of the
        destination's network. Keys without a rule are dropped. Every known key
        is validated whatever the network, but only the keys of the
        destination's network are used when publishing. On update, `meta` is
        merged with the stored settings: send `null` for a key to clear it
        (string, list and object settings; boolean settings cannot be cleared,
        so send `true` or `false`); `thread_replies` replaces the whole list;
        `poll` is merged key by key, its `options` replaced as a list. Required
        to schedule or publish: TikTok `privacy_level`, Pinterest `board_id`,
        Discord `channel_id`, Google Business `event` on `EVENT`/`OFFER`,
        YouTube a title (`title` or the first line of the text), X
        `poll.options` (2 or more), `poll.duration_minutes` and a question (the
        post `content`) on `x_poll`. `GET /content-types` lists the
        unconditional ones (TikTok, Pinterest, Discord) per network as
        `required_meta`.
      anyOf:
        - $ref: '#/components/schemas/PlatformMetaX'
        - $ref: '#/components/schemas/PlatformMetaBluesky'
        - $ref: '#/components/schemas/PlatformMetaMastodon'
        - $ref: '#/components/schemas/PlatformMetaTikTok'
        - $ref: '#/components/schemas/PlatformMetaPinterest'
        - $ref: '#/components/schemas/PlatformMetaDiscord'
        - $ref: '#/components/schemas/PlatformMetaYouTube'
        - $ref: '#/components/schemas/PlatformMetaInstagram'
        - $ref: '#/components/schemas/PlatformMetaThreads'
        - $ref: '#/components/schemas/PlatformMetaFacebook'
        - $ref: '#/components/schemas/PlatformMetaLinkedIn'
        - $ref: '#/components/schemas/PlatformMetaGoogleBusiness'
        - $ref: '#/components/schemas/PlatformMetaNone'
    Post:
      type: object
      description: >-
        A post on one channel. Posts created together from several channels are
        independent posts that share a `post_group_id`.
      properties:
        id:
          type: string
          format: uuid
        post_group_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Shared by the posts created in one batch.
        author:
          oneOf:
            - $ref: '#/components/schemas/Person'
            - type: 'null'
        content:
          type:
            - string
            - 'null'
          description: >-
            Post text, stored as sent (posts written in the app hold the
            editor's HTML).
        media:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/MediaItem'
        status:
          type: string
          enum:
            - draft
            - pending_approval
            - scheduled
            - publishing
            - published
            - failed
          description: >-
            Lifecycle of the post in TryPost. `pending_approval` is a post a
            member who needs approval asked to schedule or publish. The outcome
            on the network is `publish_status`.
        schedule_mode:
          type:
            - string
            - 'null'
          enum:
            - queue
            - custom
            - null
          description: >-
            `queue`: the post holds a slot of the channel's posting schedule.
            `custom`: it is scheduled at its own time.
        scheduled_at:
          type:
            - string
            - 'null'
          description: UTC, format `Y-m-d H:i:s`.
        published_at:
          type:
            - string
            - 'null'
          description: UTC, format `Y-m-d H:i:s`.
        approval_requested_by:
          oneOf:
            - $ref: '#/components/schemas/Person'
            - type: 'null'
          description: Who asked for approval (not always the author).
        approval_requested_at:
          type:
            - string
            - 'null'
          description: UTC, format `Y-m-d H:i:s`.
        approved_by:
          oneOf:
            - $ref: '#/components/schemas/Person'
            - type: 'null'
        approved_at:
          type:
            - string
            - 'null'
          description: UTC, format `Y-m-d H:i:s`.
        recurrence:
          type:
            - object
            - 'null'
          description: Repeat rule, or `null`.
          properties:
            interval:
              type: integer
            frequency:
              type: string
              enum:
                - day
                - week
                - month
                - year
            remaining:
              type:
                - integer
                - 'null'
              description: Repeats left after the next one.
        origin:
          type: string
          enum:
            - trypost
            - network
          description: >-
            `network` for posts imported from the network (published outside
            TryPost).
        publish_status:
          type: string
          enum:
            - pending
            - publishing
            - retrying
            - pending_review
            - published
            - failed
            - rejected
          description: >-
            Publishing state on the network. `pending` until the post is sent;
            `retrying` waits for a retry after a network limit or a temporary
            network problem (such as a LinkedIn post not yet ready for its
            comment); `pending_review` and `rejected` come from networks that
            review posts (Google Business).
        platform:
          oneOf:
            - $ref: '#/components/schemas/Platform'
            - type: 'null'
          description: Network of the post's channel.
        content_type:
          oneOf:
            - $ref: '#/components/schemas/ContentType'
            - type: 'null'
        meta:
          type:
            - object
            - array
            - 'null'
          maxItems: 0
          description: >-
            Stored per-network settings (see `PlatformMeta`). Empty settings may
            serialize as an empty array.
        platform_url:
          type:
            - string
            - 'null'
          description: Link to the published post on the network.
        error_message:
          type:
            - string
            - 'null'
          description: Why publishing failed, when it did.
        display_name:
          type:
            - string
            - 'null'
          description: Account name, kept even after the account is disconnected.
        display_username:
          type:
            - string
            - 'null'
        display_avatar:
          type:
            - string
            - 'null'
        social_account:
          oneOf:
            - $ref: '#/components/schemas/SocialAccount'
            - type: 'null'
          description: >-
            The account, or `null` once it was removed (the `display_*` fields
            keep its name).
        labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
        created_at:
          type: string
          description: UTC, format `Y-m-d H:i:s`.
        updated_at:
          type: string
          description: UTC, format `Y-m-d H:i:s`.
      examples:
        - id: 9d3c1f2a-6b4e-4c8a-9f1e-2a7b5c8d0e41
          post_group_id: 9d3c1f29-e0a1-4b7c-8d2e-5f6a7b8c9d03
          author:
            id: 9b1e2d3c-4f5a-4b6c-8d7e-9f0a1b2c3d4e
            name: Ana Souza
          content: We just shipped scheduled threads. Here is how they work.
          media:
            - id: 9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f
              path: medias/9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f.jpg
              url: >-
                https://media.trypost.it/medias/9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f.jpg
              type: image
              mime_type: image/jpeg
              original_filename: launch.jpg
              size: 482113
              meta:
                width: 1080
                height: 1350
                alt_text: Product launch banner
          status: scheduled
          schedule_mode: custom
          scheduled_at: '2026-10-12 14:00:00'
          published_at: null
          approval_requested_by: null
          approval_requested_at: null
          approved_by: null
          approved_at: null
          recurrence: null
          origin: trypost
          publish_status: pending
          platform: x
          content_type: x_post
          meta:
            thread_replies:
              - text: 2/ Replies publish under the first post.
                media: []
          platform_url: null
          error_message: null
          display_name: TryPost
          display_username: trypostit
          display_avatar: >-
            https://pbs.twimg.com/profile_images/1790000000000000000/avatar_400x400.jpg
          social_account:
            id: 9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54
            platform: x
            display_name: TryPost
            username: trypostit
            status: connected
            has_posting_schedule: true
            timezone: America/Sao_Paulo
            posting_goal: 5
            max_content_length: 280
            long_posts: false
            verified_badge: null
          labels:
            - id: 9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f
              name: Launch
              color: '#2563EB'
              created_at: '2026-09-01 10:00:00'
              updated_at: '2026-09-01 10:00:00'
          created_at: '2026-10-08 13:20:11'
          updated_at: '2026-10-08 13:20:11'
    MediaItemMeta:
      type: object
      description: >-
        Editable settings of one media item. Other keys the server measured (for
        example `width`, `height`, `duration`) may also appear in responses.
      properties:
        alt_text:
          type: string
          maxLength: 2000
          description: >-
            Accessibility description. Applies to images; each network truncates
            it to its own cap.
        user_tags:
          type: array
          maxItems: 20
          description: People tagged on an Instagram image.
          items:
            type: object
            required:
              - username
              - x
              - 'y'
            properties:
              username:
                type: string
                pattern: ^@?[A-Za-z0-9._]{1,30}$
                description: Public Instagram username. A leading `@` is dropped.
              x:
                type: number
                minimum: 0
                maximum: 1
                description: Offset from the left edge, 0 to 1.
              'y':
                type: number
                minimum: 0
                maximum: 1
                description: Offset from the top edge, 0 to 1.
        cover_offset_ms:
          type: integer
          minimum: 0
          description: >-
            Video frame used as the cover, in milliseconds from the start.
            Cannot pass the end of the video.
    PlatformMetaX:
      type: object
      title: X
      description: Settings for `x_post` and `x_poll`.
      properties:
        thread_replies:
          type:
            - array
            - 'null'
          maxItems: 24
          description: >-
            Up to 24 replies published under the post as a thread. Each item is
            a `ThreadReply`, or a plain string for a text-only reply. On update
            this list replaces the stored one. On X a reply can be a poll:
            `{text, poll}` with no media.
          items:
            oneOf:
              - type: string
                maxLength: 25000
                title: Text-only reply
              - $ref: '#/components/schemas/ThreadReply'
        is_ai_generated:
          type: boolean
          description: >-
            Discloses AI-generated media on the post (sent to X as
            `made_with_ai`).
        poll:
          oneOf:
            - $ref: '#/components/schemas/XPoll'
            - type: 'null'
          description: >-
            `x_poll` only: the poll's choices and length. Dropped on any other
            content type. On update it is merged with the stored poll.
    PlatformMetaBluesky:
      type: object
      title: Bluesky
      description: Settings for `bluesky_post`.
      properties:
        thread_replies:
          type:
            - array
            - 'null'
          maxItems: 24
          description: >-
            Up to 24 replies published under the post as a thread. Each item is
            a `ThreadReply`, or a plain string for a text-only reply. On update
            this list replaces the stored one.
          items:
            oneOf:
              - type: string
                maxLength: 25000
                title: Text-only reply
              - $ref: '#/components/schemas/ThreadReply'
        link_preview:
          type: boolean
          default: true
          description: >-
            Send `false` (a real boolean) to publish a text post with a link
            without its preview card.
    PlatformMetaMastodon:
      type: object
      title: Mastodon
      description: Settings for `mastodon_post`.
      properties:
        thread_replies:
          type:
            - array
            - 'null'
          maxItems: 24
          description: >-
            Up to 24 replies published under the post as a thread. Each item is
            a `ThreadReply`, or a plain string for a text-only reply. On update
            this list replaces the stored one.
          items:
            oneOf:
              - type: string
                maxLength: 25000
                title: Text-only reply
              - $ref: '#/components/schemas/ThreadReply'
        spoiler_text:
          type:
            - string
            - 'null'
          maxLength: 500
          description: Content warning. Counts toward the 500-character post limit.
    PlatformMetaTikTok:
      type: object
      title: TikTok
      description: >-
        Settings for `tiktok_video` and `tiktok_photo`. `privacy_level` is
        required to schedule or publish; read the allowed values from `GET
        /social-accounts/{account}/tiktok-creator-info` and keep
        `allow_comments`, `allow_duet` and `allow_stitch` false when it reports
        them disabled. `SELF_ONLY` cannot be combined with
        `brand_content_toggle`.
      properties:
        privacy_level:
          type:
            - string
            - 'null'
          enum:
            - PUBLIC_TO_EVERYONE
            - MUTUAL_FOLLOW_FRIENDS
            - FOLLOWER_OF_CREATOR
            - SELF_ONLY
            - null
          description: Who can see the post. Required to schedule or publish.
        allow_comments:
          type: boolean
        allow_duet:
          type: boolean
          description: '`tiktok_video` only.'
        allow_stitch:
          type: boolean
          description: '`tiktok_video` only.'
        is_aigc:
          type: boolean
          description: AI-generated content label. `tiktok_video` only.
        auto_add_music:
          type: boolean
          description: '`tiktok_photo` only.'
        disclose:
          type: boolean
          description: Commercial content disclosure.
        brand_content_toggle:
          type: boolean
          description: Paid partnership.
        brand_organic_toggle:
          type: boolean
          description: Promotes your own brand.
    PlatformMetaPinterest:
      type: object
      title: Pinterest
      description: >-
        Settings for `pinterest_pin`, `pinterest_video_pin` and
        `pinterest_carousel`. The pin description is the post content; a video
        pin cover is the media item's `meta.cover_offset_ms`.
      properties:
        board_id:
          type:
            - string
            - 'null'
          description: >-
            Board to pin to. Required to schedule or publish. List boards with
            `GET /social-accounts/{account}/boards` or create one with `POST
            /social-accounts/{account}/boards`.
        title:
          type:
            - string
            - 'null'
          maxLength: 100
        link:
          type:
            - string
            - 'null'
          format: uri
          maxLength: 2048
          description: Destination URL (`http` or `https`).
    PlatformMetaDiscord:
      type: object
      title: Discord
      description: Settings for `discord_message`.
      properties:
        channel_id:
          type:
            - string
            - 'null'
          description: >-
            Channel to post in. Required to schedule or publish. List channels
            with `GET /social-accounts/{account}/channels`.
        channel_name:
          type:
            - string
            - 'null'
          description: >-
            Read-only: the name of `channel_id`, filled by TryPost from the
            server's channel list when it was read in the last 5 minutes (by the
            app, [List Discord
            channels](/api-reference/social-accounts/list-discord-channels) or
            MCP). A value you send is ignored. Without a cached list the post
            stores no name.
          readOnly: true
        mentions:
          type:
            - array
            - 'null'
          items:
            type: object
            required:
              - token
            properties:
              token:
                type: string
                description: Mention token, for example `@everyone` or `<@&roleId>`.
              label:
                type:
                  - string
                  - 'null'
        embeds:
          type:
            - array
            - 'null'
          maxItems: 10
          items:
            type: object
            properties:
              title:
                type:
                  - string
                  - 'null'
                maxLength: 256
              description:
                type:
                  - string
                  - 'null'
                maxLength: 4096
              url:
                type:
                  - string
                  - 'null'
                format: uri
              image:
                type:
                  - string
                  - 'null'
                format: uri
                description: Image URL.
              color:
                type:
                  - string
                  - 'null'
                pattern: ^#?[0-9A-Fa-f]{6}$
                description: Hex color, `#RRGGBB`.
    PlatformMetaYouTube:
      type: object
      title: YouTube
      description: >-
        Settings for `youtube_short`. A post needs `title` or text to be
        scheduled or published.
      properties:
        title:
          type:
            - string
            - 'null'
          maxLength: 100
          description: >-
            No `<` or `>` (refused even on drafts). Omitted, it is the first
            non-empty line of the text with `<` and `>` removed, cut to 100
            characters.
        description:
          type:
            - string
            - 'null'
          description: >-
            Plain text, at most 5000 bytes. Omit or send `null` to use the post
            content.
        category_id:
          type:
            - string
            - 'null'
          enum:
            - '1'
            - '2'
            - '10'
            - '15'
            - '17'
            - '19'
            - '20'
            - '22'
            - '23'
            - '24'
            - '25'
            - '26'
            - '27'
            - '28'
            - '29'
            - null
          default: '22'
          description: >-
            YouTube category: 1 Film & Animation, 2 Autos & Vehicles, 10 Music,
            15 Pets & Animals, 17 Sports, 19 Travel & Events, 20 Gaming, 22
            People & Blogs, 23 Comedy, 24 Entertainment, 25 News & Politics, 26
            Howto & Style, 27 Education, 28 Science & Technology, 29 Nonprofits
            & Activism. An integer id is accepted and stored as a string.
        privacy_status:
          type:
            - string
            - 'null'
          enum:
            - public
            - unlisted
            - private
            - null
          default: public
        license:
          type:
            - string
            - 'null'
          enum:
            - youtube
            - creativeCommon
            - null
          default: youtube
        notify_subscribers:
          type: boolean
          default: true
        embeddable:
          type: boolean
          default: true
        made_for_kids:
          type: boolean
          default: false
        is_ai_generated:
          type: boolean
          description: Discloses altered or synthetic content.
    PlatformMetaInstagram:
      type: object
      title: Instagram
      description: >-
        Settings for `instagram_feed`, `instagram_reel` and `instagram_story`
        (both `instagram` and `instagram-facebook` accounts). An
        `instagram_feed` post with a single video publishes as a Reel, without
        the Reel-only settings (`share_to_feed`, `trial_graduation`, `audio`).
        People tags are the media item's `meta.user_tags`; a video cover is
        `meta.cover_offset_ms`. A post may carry at most 5 hashtags.
      properties:
        is_ai_generated:
          type: boolean
          description: AI-generated label (feed, reels, stories, carousels).
        share_to_feed:
          type: boolean
          default: true
          description: '`instagram_reel` only: also show the Reel in the profile feed.'
        collaborators:
          type:
            - array
            - 'null'
          maxItems: 3
          items:
            type: string
            pattern: ^@?[A-Za-z0-9._]{1,30}$
          description: >-
            Up to 3 Instagram usernames invited as co-authors of a feed post,
            carousel or Reel (ignored on stories). A leading `@` and duplicates
            are dropped. Each invited account must accept in the Instagram app.
            A username that does not exist fails the post when it publishes. Not
            allowed together with `trial_graduation`.
          example:
            - trypost.it
            - paulocastellano
        trial_graduation:
          type:
            - string
            - 'null'
          enum:
            - MANUAL
            - SS_PERFORMANCE
            - null
          description: >-
            `instagram_reel` only: publish a trial reel, shown to non-followers
            first. `SS_PERFORMANCE` lets Instagram share it with your followers
            when it performs well (after 72 hours); `MANUAL` waits for you to
            share it in the Instagram app. Only works on accounts where
            Instagram offers trial reels. Scheduling or publishing a trial reel
            that has `collaborators` is refused.
        audio:
          type:
            - object
            - 'null'
          description: >-
            `instagram_reel` only, on an `instagram-facebook` account: music for
            the Reel. Get the `id` from [Search Instagram
            audio](/api-reference/social-accounts/search-instagram-audio). Copy
            `title`, `artist`, `cover_url` and `preview_url` from that result
            too, so the app shows the track; when they are missing, the app
            fills them in the first time the post is opened in the composer.
            Scheduling or publishing is refused when `id` is missing, or when
            the account is connected with Instagram's own login (`Music needs an
            Instagram account connected through Facebook.`); a post stored that
            way (for example after the channel was reconnected with Instagram's
            login) fails with the same message when its time comes. Instagram
            does not let you choose which part of the track plays.
          properties:
            id:
              type:
                - string
                - 'null'
              maxLength: 64
              pattern: ^[0-9]+$
              description: >-
                Instagram audio asset id, as a string of digits. A number is
                refused.
            title:
              type:
                - string
                - 'null'
              maxLength: 255
            artist:
              type:
                - string
                - 'null'
              maxLength: 255
            cover_url:
              type:
                - string
                - 'null'
              format: uri
              maxLength: 2048
            preview_url:
              type:
                - string
                - 'null'
              format: uri
              maxLength: 4096
            audio_volume:
              type:
                - integer
                - 'null'
              minimum: 0
              maximum: 100
              default: 100
              description: Music volume.
            video_volume:
              type:
                - integer
                - 'null'
              minimum: 0
              maximum: 100
              default: 100
              description: Volume of the Reel's own sound.
          example:
            id: '1234567890123456'
            title: Grudge
            artist: Olivia Rodrigo
            audio_volume: 40
            video_volume: 100
    PlatformMetaThreads:
      type: object
      title: Threads
      description: >-
        Settings for `threads_post`. Use the content type `threads_ghost_post`
        for a text-only post archived after 24 hours (no media, no topic).
      properties:
        topic_tag:
          type:
            - string
            - 'null'
          description: >-
            Topic, 1 to 50 characters after a leading `#` is dropped, without
            `.` or `&`.
    PlatformMetaFacebook:
      type: object
      title: Facebook
      description: >-
        Settings for `facebook_post`. Facebook reels and stories take no
        settings; stories publish no text.
      properties:
        link_preview:
          type: boolean
          default: true
          description: >-
            Send `false` (a real boolean) to publish a text post with a link
            without its preview card.
    PlatformMetaLinkedIn:
      type: object
      title: LinkedIn
      description: Settings for `linkedin_post` and `linkedin_page_post`.
      properties:
        link_preview:
          type: boolean
          default: true
          description: >-
            Send `false` (a real boolean) to publish a text post with a link
            without its preview card.
        document_title:
          type:
            - string
            - 'null'
          maxLength: 300
          description: Title shown on a PDF document post. Defaults to the file name.
        thread_replies:
          type:
            - array
            - 'null'
          description: >-
            One reply, published as a comment from the same profile or page
            right after the post. Text only, at most 3000 characters, HTML
            handled as in the post. A draft accepts up to 24 replies like any
            thread; scheduling or publishing refuses a second reply, media, an
            empty comment and one over 3000 characters. On update this list
            replaces the stored one.
          items:
            oneOf:
              - type: string
                maxLength: 25000
                title: Comment text
              - $ref: '#/components/schemas/ThreadReply'
          examples:
            - - text: 'Read more: https://trypost.it/blog/threads'
          maxItems: 24
    PlatformMetaGoogleBusiness:
      type: object
      title: Google Business Profile
      description: >-
        Settings for `google_business_post`. An `EVENT` or `OFFER` needs
        `event.title`, `event.start_date` and `event.end_date` (the title is the
        offer title), and cannot end before it starts.
      properties:
        topic_type:
          type:
            - string
            - 'null'
          enum:
            - STANDARD
            - EVENT
            - OFFER
            - null
          default: STANDARD
        call_to_action:
          type:
            - object
            - 'null'
          description: Button on the post. Not on `OFFER`.
          properties:
            action_type:
              type:
                - string
                - 'null'
              enum:
                - NONE
                - BOOK
                - ORDER
                - SHOP
                - LEARN_MORE
                - SIGN_UP
                - CALL
                - null
            url:
              type:
                - string
                - 'null'
              format: uri
              maxLength: 2048
              description: Required unless `action_type` is `NONE` or `CALL`.
        event:
          type:
            - object
            - 'null'
          description: Required on `EVENT` and `OFFER`.
          properties:
            title:
              type:
                - string
                - 'null'
              maxLength: 58
            start_date:
              type:
                - string
                - 'null'
              format: date
              description: '`YYYY-MM-DD`.'
            end_date:
              type:
                - string
                - 'null'
              format: date
              description: '`YYYY-MM-DD`, not before `start_date`.'
            start_time:
              type:
                - string
                - 'null'
              pattern: ^\d{2}:\d{2}$
              description: '`HH:MM`.'
            end_time:
              type:
                - string
                - 'null'
              pattern: ^\d{2}:\d{2}$
              description: '`HH:MM`.'
        offer:
          type:
            - object
            - 'null'
          description: '`OFFER` only.'
          properties:
            coupon_code:
              type:
                - string
                - 'null'
            redeem_online_url:
              type:
                - string
                - 'null'
              format: uri
              maxLength: 2048
            terms_conditions:
              type:
                - string
                - 'null'
              maxLength: 5000
    PlatformMetaNone:
      type: object
      title: Telegram
      description: Telegram (and Facebook reels and stories) take no settings.
      properties: {}
    Person:
      type: object
      description: A workspace member. Only the id and name are exposed.
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
    MediaItem:
      type: object
      description: A media item as stored on a post.
      properties:
        id:
          type: string
          format: uuid
          description: Media id. Pass it as `media[].id` to reuse the file on another post.
        path:
          type: string
          description: Storage path, `medias/{uuid}.{ext}`.
        url:
          type: string
          format: uri
          description: Public URL of the file.
        type:
          type:
            - string
            - 'null'
          enum:
            - image
            - video
            - document
            - null
          description: '`null` on older items stored without a type.'
        mime_type:
          type:
            - string
            - 'null'
        original_filename:
          type:
            - string
            - 'null'
        size:
          type:
            - integer
            - 'null'
          description: Size in bytes.
        meta:
          $ref: '#/components/schemas/MediaItemMeta'
        source:
          type:
            - string
            - 'null'
          enum:
            - ai
            - unsplash
            - google_drive
            - google_photos
            - canva
            - null
          description: >-
            Where the file came from in the app. Present only on items added
            from one of these sources.
        source_meta:
          type:
            - object
            - 'null'
          description: Details from that source. Present only when the source gave any.
      examples:
        - id: 9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f
          path: medias/9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f.jpg
          url: >-
            https://media.trypost.it/medias/9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f.jpg
          type: image
          mime_type: image/jpeg
          original_filename: launch.jpg
          size: 482113
          meta:
            width: 1080
            height: 1350
            alt_text: Product launch banner
    Platform:
      type: string
      enum:
        - linkedin
        - linkedin-page
        - x
        - tiktok
        - youtube
        - facebook
        - instagram
        - instagram-facebook
        - threads
        - pinterest
        - bluesky
        - mastodon
        - telegram
        - discord
        - google_business
      description: >-
        Network of a social account. `linkedin-page` is a LinkedIn company page,
        `instagram-facebook` an Instagram account connected through a Facebook
        Page.
    SocialAccount:
      type: object
      properties:
        id:
          type: string
          format: uuid
        platform:
          $ref: '#/components/schemas/Platform'
        display_name:
          type:
            - string
            - 'null'
        username:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - connected
            - disconnected
            - token_expired
        has_posting_schedule:
          type: boolean
          description: >-
            Whether the channel has posting times. Queueing a post (`queue`)
            needs them.
        timezone:
          type: string
          description: IANA time zone of the channel. Queue slots and recurrence follow it.
        posting_goal:
          type:
            - integer
            - 'null'
          description: Posts per week the channel aims for.
        max_content_length:
          type: integer
          description: >-
            Text limit of this account, in characters. An X account with long
            posts gets 25000.
        long_posts:
          type: boolean
          description: Whether this X account can publish long posts.
        verified_badge:
          type:
            - string
            - 'null'
          enum:
            - blue
            - business
            - government
            - null
          description: >-
            X checkmark; `null` on other networks or unverified accounts. A
            badge alone does not mean long posts: read `long_posts`.
    Label:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        color:
          type: string
          description: Hex color, `#RRGGBB`.
          examples:
            - '#2563EB'
        created_at:
          type: string
          description: UTC, format `Y-m-d H:i:s`.
          examples:
            - '2026-09-01 10:00:00'
        updated_at:
          type: string
          description: UTC, format `Y-m-d H:i:s`.
          examples:
            - '2026-09-01 10:00:00'
    ErrorBody:
      type: object
      properties:
        message:
          type: string
    ValidationErrorBody:
      type: object
      properties:
        message:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
    RateLimitErrorBody:
      type: object
      properties:
        name:
          type: string
          const: rate_limit_exceeded
        message:
          type: string
          examples:
            - Rate limit exceeded. Please retry after 30 seconds.
    ThreadReply:
      type: object
      description: >-
        One reply published under the post as a thread (X, Bluesky and
        Mastodon), or the comment of a LinkedIn post. A reply needs text or
        media, except a poll reply, which needs its text (the question) and
        takes no media, drafts included. Its text must fit the account limit
        (Bluesky 300, Mastodon 500 including the content warning, which every
        reply repeats, X 280 or 25000 for accounts with long posts). Its media
        belongs to this reply only and follows the media rules of a post on that
        network. On X a reply can instead be a poll (`poll`), with its text as
        the question (at most 280 characters) and no media; off X `poll` is
        dropped. On LinkedIn a post takes one reply, published as a comment from
        the same profile or page: text only, up to 3000 characters.
      properties:
        text:
          type:
            - string
            - 'null'
          maxLength: 25000
        media:
          type: array
          maxItems: 4
          description: >-
            Up to 4 media items, each given by `url`, `id` or `upload_token`,
            with optional `meta.alt_text`.
          items:
            $ref: '#/components/schemas/MediaReference'
        poll:
          oneOf:
            - $ref: '#/components/schemas/XPoll'
            - type: 'null'
          description: 'X only: makes this reply a poll.'
      examples:
        - text: 3/ Full changelog below.
          media:
            - url: https://example.com/changelog.png
    XPoll:
      type: object
      description: >-
        An X poll: the post `content` (or the reply `text`) is the question, at
        most 280 characters even on an account with long posts. A poll carries
        no media, drafts included. A draft may lack the choices or the length;
        scheduling or publishing needs at least 2 choices, `duration_minutes`
        and a question. On update, `meta.poll` is merged key by key with the
        stored one and `options` replaces the whole list; a reply's `poll` is
        replaced along with `thread_replies`.
      properties:
        options:
          type:
            - array
            - 'null'
          description: >-
            2 to 4 choices to schedule or publish, each 1 to 25 characters as X
            counts them (an emoji outside the basic plane, such as 🐧, counts
            two). No two the same, compared without case. Blank choices are
            dropped. More than 4, a repeated choice or one over 25 characters is
            refused on every save, drafts included. Length is measured after
            trimming.
          items:
            type: string
        duration_minutes:
          type:
            - integer
            - 'null'
          minimum: 5
          maximum: 10080
          description: >-
            How long voting stays open, from 5 minutes to 7 days. Required to
            schedule or publish; there is no default.
      examples:
        - options:
            - Calendar sync
            - Bulk upload
            - Dark mode
          duration_minutes: 1440
  responses:
    Unauthorized:
      description: >-
        Missing, invalid, revoked or expired API key. Bodies: `Unauthenticated.`
        (no key, or a key that is invalid or revoked), `Token expired.` (past
        its `expires_at`), `Token not found.` and `No workspace selected.` (the
        key is no longer bound to a workspace).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
          example:
            message: Unauthenticated.
    PaymentRequired:
      description: >-
        TryPost Cloud only: the workspace's account has no active subscription
        or trial. Body: `{"message": "Active subscription required."}`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
          example:
            message: Active subscription required.
    Forbidden:
      description: >-
        The request is not allowed. API keys work only for workspace admins (the
        account owner or a member marked as admin): otherwise every request
        returns `Insufficient workspace permissions.`. Other bodies: `Workspace
        access denied.` (the key's user left the workspace) and `Personal access
        token required.` (an MCP OAuth token was sent) and `This action is
        unauthorized.` (the note belongs to another member).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
    Conflict:
      description: >-
        Another change to this post or its channel's queue is in progress.
        Retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
    ValidationError:
      description: Validation failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorBody'
    TooManyRequests:
      description: 'Rate limit exceeded. Limits: 60 requests per minute per workspace.'
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitErrorBody'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Workspace API key from Settings → API Keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.