Getting started

popkit REST API

popkit's capabilities as a REST API for your scripts, automation platforms and back ends: with one long-lived credential you can read accounts and posts, save drafts, schedule, publish, reply to comments and read analytics. It shares its foundation with popkit's MCP server — the same scopes, rate limits, idempotency and audit — just a different way to call it.

Base URL

https://popkit.loxily.com/api/v1

HTTPS only; requests and responses are JSON (Content-Type: application/json). v1 in the path is the major version: within a version we only make backward-compatible additions (new fields, endpoints, enum values), so ignore fields you do not recognise.

Start here

Quickstart

Issue a credential → first request → save a draft → schedule, in five minutes.

Authentication

Where credentials come from, how scopes and publish tiers work, how to revoke.

Conventions

Envelope, cursors, idempotency keys, rate limits and daily caps, time format.

Errors

13 machine codes, their HTTP status and what to do.

OpenAPI 3.1

/docs/api/openapi.json — import into Postman / Swagger / code generators.

MCP docs

The other way in, for AI clients like Claude and Cursor; same capabilities.

All endpoints (20)

Grouped by domain. Each endpoint has its own page with parameter tables, cURL / JavaScript / Python samples and response examples per status.

Workspace & accounts — Who am I, which accounts are connected, what quota is left.

Method	Path	What it does
GET	/api/v1/workspace	Workspace context
GET	/api/v1/accounts	Connected accounts

Posts — Drafts, scheduling, edits, rescheduling, approval and prechecks.

Method	Path	What it does
GET	/api/v1/posts	List posts
GET	/api/v1/posts/{postId}	Get a post
POST	/api/v1/posts	Create a post
PATCH	/api/v1/posts/{postId}	Update a post
POST	/api/v1/posts/precheck	Publish precheck
POST	/api/v1/posts/{postId}/reschedule	Reschedule
POST	/api/v1/posts/{postId}/submit	Submit for approval
POST	/api/v1/posts/{postId}/cover-suggestions	Suggest covers
POST	/api/v1/posts/{postId}/cover	Set cover

Publishing — The two endpoints that actually go out: confirm and publish / retry.

Method	Path	What it does
POST	/api/v1/posts/{postId}/confirm	Confirm publish
POST	/api/v1/posts/{postId}/publish	Publish / retry

Media — Hand images / videos to popkit in exchange for a publishable media URL.

Method	Path	What it does
POST	/api/v1/media	Attach media

Comments — The comment inbox and replying as the account.

Method	Path	What it does
GET	/api/v1/comments	Comment inbox
POST	/api/v1/comments/{commentId}/replies	Reply to a comment

Idea board — Groups and ideas on the planning board.

Method	Path	What it does
GET	/api/v1/ideas	List ideas
POST	/api/v1/ideas	Create an idea
PATCH	/api/v1/ideas/{ideaId}	Update an idea

Analytics — Metrics overview, same definitions as the in-app analytics page.

Method	Path	What it does
GET	/api/v1/analytics/summary	Analytics summary

Response envelope

Success

{
  "data": {
    "…": "…"
  },
  "meta": {
    "requestId": "3f9c1e2a-7d4b-4c1e-9a6f-0b2d8e5c7a11"
  }
}

Failure

{
  "error": {
    "code": "forbidden",
    "message": "credential lacks scope posts:write",
    "params": {
      "scope": "posts:write"
    }
  },
  "meta": {
    "requestId": "3f9c1e2a-7d4b-4c1e-9a6f-0b2d8e5c7a12"
  }
}

Field	Type	Meaning
data	object	Payload on success; shape depends on the endpoint.
error.code	string	Machine code to branch on; full table under Errors.
error.message	string \| null	English hint for developers / models; not UI copy.
error.params	object \| null	Machine-readable extras such as `{ limit, used }` or `{ scope }`.
meta.requestId	string	Request id (also in the `X-Request-Id` header); quote it when asking for help.
meta.replayed	boolean?	`true` when this is the cached result of an earlier call with the same `Idempotency-Key`.

Relationship to the MCP server

REST and MCP are two façades over one capability core: the 20 endpoints map one-to-one to the 20 MCP tools, input schemas are byte-identical, and rate limits and idempotency caches are shared per credential (5 publishes over REST also use up 5 of the same credential's MCP publish budget). Unattended scripts and automation platforms use REST; AI assistants with a human present use MCP (which supports OAuth and two-step confirmation).