Overview
The mental model for profiles, posts, media, and the current public PostMantis API contract.
Start here for the API mental model.
What the API is for
PostMantis gives agents and backend systems one runtime API to publish and track delivery state for accounts already connected in the dashboard.
Scope
The runtime surface for agents, automations, and backend services:
- profiles (read-only)
- posts
- media uploads
Account administration — only in the dashboard:
- connect and manage social profiles
- create and scope API keys
- billing and settings
Also available here as a convenience:
- create and publish posts manually
Resource model
| Term | Meaning |
|---|---|
| Profile | One already-connected publishable destination in your account |
| Post | The top-level publishing workflow resource |
| Delivery | One delivery intention created by pairing a post with a selected profile |
| Provider options | Provider-specific write options grouped under the provider_options object |
| Delivery result | The delivery outcome returned in deliveries[] when you read a post later |
Profile
A profile is one already-connected publishable destination — a specific X account, LinkedIn page, YouTube channel, or Pinterest board already connected in the dashboard. Profiles are primarily read-oriented in the public API.
GET /api/profiles provides enough information to choose destinations. GET /api/profiles/{id} is optional. If you need to stop future use of a profile without deleting history, use POST /api/profiles/{id}/disconnect.
Post
A post is the main publishing workflow. It can be a draft, a scheduled post, or an immediate publish request.
A post may include body, media, selected profiles, and provider-specific parameters in provider_options.
When you create or publish a post, PostMantis expands it into one or more deliveries based on the selected profiles.
Media
Media can come from remote URLs, completed upload sessions, or direct multipart/form-data uploads on post create or update.
These are ingestion methods, not different downstream media models. Before PostMantis accepts a post, every supported media-like input is normalized into a PostMantis-owned asset. Downstream workflow and provider publishing then operate only on owned asset references.
Core semantics
Acceptance commands
These endpoints accept work and return non-terminal workflow state:
POST /api/posts— accepts intodraftorpendingPOST /api/posts/{id}/publish— accepts intopending
Terminal states appear only when you read the post later.
Why you may still see scheduled in the response
Non-draft writes enter pending first. The server then reads the post back before
returning the response, so a fast worker may already advance the serialized response to
scheduled.
POST /api/posts accepts both application/json and multipart/form-data. Use multipart when uploading local files directly.
post[body] post[scheduled_at]
profiles[] provider_options[provider][field]
media[n][file|url|asset_id|alt]For each media[n], send exactly one of file, url, or asset_id.
Provider cover assets follow the same rule in multipart requests:
provider_options[youtube][cover][file|url|asset_id]provider_options[instagram][cover][file|url|asset_id]provider_options[pinterest][cover][file|url|asset_id]
API key scope is immutable. If you need different access later, revoke the old key and create a new one in the dashboard.
Post visibility is all-or-nothing: a key can read a post only when every delivery on that post is inside the key scope.
Common request flows
| Intent | Request | Accepted response | What happens next |
|---|---|---|---|
| Save a draft only | POST /api/posts with post.draft: true | draft | Stored, not submitted for delivery yet |
| Publish an existing draft now | POST /api/posts/{id}/publish with empty body | pending | Accepted immediately, then the workflow advances to scheduled and dispatches as soon as possible |
| Publish an existing draft later | POST /api/posts/{id}/publish with top-level scheduled_at | pending | Accepted immediately, then the workflow advances to scheduled and waits until that future time |
| Create and publish now | POST /api/posts without draft or post.scheduled_at | pending | Accepted immediately, then the workflow advances to scheduled and dispatches as soon as possible |
| Create and schedule for later | POST /api/posts with future post.scheduled_at | pending | Accepted immediately, then the workflow advances to scheduled and waits until the future time |
| Cancel a scheduled post | POST /api/posts/{id}/cancel | canceled | Only works after the post reached scheduled and while every delivery is still pending |
Non-draft writes are accepted into pending first. Later reads move to scheduled or completed once the publishing workflow advances the post.
Read endpoints
Publish retries
Delivery retries happen in the background workflow, not in the original write request. PostMantis currently uses up to 3 total attempts for delivery task executions that throw, with a simple fixed 60-second delay between retries.
Provider-level failures returned as explicit publish results are different. Those deliveries are finalized as failed and exposed on the post resource without another automatic attempt.
Intermediate retry attempts stay at the workflow-runtime layer. Current user-facing reads and the Publishing Log show domain events and final delivery outcomes, not every internal worker retry attempt as a separate event.
Cancellation
POST /api/posts/{id}/cancel is the only deletion-like write. Use it only for posts that already reached scheduled and have not started settling any delivery yet. Deleting post records or already-published provider content is intentionally not supported.
Status model
Post workflow
| Status | Meaning |
|---|---|
draft | Stored, not submitted for delivery |
pending | Accepted and not yet advanced by the workflow |
scheduled | Advanced by the workflow and now dispatchable or waiting for time |
completed | Workflow orchestration finished |
canceled | Canceled before any delivery left pending |
completed ≠ fully published
completed means workflow orchestration finished. Inspect deliveries[]
for the true delivery results.
Delivery result
| Status | Meaning |
|---|---|
pending | Delivery not finished |
published | Delivery succeeded |
failed | Delivery ended unsuccessfully |
Media
Media status is a lightweight readiness signal, not a full per-asset workflow log. Use post status, delivery status, and the Publishing Log to understand the primary publish state.
| Status | Meaning |
|---|---|
pending | The post has not yet reached a later workflow state |
processed | The post progressed to scheduled, completed, or canceled |
failed | The stored media record carries an explicit failure marker |
Naming rule of thumb
| Term | Use for |
|---|---|
profiles | Choosing where a post should go |
provider_options | Setting provider-specific request fields |
deliveries | Reasoning about one delivery path inside a post |
| delivery results | Inspecting which deliveries succeeded or failed |
Related
Examples
Practical request examples for drafts, scheduling, uploads, and multi-provider publishing.
List posts GET
Returns a paginated list of posts visible to the authenticated API key. Post visibility is all-or-nothing: a post appears only when all deliveries on that post are inside the key scope. Use the `deliveries` array for per-destination results. For `profile_ids` and `providers`, generated clients should send repeated query keys; the server also accepts comma-separated values for compatibility.