Planable
Planable Campaigns API

The Campaigns API from Planable — 5 operation(s). Create, read, update and delete campaigns — named groupings of posts inside a workspace.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.1.0
info:
  title: Planable Public Campaigns 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: Campaigns
paths:
  /campaigns:
    get:
      tags:
      - Campaigns
      summary: List campaigns
      description: Returns campaigns for a workspace with pagination, optionally filtered by status.
      parameters:
      - name: workspaceId
        in: query
        required: true
        schema:
          type: string
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - active
          - archived
          - paused
          - planned
          - completed
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 10
      security:
      - bearerAuth: []
      responses:
        '200':
          description: List of campaigns with pagination
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        workspaceId:
                          type: string
                        name:
                          type: string
                        status:
                          type: string
                          enum:
                          - active
                          - archived
                          - paused
                          - planned
                          - completed
                        icon:
                          type: string
                          enum:
                          - star
                          - bulb
                          - calendar
                          - apple
                          - gift
                          - christmasTree
                          - glass
                          - eggCracked
                          - archive
                          - ghost
                          - cross
                          - candle
                          - home
                          - briefcase
                          - school
                          - camera
                          - bike
                          - bell
                          - barbell
                          - barrier
                          - paint
                          - bolt
                          - heart
                          - babyCarriage
                          - trophy
                          - award
                          - paw
                          - bone
                          - creditCard
                          - discount
                          - shield
                          - tag
                          - thumbUp
                          - thumbDown
                          - umbrella
                          - flag
                          - sun
                          - campfire
                          - seeding
                          - leaf
                          - cherry
                          - macro
                          - clover
                          - pumpkin
                          - flame
                          - cactus
                          - globe
                          - stack
                          - basketball
                          - baseball
                          - ball
                          - gasPump
                          - car
                          - balloon
                          - mug
                          - location
                          - analyze
                          - chartPie
                          - chartDots
                          - cards
                          - mail
                          - headphones
                          - microphone
                          - key
                        color:
                          type: string
                        startedAt:
                          type:
                          - string
                          - 'null'
                          format: date-time
                        endedAt:
                          type:
                          - string
                          - 'null'
                          format: date-time
                        description:
                          type: string
                        links:
                          type: array
                          items:
                            type: object
                            properties:
                              url:
                                type: string
                              title:
                                type:
                                - string
                                - 'null'
                            required:
                            - url
                            - title
                        createdAt:
                          type: string
                          format: date-time
                      required:
                      - id
                      - workspaceId
                      - name
                      - status
                      - icon
                      - color
                      - startedAt
                      - endedAt
                      - links
                      - createdAt
                  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:
      - Campaigns
      summary: Create a campaign
      description: Creates a campaign in a workspace. `description` is supplied as plain text and stored
        as rich text. Subject to the workspace campaign plan limit.
      security:
      - bearerAuth:
        - write
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                workspaceId:
                  type: string
                  minLength: 1
                name:
                  type: string
                  minLength: 1
                  maxLength: 80
                status:
                  type: string
                  enum:
                  - active
                  - archived
                  - paused
                  - planned
                  - completed
                  default: planned
                icon:
                  type: string
                  enum:
                  - star
                  - bulb
                  - calendar
                  - apple
                  - gift
                  - christmasTree
                  - glass
                  - eggCracked
                  - archive
                  - ghost
                  - cross
                  - candle
                  - home
                  - briefcase
                  - school
                  - camera
                  - bike
                  - bell
                  - barbell
                  - barrier
                  - paint
                  - bolt
                  - heart
                  - babyCarriage
                  - trophy
                  - award
                  - paw
                  - bone
                  - creditCard
                  - discount
                  - shield
                  - tag
                  - thumbUp
                  - thumbDown
                  - umbrella
                  - flag
                  - sun
                  - campfire
                  - seeding
                  - leaf
                  - cherry
                  - macro
                  - clover
                  - pumpkin
                  - flame
                  - cactus
                  - globe
                  - stack
                  - basketball
                  - baseball
                  - ball
                  - gasPump
                  - car
                  - balloon
                  - mug
                  - location
                  - analyze
                  - chartPie
                  - chartDots
                  - cards
                  - mail
                  - headphones
                  - microphone
                  - key
                color:
                  type: string
                startedAt:
                  type: string
                  format: date-time
                endedAt:
                  type: string
                  format: date-time
                description:
                  type: string
                links:
                  type: array
                  items:
                    type: object
                    properties:
                      url:
                        type: string
                        minLength: 1
                      title:
                        type: string
                    required:
                    - url
              required:
              - workspaceId
              - name
      responses:
        '201':
          description: Campaign created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      workspaceId:
                        type: string
                      name:
                        type: string
                      status:
                        type: string
                        enum:
                        - active
                        - archived
                        - paused
                        - planned
                        - completed
                      icon:
                        type: string
                        enum:
                        - star
                        - bulb
                        - calendar
                        - apple
                        - gift
                        - christmasTree
                        - glass
                        - eggCracked
                        - archive
                        - ghost
                        - cross
                        - candle
                        - home
                        - briefcase
                        - school
                        - camera
                        - bike
                        - bell
                        - barbell
                        - barrier
                        - paint
                        - bolt
                        - heart
                        - babyCarriage
                        - trophy
                        - award
                        - paw
                        - bone
                        - creditCard
                        - discount
                        - shield
                        - tag
                        - thumbUp
                        - thumbDown
                        - umbrella
                        - flag
                        - sun
                        - campfire
                        - seeding
                        - leaf
                        - cherry
                        - macro
                        - clover
                        - pumpkin
                        - flame
                        - cactus
                        - globe
                        - stack
                        - basketball
                        - baseball
                        - ball
                        - gasPump
                        - car
                        - balloon
                        - mug
                        - location
                        - analyze
                        - chartPie
                        - chartDots
                        - cards
                        - mail
                        - headphones
                        - microphone
                        - key
                      color:
                        type: string
                      startedAt:
                        type:
                        - string
                        - 'null'
                        format: date-time
                      endedAt:
                        type:
                        - string
                        - 'null'
                        format: date-time
                      description:
                        type: string
                      links:
                        type: array
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                            title:
                              type:
                              - string
                              - 'null'
                          required:
                          - url
                          - title
                      createdAt:
                        type: string
                        format: date-time
                    required:
                    - id
                    - workspaceId
                    - name
                    - status
                    - icon
                    - color
                    - startedAt
                    - endedAt
                    - links
                    - createdAt
                required:
                - data
        '400':
          description: Validation error
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Campaign limit reached or insufficient permissions
        '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'
  /campaigns/{id}:
    get:
      tags:
      - Campaigns
      summary: Get campaign detail
      description: Returns a single campaign by ID.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Campaign detail
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      workspaceId:
                        type: string
                      name:
                        type: string
                      status:
                        type: string
                        enum:
                        - active
                        - archived
                        - paused
                        - planned
                        - completed
                      icon:
                        type: string
                        enum:
                        - star
                        - bulb
                        - calendar
                        - apple
                        - gift
                        - christmasTree
                        - glass
                        - eggCracked
                        - archive
                        - ghost
                        - cross
                        - candle
                        - home
                        - briefcase
                        - school
                        - camera
                        - bike
                        - bell
                        - barbell
                        - barrier
                        - paint
                        - bolt
                        - heart
                        - babyCarriage
                        - trophy
                        - award
                        - paw
                        - bone
                        - creditCard
                        - discount
                        - shield
                        - tag
                        - thumbUp
                        - thumbDown
                        - umbrella
                        - flag
                        - sun
                        - campfire
                        - seeding
                        - leaf
                        - cherry
                        - macro
                        - clover
                        - pumpkin
                        - flame
                        - cactus
                        - globe
                        - stack
                        - basketball
                        - baseball
                        - ball
                        - gasPump
                        - car
                        - balloon
                        - mug
                        - location
                        - analyze
                        - chartPie
                        - chartDots
                        - cards
                        - mail
                        - headphones
                        - microphone
                        - key
                      color:
                        type: string
                      startedAt:
                        type:
                        - string
                        - 'null'
                        format: date-time
                      endedAt:
                        type:
                        - string
                        - 'null'
                        format: date-time
                      description:
                        type: string
                      links:
                        type: array
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                            title:
                              type:
                              - string
                              - 'null'
                          required:
                          - url
                          - title
                      createdAt:
                        type: string
                        format: date-time
                    required:
                    - id
                    - workspaceId
                    - name
                    - status
                    - icon
                    - color
                    - startedAt
                    - endedAt
                    - links
                    - createdAt
                required:
                - data
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Campaign 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'
    patch:
      tags:
      - Campaigns
      summary: Update a campaign
      description: Partially updates a campaign. Any subset of the create fields may be provided.
      security:
      - bearerAuth:
        - write
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 80
                status:
                  type: string
                  enum:
                  - active
                  - archived
                  - paused
                  - planned
                  - completed
                icon:
                  type: string
                  enum:
                  - star
                  - bulb
                  - calendar
                  - apple
                  - gift
                  - christmasTree
                  - glass
                  - eggCracked
                  - archive
                  - ghost
                  - cross
                  - candle
                  - home
                  - briefcase
                  - school
                  - camera
                  - bike
                  - bell
                  - barbell
                  - barrier
                  - paint
                  - bolt
                  - heart
                  - babyCarriage
                  - trophy
                  - award
                  - paw
                  - bone
                  - creditCard
                  - discount
                  - shield
                  - tag
                  - thumbUp
                  - thumbDown
                  - umbrella
                  - flag
                  - sun
                  - campfire
                  - seeding
                  - leaf
                  - cherry
                  - macro
                  - clover
                  - pumpkin
                  - flame
                  - cactus
                  - globe
                  - stack
                  - basketball
                  - baseball
                  - ball
                  - gasPump
                  - car
                  - balloon
                  - mug
                  - location
                  - analyze
                  - chartPie
                  - chartDots
                  - cards
                  - mail
                  - headphones
                  - microphone
                  - key
                color:
                  type: string
                startedAt:
                  type: string
                  format: date-time
                endedAt:
                  type: string
                  format: date-time
                description:
                  type: string
                links:
                  type: array
                  items:
                    type: object
                    properties:
                      url:
                        type: string
                        minLength: 1
                      title:
                        type: string
                    required:
                    - url
      responses:
        '200':
          description: Campaign updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      workspaceId:
                        type: string
                      name:
                        type: string
                      status:
                        type: string
                        enum:
                        - active
                        - archived
                        - paused
                        - planned
                        - completed
                      icon:
                        type: string
                        enum:
                        - star
                        - bulb
                        - calendar
                        - apple
                        - gift
                        - christmasTree
                        - glass
                        - eggCracked
                        - archive
                        - ghost
                        - cross
                        - candle
                        - home
                        - briefcase
                        - school
                        - camera
                        - bike
                        - bell
                        - barbell
                        - barrier
                        - paint
                        - bolt
                        - heart
                        - babyCarriage
                        - trophy
                        - award
                        - paw
                        - bone
                        - creditCard
                        - discount
                        - shield
                        - tag
                        - thumbUp
                        - thumbDown
                        - umbrella
                        - flag
                        - sun
                        - campfire
                        - seeding
                        - leaf
                        - cherry
                        - macro
                        - clover
                        - pumpkin
                        - flame
                        - cactus
                        - globe
                        - stack
                        - basketball
                        - baseball
                        - ball
                        - gasPump
                        - car
                        - balloon
                        - mug
                        - location
                        - analyze
                        - chartPie
                        - chartDots
                        - cards
                        - mail
                        - headphones
                        - microphone
                        - key
                      color:
                        type: string
                      startedAt:
                        type:
                        - string
                        - 'null'
                        format: date-time
                      endedAt:
                        type:
                        - string
                        - 'null'
                        format: date-time
                      description:
                        type: string
                      links:
                        type: array
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                            title:
                              type:
                              - string
                              - 'null'
                          required:
                          - url
                          - title
                      createdAt:
                        type: string
                        format: date-time
                    required:
                    - id
                    - workspaceId
                    - name
                    - status
                    - icon
                    - color
                    - startedAt
                    - endedAt
                    - links
                    - createdAt
                required:
                - data
        '400':
          description: Validation error
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
        '404':
          description: Campaign 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'
    delete:
      tags:
      - Campaigns
      summary: Delete a campaign
      description: Deletes a campaign and detaches it from its posts. Posts are kept; only the `campaignId`
        link is removed.
      security:
      - bearerAuth:
        - write
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Campaign deleted
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
        '404':
          description: Campaign 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'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: pln_*
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - VALIDATION_ERROR
              - UNAUTHORIZED
              - FORBIDDEN
              - NOT_FOUND
              - METHOD_NOT_ALLOWED
              - RATE_LIMITED
              - POST_ALREADY_PUBLISHED
              - PUBLISHING_IN_PROGRESS
              - WORKSPACE_LIMIT_REACHED
              - INTERNAL
            message:
              type: string
            requestId:
              type: string
          required:
          - code
          - message
          - requestId
      required:
      - error
Planable Campaigns API

Documentation

Specifications

Other Resources

OpenAPI Specification
