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.