Planable
Planable Posts API

The Posts API from Planable — 18 operation(s). The core content surface — list, create, read, update and delete posts, create synced cross-platform group posts, manage comments and reactions, request approval, create and revoke public share links, reorder the grid, and pull post metrics.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.1.0
info:
  title: Planable Public Posts API
  version: 1.0.0
  description: 'REST API for managing Planable companies, workspaces, pages, posts and more.


    **Plan eligibility:** new API tokens can only be generated by companies on the **Pro** and **Enterprise**
    plans. Tokens that have already been generated continue to work regardless of plan.'
servers:
- url: https://api.planable.io/api/v1
security:
- bearerAuth: []
tags:
- name: Posts
paths:
  /posts:
    get:
      tags:
      - Posts
      summary: List posts
      description: Returns posts for a workspace with pagination. Each item includes the same post detail
        fields as GET /posts/{id}.
      parameters:
      - name: workspaceId
        in: query
        required: true
        schema:
          type: string
      - name: pageId
        in: query
        required: false
        schema:
          type: string
      - name: campaignId
        in: query
        required: false
        schema:
          type: string
        description: Filter by campaign ID, or `no-campaign` for posts not assigned to any campaign
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
      security:
      - bearerAuth: []
      responses:
        '200':
          description: List of post details with pagination
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        workspaceId:
                          type: string
                        pageId:
                          type: string
                        type:
                          type: string
                        classification:
                          type: string
                        plainText:
                          type: string
                        createdAt:
                          type: string
                          format: date-time
                        gridPosition:
                          type: number
                        campaignId:
                          type:
                          - string
                          - 'null'
                        media:
                          type: array
                          items:
                            type: string
                            format: uri
                          maxItems: 20
                          description: Up to 20 public image or video URLs, each max 100MB. Files are
                            downloaded server-side from the provided URLs.
                        scheduledAt:
                          type:
                          - string
                          - 'null'
                          format: date-time
                        status:
                          type: string
                        approved:
                          type: boolean
                        approvedBy:
                          type: array
                          items:
                            type: object
                            properties:
                              userId:
                                type: string
                              approvedAt:
                                type: string
                                format: date-time
                              levelId:
                                type: string
                            required:
                            - userId
                            - approvedAt
                        approval:
                          type: object
                          properties:
                            status:
                              type: string
                              enum:
                              - NOT_APPLICABLE
                              - NEVER_SENT
                              - PENDING
                              - PARTIALLY_APPROVED
                              - FULLY_APPROVED
                            approved:
                              type: boolean
                            type:
                              type: string
                              enum:
                              - NONE
                              - OPTIONAL
                              - REQUIRED
                              - MULTIPLE
                            completedLevels:
                              type: integer
                              minimum: 0
                            totalLevels:
                              type: integer
                              minimum: 0
                            currentLevelId:
                              type: string
                            levels:
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    type: string
                                  label:
                                    type: string
                                  approved:
                                    type: boolean
                                  approvedBy:
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        userId:
                                          type: string
                                        approvedAt:
                                          type: string
                                          format: date-time
                                        levelId:
                                          type: string
                                      required:
                                      - userId
                                      - approvedAt
                                required:
                                - id
                                - label
                                - approved
                                - approvedBy
                          required:
                          - status
                          - approved
                          - type
                          - completedLevels
                          - totalLevels
                          - levels
                        published:
                          type: boolean
                        scheduledSet:
                          type: boolean
                        teamOnly:
                          type: boolean
                        archived:
                          type: boolean
                        modifiedAt:
                          type: string
                          format: date-time
                        mediaType:
                          type: string
                        videoThumbnailUrl:
                          type: string
                          format: uri
                          description: Current thumbnail (cover) URL of the post video, when the post
                            has a video with a thumbnail.
                        labels:
                          type: array
                          items:
                            type: object
                            properties:
                              uuid:
                                type: string
                              text:
                                type: string
                              color:
                                type: string
                            required:
                            - uuid
                            - text
                            - color
                        commentsCounter:
                          type: number
                        notesCounter:
                          type: number
                        publicShareLink:
                          type: string
                          format: uri
                        publishedPostLink:
                          type: string
                          format: uri
                        groupId:
                          type: string
                        groupPageIds:
                          type: array
                          items:
                            type: string
                        groupSync:
                          type: boolean
                        pinterest:
                          type: object
                          properties:
                            boardId:
                              type: string
                            boardName:
                              type: string
                            title:
                              type:
                              - string
                              - 'null'
                            link:
                              type:
                              - string
                              - 'null'
                            description:
                              type:
                              - string
                              - 'null'
                          required:
                          - boardId
                          - boardName
                          - title
                          - link
                          - description
                      required:
                      - id
                      - workspaceId
                      - pageId
                      - type
                      - classification
                      - plainText
                      - createdAt
                      - campaignId
                      - media
                      - scheduledAt
                      - status
                      - approved
                      - approval
                      - published
                      - scheduledSet
                      - teamOnly
                      - archived
                      - commentsCounter
                      - notesCounter
                  pagination:
                    type: object
                    properties:
                      offset:
                        type: number
                      limit:
                        type: number
                      hasMore:
                        type: boolean
                    required:
                    - offset
                    - limit
                    - hasMore
                required:
                - data
                - pagination
        '400':
          description: Validation error
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
      - Posts
      summary: Create a new post
      description: 'Creates a post in the specified workspace and page. Use `pageId` for a single post
        or `pageIds` to create grouped cross-page posts. When `media` URLs are provided for grouped posts,
        each file is imported into the workspace Media Library once and the same asset is reused across
        every post in the group instead of being copied per platform. The `notify` flag controls whether
        workspace members receive a post-added notification (email/in-app push); set it to `false` to
        suppress those notifications. Internal activity feed entries are always recorded. `notify` is
        not an approval request — use POST /posts/{id}/request-approval to notify approvers. The `media`
        field: Up to 20 public image or video URLs, each max 100MB. Files are downloaded server-side from
        the provided URLs. Use `videoThumbnail` to set a custom video thumbnail (cover); it requires a
        video in `media` that finishes transcoding during the request, otherwise the request returns 400
        after the post is created — in that case, retry via PATCH /posts/{id} once the video is processed.'
      security:
      - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                workspaceId:
                  type: string
                  minLength: 1
                pageId:
                  type: string
                  minLength: 1
                pageIds:
                  type: array
                  items:
                    type: string
                    minLength: 1
                  minItems: 1
                  maxItems: 20
                text:
                  type: string
                  maxLength: 25000
                  default: ''
                gridPosition:
                  type: integer
                  minimum: 0
                scheduledAt:
                  type: string
                  format: date-time
                labels:
                  type: array
                  items:
                    type: string
                  default: []
                media:
                  type: array
                  items:
                    type: string
                    format: uri
                  maxItems: 20
                  default: []
                  description: Up to 20 public image or video URLs, each max 100MB. Files are downloaded
                    server-side from the provided URLs.
                teamOnly:
                  type: boolean
                approved:
                  type: boolean
                approvedBy:
                  type: string
                  minLength: 1
                publishAtScheduledDate:
                  type: boolean
                  default: false
                firstComment:
                  type: string
                  maxLength: 8000
                internalNote:
                  type: string
                  maxLength: 8000
                youtubeTitle:
                  type: string
                  maxLength: 100
                linkedinPdfTitle:
                  type: string
                  maxLength: 150
                  description: LinkedIn PDF carousel title (`linkedinData.pdfTitle`). When set on a LinkedIn
                    post with multiple images, also enables publishing as a PDF document carousel (`linkedinData.publishCarouselAsPdf`).
                    Pass an empty string on PATCH to disable PDF mode and clear the title.
                linkedinVideoTitle:
                  type: string
                  maxLength: 150
                notify:
                  type: boolean
                  default: true
                  description: Controls whether workspace members receive a post-added notification (email/in-app
                    push). This is not an approval request — use POST /posts/{id}/request-approval to
                    notify approvers.
                pinterest:
                  type: object
                  properties:
                    boardId:
                      type: string
                      minLength: 1
                    title:
                      type: string
                      maxLength: 100
                    link:
                      type: string
                      format: uri
                    description:
                      type: string
                      maxLength: 500
                  required:
                  - boardId
                campaignId:
                  anyOf:
                  - type: string
                    minLength: 1
                  - type: 'null'
                  - type: 'null'
                videoThumbnail:
                  type: object
                  properties:
                    imageUrl:
                      type: string
                      format: uri
                      description: Public URL of a static image that is uploaded and set as the video
                        thumbnail (cover).
                    offsetSeconds:
                      type: number
                      minimum: 0
                      description: Offset into the video, in seconds; the frame at this position is extracted
                        and set as the thumbnail.
                  description: Sets a custom thumbnail on the post video (the single video, or the first
                    video for mixed media). Requires the video to be fully transcoded.
              required:
              - workspaceId
      responses:
        '201':
          description: Post created
          content:
            application/json:
              schema:
                type: object
                properties:
                  posts:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        workspaceId:
                          type: string
                        pageId:
                          type: string
                        type:
                          type: string
                        classification:
                          type: string
                        plainText:
                          type: string
                        createdAt:
                          type: string
                          format: date-time
                        gridPosition:
                          type: number
                        campaignId:
                          type:
                          - string
                          - 'null'
                        media:
                          type: array
                          items:
                            type: string
                            format: uri
                          maxItems: 20
                          description: Up to 20 public image or video URLs, each max 100MB. Files are
                            downloaded server-side from the provided URLs.
                        scheduledAt:
                          type:
                          - string
                          - 'null'
                          format: date-time
                        status:
                          type: string
                        approved:
                          type: boolean
                        approvedBy:
                          type: array
                          items:
                            type: object
                            properties:
                              userId:
                                type: string
                              approvedAt:
                                type: string
                                format: date-time
                              levelId:
                                type: string
                            required:
                            - userId
                            - approvedAt
                        approval:
                          type: object
                          properties:
                            status:
                              type: string
                              enum:
                              - NOT_APPLICABLE
                              - NEVER_SENT
                              - PENDING
                              - PARTIALLY_APPROVED
                              - FULLY_APPROVED
                            approved:
                              type: boolean
                            type:
                              type: string
                              enum:
                              - NONE
                              - OPTIONAL
                              - REQUIRED
                              - MULTIPLE
                            completedLevels:
                              type: integer
                              minimum: 0
                            totalLevels:
                              type: integer
                              minimum: 0
                            currentLevelId:
                              type: string
                            levels:
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    type: string
                                  label:
                                    type: string
                                  approved:
                                    type: boolean
                                  approvedBy:
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        userId:
                                          type: string
                                        approvedAt:
                                          type: string
                                          format: date-time
                                        levelId:
                                          type: string
                                      required:
                                      - userId
                                      - approvedAt
                                required:
                                - id
                                - label
                                - approved
                                - approvedBy
                          required:
                          - status
                          - approved
                          - type
                          - completedLevels
                          - totalLevels
                          - levels
                        published:
                          type: boolean
                        scheduledSet:
                          type: boolean
                        teamOnly:
                          type: boolean
                        archived:
                          type: boolean
                        modifiedAt:
                          type: string
                          format: date-time
                        mediaType:
                          type: string
                        videoThumbnailUrl:
                          type: string
                          format: uri
                          description: Current thumbnail (cover) URL of the post video, when the post
                            has a video with a thumbnail.
                        labels:
                          type: array
                          items:
                            type: object
                            properties:
                              uuid:
                                type: string
                              text:
                                type: string
                              color:
                                type: string
                            required:
                            - uuid
                            - text
                            - color
                        commentsCounter:
                          type: number
                        notesCounter:
                          type: number
                        publicShareLink:
                          type: string
                          format: uri
                        publishedPostLink:
                          type: string
                          format: uri
                        groupId:
                          type: string
                        groupPageIds:
                          type: array
                          items:
                            type: string
                        groupSync:
                          type: boolean
                        pinterest:
                          type: object
                          properties:
                            boardId:
                              type: string
                            boardName:
                              type: string
                            title:
                              type:
                              - string
                              - 'null'
                            link:
                              type:
                              - string
                              - 'null'
                            description:
                              type:
                              - string
                              - 'null'
                          required:
                          - boardId
                          - boardName
                          - title
                          - link
                          - description
                      required:
                      - id
                      - workspaceId
                      - pageId
                      - type
                      - classification
                      - plainText
                      - createdAt
                      - campaignId
                      - media
                      - scheduledAt
                      - status
                      - approved
                      - approval
                      - published
                      - scheduledSet
                      - teamOnly
                      - archived
                      - commentsCounter
                      - notesCounter
                required:
                - posts
        '400':
          description: Validation error
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Workspace or page not found
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /posts/{id}:
    get:
      tags:
      - Posts
      summary: Get post detail
      description: Returns a single post by ID including media URLs.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Post detail with media
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      workspaceId:
                        type: string
                      pageId:
                        type: string
                      type:
                        type: string
                      classification:
                        type: string
                      plainText:
                        type: string
                      createdAt:
                        type: string
                        format: date-time
                      gridPosition:
                        type: number
                      campaignId:
                        type:
                        - string
                        - 'null'
                      media:
                        type: array
                        items:
                          type: string
                          format: uri
                        maxItems: 20
                        description: Up to 20 public image or video URLs, each max 100MB. Files are downloaded
                          server-side from the provided URLs.
                      scheduledAt:
                        type:
                        - string
                        - 'null'
                        format: date-time
                      status:
                        type: string
                      approved:
                        type: boolean
                      approvedBy:
                        type: array
                        items:
                          type: object
                          properties:
                            userId:
                              type: string
                            approvedAt:
                              type: string
                              format: date-time
                            levelId:
                              type: string
                          required:
                          - userId
                          - approvedAt
                      approval:
                        type: object
                        properties:
                          status:
                            type: string
                            enum:
                            - NOT_APPLICABLE
                            - NEVER_SENT
                            - PENDING
                            - PARTIALLY_APPROVED
                            - FULLY_APPROVED
                          approved:
                            type: boolean
                          type:
                            type: string
                            enum:
                            - NONE
                            - OPTIONAL
                            - REQUIRED
                            - MULTIPLE
                          completedLevels:
                            type: integer
                            minimum: 0
                          totalLevels:
                            type: integer
                            minimum: 0
                          currentLevelId:
                            type: string
                          levels:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                label:
                                  type: string
                                approved:
                                  type: boolean
                                approvedBy:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      userId:
                                        type: string
                                      approvedAt:
                                        type: string
                                        format: date-time
                                      levelId:
                                        type: string
                                    required:
                                    - userId
                                    - approvedAt
                              required:
                              - id
                              - label
                              - approved
                              - approvedBy
                        required:
                        - status
                        - approved
                        - type
                        - completedLevels
                        - totalLevels
                        - levels
                      published:
                        type: boolean
                      scheduledSet:
                        type: boolean
                      teamOnly:
                        type: boolean
                      archived:
                        type: b

# --- truncated at 32 KB (85 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/planable/refs/heads/main/openapi/planable-posts-api-openapi.yml
Planable Posts API

Documentation

Specifications

Other Resources

OpenAPI Specification
