Publer

Publer Media API

The Media API from Publer — 3 operations for the workspace media library: list and filter photos, videos and GIFs by type, usage, source and search term, upload a file directly as multipart, or upload asynchronously from a remote URL.

GitHub OpenAPI

Documentation

📖
Documentation
https://publer.com/docs/api-reference/media
📖
APIReference
https://publer.com/docs/api-reference/introduction

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/publer/refs/heads/main/openapi/publer-media-api-openapi.yml

Other Resources

🔗
Overlay
https://raw.githubusercontent.com/api-evangelist/publer/refs/heads/main/overlays/publer-media-overlay.yaml
🔗
PostmanCollection
https://raw.githubusercontent.com/api-evangelist/publer/refs/heads/main/collections/publer.postman_collection.json
🔗
OpenCollection
https://raw.githubusercontent.com/api-evangelist/publer/refs/heads/main/collections/publer.opencollection.json

OpenAPI Specification

publer-media-api-openapi.yml Raw ↑ 
openapi: 3.1.1
info:
  title: Publer Media API
  description: 'The Publer API (v1) is a RESTful JSON interface for automating social media workflows
    - scheduling, publishing, media management and analytics - across Facebook, Instagram, X/Twitter,
    LinkedIn, TikTok, YouTube, Pinterest, Threads, Bluesky, Mastodon, Google Business Profiles, WordPress
    and Telegram. Authentication is an API key sent as `Authorization: Bearer-API YOUR_API_KEY` together
    with a `Publer-Workspace-Id` header. The API is available exclusively to Publer Business users.'
  termsOfService: https://publer.com/terms
  contact:
    name: Publer Support
    email: support@publer.com
    url: https://publer.com/docs
  version: 1.0.0
servers:
- url: https://app.publer.com/api/v1
security:
- BearerApiAuth: []
tags:
- name: Media
  description: Endpoints for uploading and managing media files
paths:
  /media:
    get:
      summary: List Media
      description: Retrieves a paginated list of media items from the user's library. The endpoint supports
        filtering by various parameters and can also retrieve specific media items by their IDs.
      tags:
      - Media
      parameters:
      - schema:
          type: string
        name: Publer-Workspace-Id
        in: header
        description: ID of the workspace to retrieve media from
        required: true
      - schema:
          type: array
          items:
            type: string
        style: form
        explode: false
        name: ids
        in: query
        description: Specific media IDs to retrieve. If provided, pagination and other filters are ignored
        required: false
      - schema:
          type: integer
        name: page
        in: query
        description: Page number for pagination (0-based)
        required: false
      - schema:
          type: array
          items:
            type: string
            enum:
            - photo
            - video
            - gif
        style: form
        explode: false
        name: types
        in: query
        description: Filter by media types
        required: true
      - schema:
          type: array
          items:
            type: boolean
        style: form
        explode: false
        name: used
        in: query
        description: Filter by used status
        required: true
      - schema:
          type: array
          items:
            type: string
            enum:
            - canva
            - vista
            - postnitro
            - contentdrips
            - openai
            - favorites
        style: form
        explode: false
        name: source
        in: query
        description: Filter by source
        required: false
      - schema:
          type: string
        name: search
        in: query
        description: Search term to filter media by name or caption
        required: false
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  media:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Unique identifier for the media
                        type:
                          type: string
                          description: Type of media
                          enum:
                          - photo
                          - video
                          - gif
                        name:
                          type: string
                          description: Name of the media
                        caption:
                          type: string
                          description: Caption for the media
                        path:
                          type: string
                          description: URL to the full media
                        thumbnails:
                          type: array
                          description: Array of thumbnails objects associated with the media
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                                description: Unique identifier for the thumbnail
                              small:
                                type: string
                                description: URL to the small thumbnail
                              real:
                                type: string
                                description: URL to the real thumbnail
                        created_at:
                          type: string
                          format: date-time
                          description: Creation timestamp
                        updated_at:
                          type: string
                          format: date-time
                          description: Last update timestamp
                        favorite:
                          type: boolean
                          description: Whether the media is marked as favorite
                        in_library:
                          type: boolean
                          description: Whether the media is saved in the library
                  total:
                    type: integer
                    description: Total count of media items matching the query (without pagination)
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401ErrorResponse'
        '403':
          description: Permission denied or missing required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403ErrorResponse'
      operationId: listMedia
    post:
      summary: Upload a media file directly
      description: Upload a media file (image, video, or document) to be used in social media posts
      tags:
      - Media
      parameters:
      - schema:
          type: string
        name: Publer-Workspace-Id
        in: header
        description: ID of the workspace to upload media
        required: true
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  contentMediaType: application/octet-stream
                direct_upload:
                  type: boolean
                  description: Whether to upload directly to our S3 cloud (slower, but required if you
                    need the final media URL)
                  default: false
                in_library:
                  type: boolean
                  description: Whether to save to media library
                  default: false
            encoding:
              file:
                contentType: application/octet-stream
      responses:
        '200':
          description: Media file uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaUploadResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401ErrorResponse'
        '413':
          description: Permission denied or missing required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403ErrorResponse'
      operationId: uploadAMediaFileDirectly
  /media/from-url:
    post:
      summary: Upload media from URL
      description: Upload media files by providing URLs
      tags:
      - Media
      parameters:
      - schema:
          type: string
        name: Publer-Workspace-Id
        in: header
        description: ID of the workspace to upload media
        required: true
      responses:
        '200':
          description: Media upload job created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_id:
                    type: string
                    description: ID of the created job
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401ErrorResponse'
        '403':
          description: Permission denied or missing required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403JobErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MediaFromUrlRequest'
        description: URL upload request
        required: true
      operationId: uploadMediaFromURL
components:
  schemas:
    401ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          description: List of error messages
          items:
            type: string
    403ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          description: List of error messages
          items:
            type: string
    403JobErrorResponse:
      type: object
      properties:
        errors:
          type: array
          description: List of error messages
          items:
            type: string
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          description: List of error messages
          items:
            type: string
    MediaFromUrlRequest:
      type: object
      required:
      - media
      - type
      properties:
        media:
          type: array
          description: List of media URLs and metadata
          items:
            type: object
            required:
            - url
            - name
            properties:
              url:
                type: string
                description: URL of the media to download
              name:
                type: string
                description: Custom name for the media file
              caption:
                type: string
                description: Caption for the media
              source:
                type: string
                description: Source attribution for the media
        type:
          type: string
          description: Upload type
          enum:
          - single
          - thumbnail
          - bulk
          - thumbnail
        direct_upload:
          type: boolean
          description: Whether to upload directly to our S3 cloud (slower, but required if you need the
            final media URL)
          default: false
        in_library:
          type: boolean
          description: Whether to save to media library
          default: false
    MediaUploadResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the uploaded media
        path:
          type: string
          description: URL path to access the uploaded media
        thumbnail:
          type: string
          description: URL path to access a thumbnail version of the media
        validity:
          type: object
          description: Indicates which networks and post types support this media
        width:
          type: number
          description: Width of the media in pixels
        height:
          type: number
          description: Height of the media in pixels
        source:
          type: string
          description: Source attribution for the media
        type:
          type: string
          description: Media type (photo, video, document)
        name:
          type: string
          description: Original filename
        caption:
          type: string
          description: Caption for the media
  securitySchemes:
    BearerApiAuth:
      type: apiKey
      name: Authorization
      in: header
      description: 'API key authentication. Format: "Bearer-API YOUR_API_KEY"'