API Overview
Public API for posting, scheduling, uploads, and delivery inspection.
The PostMantis public API lives under /api/v1. It automates what you do over and over: look up connected social accounts, upload media, create or schedule posts, and check what happened.
API-key management and OAuth connect flows are dashboard-only. They are setup ceremonies, not automation — you do them once in the browser, then automate everything else with a Bearer key.
Single source of truth
Every endpoint, parameter, and error on the following pages is generated from the same OpenAPI
spec the server ships. Read the raw spec at /api/v1/openapi-docs, or use
it to generate an SDK for any language.
Authentication
Authorization: Bearer <api-key>Keys are created in the dashboard. A key carries a scope: read (list/get only) or write (create/update/cancel/disconnect/upload). Key scope can also be limited to specific providers or profiles.
Core flow
- List profiles with
GET /api/v1/profiles— collect theids you will post to. - Upload media (optional):
POST /api/v1/uploads→PUTbytes touploadUrl→POST /api/v1/uploads/complete→ keep the returnedartifactId. - Create a post with
POST /api/v1/posts. Omitpost.scheduledAtto publish now; send a future ISO-8601 datetime to schedule. - Read state with
GET /api/v1/posts/{postId}to see per-provider delivery outcomes. - Cancel a future scheduled post with
POST /api/v1/posts/{postId}/cancel.
Create is async acceptance: you get a 201 with the post id immediately, then poll GET /api/v1/posts/{postId} for the final delivery result.
One envelope rule
data field. Single resources: { data: Post }. Lists: { data: Post[], pagination } — pagination is a sibling of data, never nested. Same rule for profiles, uploads, and logs.Post states
| State | Meaning |
|---|---|
pending | Accepted. Worker has not settled the post yet. |
scheduled | Waiting for a future scheduledAt to fire. |
settled | All deliveries resolved (published or failed). |
canceled | A future delivery was stopped before it ran. |
Each delivery also has its own status: pending, published, failed, or canceled. Read them on the post's deliveries array.
Endpoints at a glance
Every endpoint below gets a full reference page (request/response shapes, examples, errors) generated from the OpenAPI spec. This table is the map.
Profiles
| Method | Path | Operation |
|---|---|---|
| GET | /api/v1/profiles | List connected profiles |
| GET | /api/v1/profiles/{id} | Get a single profile |
| POST | /api/v1/profiles/{id}/disconnect | Permanently disconnect a profile |
Posts
| Method | Path | Operation |
|---|---|---|
| GET | /api/v1/posts | List posts (filter, paginate) |
| POST | /api/v1/posts | Create a publish-now or scheduled post |
| GET | /api/v1/posts/{postId} | Get a post with delivery outcomes |
| PATCH | /api/v1/posts/{postId} | Update a future scheduled post |
| POST | /api/v1/posts/{postId}/cancel | Cancel a scheduled post and its deliveries |
POST /api/v1/posts accepts application/json (with artifactId media references from /uploads) or multipart/form-data for direct file attachment. For multipart, send one payload text field holding JSON plus one File part per media item, referencing each file inside media[] by fileField: "<partName>". The server uploads the bytes and replaces the reference with a real artifactId.
Uploads
| Method | Path | Operation |
|---|---|---|
| POST | /api/v1/uploads | Request a presigned URL and a reserved artifactId |
| POST | /api/v1/uploads/complete | Verify the upload and promote it to a usable artifact |
Two-phase flow keeps the API key off the bytes path. Max file size: 150 MB.
Publishing Logs
| Method | Path | Operation |
|---|---|---|
| GET | /api/v1/publish/logs | List delivery events for audit |
Read-only event stream: pending, published, failed, canceled per delivery.
Errors
Errors use RFC 7807 Problem Details. Each operation page documents the status codes it can return. Common ones:
| Status | Code | When |
|---|---|---|
| 401 | unauthorized | Missing or invalid API key |
| 403 | forbidden | Key lacks permission for this operation |
| 404 | notFound | Resource not found or outside key scope |
| 409 | conflict | Resource state prevents operation |
| 429 | rateLimited | Too many requests — back off and retry |
What is intentionally not here
- API key management (
/api/v1/api-keys*) — dashboard session only. - Provider OAuth connect — dashboard session only.
- Webhooks — not yet an automation surface.
If you need either of the first two, do them in the dashboard once, then automate with a key.