OpenAPI Specification
openapi: 3.0.1
info:
title: Postiz Public Analytics Posts API
description: Public REST API for Postiz, the open-source social media scheduling and management platform. The same API surface is served by Postiz Cloud (https://api.postiz.com/public/v1) and by any self-hosted Postiz instance (https://{your-domain}/api/public/v1). Authenticate by sending your API key in the Authorization header. The API lets you list connected channels (integrations), find scheduling slots, upload media, and create, list, and delete posts across 30+ supported social, video, community, and blogging platforms.
termsOfService: https://postiz.com/terms
contact:
name: Postiz Support
url: https://docs.postiz.com/public-api
license:
name: AGPL-3.0
url: https://github.com/gitroomhq/postiz-app/blob/main/LICENSE
version: '1.0'
servers:
- url: https://api.postiz.com/public/v1
description: Postiz Cloud
- url: https://{your-domain}/api/public/v1
description: Self-hosted
variables:
your-domain:
default: localhost:5000
description: Your Postiz instance domain
security:
- ApiKeyAuth: []
tags:
- name: Posts
description: Create, schedule, list, and delete posts.
paths:
/posts:
get:
tags:
- Posts
summary: List posts
description: Get posts within a date range.
operationId: listPosts
parameters:
- name: startDate
in: query
required: true
description: Start date in UTC ISO format.
schema:
type: string
format: date-time
example: '2024-12-01T00:00:00.000Z'
- name: endDate
in: query
required: true
description: End date in UTC ISO format.
schema:
type: string
format: date-time
example: '2024-12-31T23:59:59.000Z'
- name: customer
in: query
required: false
description: Filter by customer ID.
schema:
type: string
responses:
'200':
description: List of posts
content:
application/json:
schema:
$ref: '#/components/schemas/PostsResponse'
post:
tags:
- Posts
summary: Create a post
description: Create or schedule a new post. Set type to draft, schedule, or now. Each social media platform has its own settings schema selected via the settings.__type discriminator.
operationId: createPost
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePostRequest'
example:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-integration-id
value:
- content: Hello from the Postiz API!
image: []
settings:
__type: bluesky
responses:
'200':
description: Post created
content:
application/json:
schema:
$ref: '#/components/schemas/PostsResponse'
/posts/{id}:
delete:
tags:
- Posts
summary: Delete a post
description: Deletes a post by ID. A 404 means the post is already deleted and is safe to ignore.
operationId: deletePost
parameters:
- name: id
in: path
required: true
description: Post ID
schema:
type: string
responses:
'200':
description: Post deleted
/posts/group/{group}:
delete:
tags:
- Posts
summary: Delete posts by group
description: Deletes all posts that share the given group ID.
operationId: deletePostByGroup
parameters:
- name: group
in: path
required: true
description: Group ID
schema:
type: string
responses:
'200':
description: Posts deleted
/posts/{id}/missing:
get:
tags:
- Posts
summary: Get missing content
description: Returns content fields that still need to be supplied for a post.
operationId: getMissingContent
parameters:
- name: id
in: path
required: true
description: Post ID
schema:
type: string
responses:
'200':
description: Missing content items
/posts/{id}/release-id:
put:
tags:
- Posts
summary: Update release ID
description: Updates the external release identifier associated with a post.
operationId: updateReleaseId
parameters:
- name: id
in: path
required: true
description: Post ID
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
releaseId:
type: string
responses:
'200':
description: Release ID updated
/posts/{id}/status:
put:
tags:
- Posts
summary: Change post status
description: Changes a post's status between draft and schedule.
operationId: changePostStatus
parameters:
- name: id
in: path
required: true
description: Post ID
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- draft
- schedule
responses:
'200':
description: Status changed
components:
schemas:
PostsResponse:
type: object
properties:
posts:
type: array
items:
$ref: '#/components/schemas/Post'
PostContent:
type: object
required:
- content
properties:
content:
type: string
description: Post text content.
id:
type: string
description: Post ID (for updates).
image:
type: array
items:
$ref: '#/components/schemas/Media'
Tag:
type: object
required:
- value
- label
properties:
value:
type: string
label:
type: string
CreatePostRequest:
type: object
required:
- type
- date
- shortLink
- tags
properties:
type:
type: string
enum:
- draft
- schedule
- now
description: Post type.
date:
type: string
format: date-time
description: Publish date in UTC ISO format.
shortLink:
type: boolean
description: Whether to use short links.
order:
type: string
description: Order of posts.
inter:
type: number
description: Interval between posts.
tags:
type: array
items:
$ref: '#/components/schemas/Tag'
posts:
type: array
description: Required if type is not 'draft'.
items:
$ref: '#/components/schemas/PostItem'
PostItem:
type: object
required:
- integration
- value
properties:
integration:
type: object
required:
- id
properties:
id:
type: string
description: Integration ID.
value:
type: array
items:
$ref: '#/components/schemas/PostContent'
group:
type: string
description: Group ID for related posts.
settings:
type: object
description: Platform-specific settings, selected by the __type discriminator (e.g. x, linkedin, instagram, youtube, tiktok, reddit, discord, slack, telegram, mastodon, bluesky, wordpress, medium, devto).
properties:
__type:
type: string
Media:
type: object
required:
- id
- path
properties:
id:
type: string
path:
type: string
Post:
type: object
properties:
id:
type: string
content:
type: string
publishDate:
type: string
format: date-time
releaseURL:
type: string
description: URL of the published post.
state:
type: string
enum:
- QUEUE
- PUBLISHED
- ERROR
- DRAFT
integration:
type: object
properties:
id:
type: string
providerIdentifier:
type: string
name:
type: string
picture:
type: string
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: Your Postiz API key, sent as the raw value of the Authorization header.