Quickstart
The shortest path to list profiles, create a draft, publish it, and inspect the result.
Before you begin
You need a PostMantis account, at least one connected social profile, and an API key from the dashboard.
This guide uses raw HTTP so the runtime contract is clear.
Choose the flow that matches your intent
This quickstart shows the draft → publish path. For request shapes, check out Examples. For end-to-end behavior across draft, immediate publish, future scheduling, canceling, and final result reads, check out Post Lifecycle.
List profiles
Start by listing the publishable destinations your API key can use.
curl https://postmantis.com/api/profiles \
-H "Authorization: Bearer $POSTMANTIS_API_KEY"The response returns profile objects with an id, provider, and display name:
{
"profiles": [
{
"id": "4339a6bc-9cd3-455e-8f91-df8bc63f12d7",
"provider": "x",
"name": "acme_corp"
},
{
"id": "8d3ef50f-98d9-4a44-8cf7-0b7fb53ab0a8",
"provider": "linkedin",
"name": "Acme Corp"
}
]
}For most agent flows, this list call is enough to choose destinations.
Create a draft
curl https://postmantis.com/api/posts \
-X POST \
-H "Authorization: Bearer $POSTMANTIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"post": {
"body": "Launch copy ready for approval.",
"draft": true
},
"profiles": ["4339a6bc-9cd3-455e-8f91-df8bc63f12d7"]
}'The accepted response returns status: "draft". Drafts still require profiles so destination intent is explicit from the start.
Optionally attach media
Add a media array to the same request body. Choose one approach per item:
Reference a publicly accessible file by URL. PostMantis imports it during request ingestion, stores it as an owned upload, and then publishes from owned media.
{
"post": { "body": "Launch image", "draft": true },
"profiles": ["4339a6bc-9cd3-455e-8f91-df8bc63f12d7"],
"media": [
{
"url": "https://assets.example.com/launch-card.png",
"alt": "Launch card"
}
]
}Use an upload session when the file is private, local, or too large for an inline URL. The upload session is a two-step flow:
POST /api/uploads— create the asset, receive anasset_idand an upload URL- Upload your file to the provided URL
POST /api/uploads/{id}/complete— signal that the upload is finished- Reference the
asset_idinmedia
{
"post": { "body": "Launch image", "draft": true },
"profiles": ["4339a6bc-9cd3-455e-8f91-df8bc63f12d7"],
"media": [
{
"asset_id": "8f5f3f18-3cf7-4aa8-a0ea-6fd204d4c4f1",
"alt": "Launch card"
}
]
}See Uploads for the full request and response shapes.
Use multipart/form-data to upload a local file directly in the same call as post creation.
curl https://postmantis.com/api/posts \
-X POST \
-H "Authorization: Bearer $POSTMANTIS_API_KEY" \
-F 'post[body]=Launch image' \
-F 'post[draft]=true' \
-F 'profiles[]=4339a6bc-9cd3-455e-8f91-df8bc63f12d7' \
-F 'media[0][file]=@./launch-card.png' \
-F 'media[0][alt]=Launch card'For each media[n], send exactly one of file, url, or asset_id.
Publish the draft
curl https://postmantis.com/api/posts/74d6f3d9-6b68-4a2d-9d89-c4510a08ff42/publish \
-X POST \
-H "Authorization: Bearer $POSTMANTIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'The empty body is valid — publishing a draft requires no additional fields. PostMantis publishes it to the profiles already set on the draft.
The immediate response returns accepted non-terminal state. Non-draft writes enter pending first, and a very fast worker may already advance the serialized response to scheduled before it is returned.
Schedule the same draft for later
If you want the draft to go live in the future instead of immediately, send scheduled_at in the publish request body:
curl https://postmantis.com/api/posts/74d6f3d9-6b68-4a2d-9d89-c4510a08ff42/publish \
-X POST \
-H "Authorization: Bearer $POSTMANTIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"scheduled_at": "2026-03-30T12:00:00Z"
}'The accepted state is still pending first. The workflow then advances the post to scheduled and waits until the future scheduled_at before dispatching deliveries. A very fast worker may already make the serialized response show scheduled.
Read the post back
curl https://postmantis.com/api/posts/74d6f3d9-6b68-4a2d-9d89-c4510a08ff42 \
-H "Authorization: Bearer $POSTMANTIS_API_KEY"Use the response to inspect post workflow status, media processing state, and deliveries[] for the delivery result on each selected profile/provider.
Skip the draft — publish immediately
Omit draft: true and scheduled_at to create a post that goes straight to the async workflow. PostMantis accepts it into pending immediately — no separate publish call needed. A very fast worker may already make the serialized response show scheduled.
{
"post": { "body": "The launch is live." },
"profiles": ["4339a6bc-9cd3-455e-8f91-df8bc63f12d7"]
}If you want one-call future scheduling instead, send post.scheduled_at on create.
Naming rule of thumb
profiles selects destinations — provider_options carries provider-specific options — read
responses later to inspect delivery outcomes.