Publer Media API

openapi: 3.0.1
info:
  title: Publer 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
paths:
  /workspaces:
    get:
      operationId: listWorkspaces
      tags:
        - Workspaces
      summary: List workspaces
      description: >-
        Retrieves a list of all workspaces that the authenticated user has
        access to.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Workspace'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /accounts:
    get:
      operationId: listAccounts
      tags:
        - Accounts
      summary: List accounts
      description: >-
        Retrieves a list of social media accounts available in the workspace
        specified by the Publer-Workspace-Id header.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Account'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /media:
    get:
      operationId: listMedia
      tags:
        - Media
      summary: List media
      description: >-
        Retrieves a paginated list of media items from the workspace library.
        Supports filtering by type, usage status, and source, and can also
        retrieve specific media items by their IDs.
      parameters:
        - name: ids[]
          in: query
          required: false
          description: >-
            Specific media IDs to retrieve. When set, pagination and other
            filters are ignored.
          schema:
            type: array
            items:
              type: string
        - name: page
          in: query
          required: false
          description: Page number for pagination (0-based).
          schema:
            type: integer
            default: 0
        - name: types[]
          in: query
          required: true
          description: Filter by media type.
          schema:
            type: array
            items:
              type: string
              enum:
                - photo
                - video
                - gif
        - name: used[]
          in: query
          required: true
          description: Filter by usage status.
          schema:
            type: array
            items:
              type: boolean
        - name: source[]
          in: query
          required: false
          description: Filter by media source.
          schema:
            type: array
            items:
              type: string
              enum:
                - canva
                - vista
                - postnitro
                - contentdrips
                - openai
                - favorites
                - upload
        - name: search
          in: query
          required: false
          description: Search term to filter media by name or caption.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Media'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /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'
  /job_status/{job_id}:
    get:
      operationId: getJobStatus
      tags:
        - Jobs
      summary: Get job status
      description: >-
        Monitor an asynchronous operation (such as scheduling or publishing) by
        its job id.
      parameters:
        - name: job_id
          in: path
          required: true
          description: The job id returned by an asynchronous operation.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  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.
  schemas:
    Workspace:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the workspace.
        name:
          type: string
          description: Display name of the workspace.
        owner:
          type: object
          description: Owner details.
          properties:
            id:
              type: string
            email:
              type: string
            name:
              type: string
            first_name:
              type: string
            picture:
              type: string
        members:
          type: array
          description: List of users with access to the workspace.
          items:
            type: object
        plan:
          type: string
          description: Subscription plan for the workspace.
        picture:
          type: string
          description: Workspace logo URL.
    Account:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the account.
        provider:
          type: string
          description: Social network provider.
          enum:
            - bluesky
            - facebook
            - instagram
            - linkedin
            - twitter
            - tiktok
            - youtube
            - pinterest
            - google
            - wordpress
            - telegram
            - mastodon
            - threads
        name:
          type: string
          description: Display name of the social media account.
        social_id:
          type: string
          description: Unique identifier for the account on the social platform.
        picture:
          type: string
          description: URL to the account's avatar/logo.
        type:
          type: string
          description: Account type.
          enum:
            - page
            - profile
            - group
            - business
            - channel
            - location
            - blog
    Media:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the media item.
        type:
          type: string
          description: Media type.
          enum:
            - photo
            - video
            - gif
        url:
          type: string
          description: URL to the media asset.
        name:
          type: string
          description: Name of the media item.
        caption:
          type: string
          description: Caption associated with the media item.
        used:
          type: boolean
          description: Whether the media item has been used.
        source:
          type: string
          description: Source the media item was added from.
    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'
    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.
    JobResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            job_id:
              type: string
              description: Identifier of the asynchronous job to poll.
    JobStatus:
      type: object
      properties:
        status:
          type: string
          description: Current status of the job.
        payload:
          type: object
          description: Result payload of the completed job.
    Error:
      type: object
      properties:
        message:
          type: string
        type:
          type: string
        code:
          type: string
security:
  - api_key: []
    workspace_id: []