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 are always in sync with 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 directly to storage via pre-signed URLs (see Upload and manage media) Timestamps — ISO 8601 in UTC (e.g. 2026-05-13T22:30:00Z) IDs — UUID v4 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:
Error responses follow 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 (e.g. 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 on every endpoint

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 in its summary. Requests sent with a token that lacks the required ability return 403.

​
Rate limits

The API is rate-limited per token. Most endpoints share a baseline limit; high-volume routes (media uploads, post listing) get a larger budget. See Rate limits.

​
Pagination

List endpoints return up to a default page size of results. 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.