The Stories API from Planable — 1 operation(s). Create single-frame or multi-frame Instagram and Facebook stories.
openapi: 3.1.0
info:
title: Planable Public Stories 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: Stories
paths:
/stories:
post:
tags:
- Stories
summary: Create a story (single or multi-frame)
description: Creates a story on a story-capable page (Instagram and Facebook). Provide `media` as
a single URL for a one-frame story, or as an array of URLs (max 20) to create a multi-frame story
group (one frame per URL, in order). When a multi-frame story is created the response also includes
`posts` (every frame, in order) and `group` (the shared story-group id and its post ids). GIFs
are not supported. Media is processed asynchronously, so the `media` URL is typically `null` in
this response while the upload is still processing — use `mediaId` with GET /media/{id} (or re-fetch
the story) to poll `mediaStatus` until it is `success`, at which point the URL becomes available.
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.
security:
- bearerAuth:
- write
requestBody:
content:
application/json:
schema:
type: object
properties:
workspaceId:
type: string
minLength: 1
pageId:
type: string
minLength: 1
media:
anyOf:
- type: string
format: uri
- type: array
items:
type: string
format: uri
minItems: 1
maxItems: 20
description: A single media URL creates a one-frame story. An array of media URLs (max
20) creates a multi-frame story group — one frame per URL, in order. GIFs are not
supported.
stickers:
type: array
items:
type: object
properties:
type:
type: string
enum:
- text
- location
- link
- music
- mention
- hashtags
- questions
- notes
- fundraiser
- feelings
- other
value:
type: string
required:
- type
- value
default: []
scheduledAt:
type: string
format: date-time
labels:
type: array
items:
type: string
default: []
teamOnly:
type: boolean
approved:
type: boolean
approvedBy:
type: string
minLength: 1
publishAtScheduledDate:
type: boolean
default: false
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.
internalNote:
type: string
maxLength: 8000
required:
- workspaceId
- pageId
- media
responses:
'201':
description: Story created
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
enum:
- story
media:
type:
- string
- 'null'
format: uri
mediaId:
type:
- string
- 'null'
description: Media library id of the attached media. Use with GET /media/{id}
to poll its processing status.
mediaStatus:
type:
- string
- 'null'
enum:
- uploading
- processing
- error
- success
description: Processing status of the attached media. The `media` URL is only
populated once this is `success`.
scheduledAt:
type:
- string
- 'null'
format: date-time
scheduledSet:
type: boolean
status:
type: string
approved:
type: boolean
approvedBy:
type: array
items:
type: object
properties:
userId:
type: string
approvedAt:
type: string
format: date-time
required:
- userId
- approvedAt
createdAt:
type: string
format: date-time
required:
- id
- workspaceId
- pageId
- type
- classification
- media
- mediaId
- mediaStatus
- scheduledAt
- scheduledSet
- status
- approved
- createdAt
posts:
type: array
items:
type: object
properties:
id:
type: string
workspaceId:
type: string
pageId:
type: string
type:
type: string
classification:
type: string
enum:
- story
media:
type:
- string
- 'null'
format: uri
mediaId:
type:
- string
- 'null'
description: Media library id of the attached media. Use with GET /media/{id}
to poll its processing status.
mediaStatus:
type:
- string
- 'null'
enum:
- uploading
- processing
- error
- success
description: Processing status of the attached media. The `media` URL is only
populated once this is `success`.
scheduledAt:
type:
- string
- 'null'
format: date-time
scheduledSet:
type: boolean
status:
type: string
approved:
type: boolean
approvedBy:
type: array
items:
type: object
properties:
userId:
type: string
approvedAt:
type: string
format: date-time
required:
- userId
- approvedAt
createdAt:
type: string
format: date-time
required:
- id
- workspaceId
- pageId
- type
- classification
- media
- mediaId
- mediaStatus
- scheduledAt
- scheduledSet
- status
- approved
- createdAt
group:
type: object
properties:
id:
type: string
postIds:
type: array
items:
type: string
required:
- id
- postIds
required:
- data
'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'
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