openapi: 3.0.1
info:
  title: Publer Accounts Posts API
  description: 'The Publer API (v1) lets Publer Business customers programmatically schedule and publish social media posts, manage connected social accounts and workspaces, work with the media library, and track asynchronous jobs. Authentication uses an API key passed as `Authorization: Bearer-API YOUR_API_KEY` together with a `Publer-Workspace-Id` header. The API is currently available exclusively to Publer Business users.'
  termsOfService: https://publer.com/terms
  contact:
    name: Publer Support
    url: https://publer.com/docs
  version: '1.0'
servers:
- url: https://app.publer.com/api/v1
security:
- api_key: []
  workspace_id: []
tags:
- name: Posts
paths:
  /posts:
    get:
      operationId: listPosts
      tags:
      - Posts
      summary: List posts
      description: Retrieves a list of posts based on the specified filters.
      parameters:
      - name: state
        in: query
        required: false
        description: Filter by a single post state.
        schema:
          type: string
      - name: state[]
        in: query
        required: false
        description: Filter by multiple post states.
        schema:
          type: array
          items:
            type: string
      - name: from
        in: query
        required: false
        description: ISO date/datetime. Required if `to` is used.
        schema:
          type: string
      - name: to
        in: query
        required: false
        description: ISO date/datetime. Required if `from` is used.
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: Page number (default 0).
        schema:
          type: integer
          default: 0
      - name: account_ids[]
        in: query
        required: false
        description: List of account IDs to filter by.
        schema:
          type: array
          items:
            type: string
      - name: query
        in: query
        required: false
        description: Full-text search keyword.
        schema:
          type: string
      - name: postType
        in: query
        required: false
        description: Filter by post type.
        schema:
          type: string
      - name: member_id
        in: query
        required: false
        description: Filter by workspace member.
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Post'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /posts/schedule:
    post:
      operationId: schedulePosts
      tags:
      - Posts
      summary: Schedule posts
      description: Schedule posts for future publication, including drafts. The operation is processed asynchronously and returns a job id to poll for status.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkPostRequest'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /posts/schedule/publish:
    post:
      operationId: publishPosts
      tags:
      - Posts
      summary: Publish posts immediately
      description: Publish content immediately to the connected social networks. The operation is processed asynchronously and returns a job id to poll for status.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkPostRequest'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    BulkPost:
      type: object
      properties:
        networks:
          type: object
          description: Platform-specific content keyed by network provider (for example facebook, instagram, twitter, linkedin).
          additionalProperties:
            type: object
            properties:
              type:
                type: string
                description: Content format.
                enum:
                - status
                - photo
                - video
                - link
                - carousel
                - pdf
              text:
                type: string
                description: Post content.
        accounts:
          type: array
          description: Target accounts with optional scheduling time.
          items:
            type: object
            properties:
              id:
                type: string
                description: Account id to publish to.
              scheduled_at:
                type: string
                format: date-time
                description: Scheduled publication time for this account.
    Error:
      type: object
      properties:
        message:
          type: string
        type:
          type: string
        code:
          type: string
    Post:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the post.
        state:
          type: string
          description: Current state of the post.
        text:
          type: string
          description: Post content text.
        scheduled_at:
          type: string
          format: date-time
          description: Scheduled publication time.
        account_ids:
          type: array
          description: Accounts the post targets.
          items:
            type: string
        postType:
          type: string
          description: Type of the post.
    BulkPostRequest:
      type: object
      required:
      - bulk
      properties:
        bulk:
          type: object
          required:
          - state
          - posts
          properties:
            state:
              type: string
              description: Publishing method / post state.
              enum:
              - scheduled
              - draft
              - draft_private
              - draft_public
              - recurring
            posts:
              type: array
              items:
                $ref: '#/components/schemas/BulkPost'
    JobResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            job_id:
              type: string
              description: Identifier of the asynchronous job to poll.
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key passed as `Authorization: Bearer-API YOUR_API_KEY`. A `Publer-Workspace-Id` header is also required to scope requests to a workspace.'
    workspace_id:
      type: apiKey
      in: header
      name: Publer-Workspace-Id
      description: The id of the workspace to scope the request to.