Skip to main content
This section documents every endpoint exposed by the PublishBuddy API. Pages are generated directly from our OpenAPI 3.1 specification, so the request shapes, response examples, and parameter descriptions you see here match what the server accepts.

​
Conventions

Base URL: https://api.publishbuddy.com/v1 Auth: Authorization: Bearer <token> on every request (see Authentication) Format: JSON request and response bodies; media is uploaded by URL or as multipart/form-data, with pre-signed storage uploads for large files (see Upload and manage media) Timestamps: ISO 8601 in UTC (for example 2026-05-13T22:30:00+00:00) IDs: UUID strings unless otherwise documented
Every response wraps its primary payload in a data field. Mutations that succeed also return a message string suitable for surfacing in a UI:
Deletes return 200 with an empty data array and a message. Error responses use the same envelope; see Errors.

​
How the resources fit together

  • A Workspace is the container for everything: profiles, posts, media, billing.
  • A Profile is one connected social account (for example an Instagram business profile).
  • A Post is a planned publication. It targets exactly one profile, can carry media and text, and moves through statuses (waiting → publishing → published).
  • A MediaContent is a file in the workspace’s media library, optionally inside a folder.
  • Analytics are derived from successfully published posts and the underlying social network’s APIs.
Read Core concepts for a deeper tour before diving into endpoints.

​
Authentication and plans

The Bearer token controls both who you are (which user) and what you can do (which abilities). See Authentication for the full set of abilities and how to generate a token from User Settings → Login & Security at app.publishbuddy.com. Each endpoint in this section documents the ability it requires. Requests sent with a token that lacks the required ability return 403. Requests into a workspace whose owner’s plan does not include the API, or the feature behind a specific endpoint group, return 402. See Plans.

​
Rate limits

The API is rate-limited per user. Most endpoints share a baseline limit; high-volume routes (posts, media, folders) get a larger budget, and post creation has a daily cap. See Rate limits.

​
Pagination

List endpoints return one page of results at a time. Use the page query parameter to walk through additional pages, and read the meta.last_page field on the response to know when to stop. See Pagination.

​
Try it out

Each endpoint page has a built-in playground. Click Try it at the top of any reference page, paste your token, and run the request right from these docs. No extra tooling required.