openapi: 3.0.1
info:
  title: Publer Accounts Media 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: Media
paths:
  /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'
components:
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
        type:
          type: string
        code:
          type: string
    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.
  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.