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: []