postmatic
pten
Start for free

Getting started

From your first request to a published Instagram post in five calls. Base URL, authentication and the full lifecycle of a post.

Postmatic is an API for publishing and scheduling on Instagram without dealing with OAuth, long-lived tokens and the Graph API rules. You connect professional accounts through the dashboard or the connect flow, then publish with one HTTP call.

Everything lives under one base URL:

Base URL
https://api.uat.postmatic.dev/v1

What you need

  1. A Postmatic account. Sign in to the dashboard with your e-mail.
  2. A professional Instagram account (Business or Creator). Personal accounts are rejected during connection.
  3. An API key, created under API keys in the dashboard. It is shown once; keep it in a secrets vault and use it only on the server.

1. Verify the key

Every call carries the key in the x-access-key header.

GET /v1/health/auth
curl https://api.uat.postmatic.dev/v1/health/auth \
  -H "x-access-key: pm_live_…"
Response
{ "success": true, "project": { "id": "proj_…", "environment": "live" } }

2. Connect an account

Through the dashboard, under Accounts, or through the API: request the authorization URL, redirect the user and receive them back at your redirectUri.

GET /v1/connect/instagram
curl "https://api.uat.postmatic.dev/v1/connect/instagram?redirectUri=https://app.example.com/accounts" \
  -H "x-access-key: pm_live_…"

When done, the user lands on https://app.example.com/accounts?status=connected&integrationId=int_…. The full flow, with profiles and error handling, is in Accounts and profiles.

3. Find the accountId

GET /v1/connect/integrations
curl https://api.uat.postmatic.dev/v1/connect/integrations \
  -H "x-access-key: pm_live_…"
Response (abridged)
{
  "success": true,
  "total": 1,
  "integrations": [
    { "id": "int_…", "platform": "instagram", "displayName": "acme.brand", "authStatus": "active", "status": "connected" }
  ]
}

Each account's id is the accountId you pass when publishing.

4. Publish

An image reachable over HTTPS, the caption and the target account. The response arrives before the post exists on Instagram: publishing happens in the background.

API

From your application to Instagram.

One call to publish. One request to check progress. Use the language your product already runs on.

curl -X POST https://api.uat.postmatic.dev/v1/posts \
  -H "x-access-key: pm_live_…" \
  -H "content-type: application/json" \
  -d '{
    "content": "Hello from Postmatic.",
    "platforms": [{ "platform": "instagram", "accountId": "int_…" }],
    "mediaItems": [{ "type": "image", "url": "https://…/foto.jpg" }],
    "publishNow": true
  }'

Immediate publishing example. Replace the key, connected account ID and image URL.

Response 202
{
  "success": true,
  "postId": "post_…",
  "status": "pending",
  "platforms": [{ "platform": "instagram", "accountId": "int_…", "status": "queued", "platformPostUrl": null }]
}

5. Track it

Poll the post until status reaches published or failed. Immediate publishing usually finishes in under two minutes.

GET /v1/posts/:id
curl https://api.uat.postmatic.dev/v1/posts/post_… \
  -H "x-access-key: pm_live_…"

On published, each item in platforms carries the platformPostUrl. On failed, read the target's errorCode and errorMessage. States and scheduling rules are in Posts.

Next steps

  • Authentication: the two access modes, request limits and the error envelope.
  • Media: upload images straight to Postmatic instead of exposing a URL.
  • Errors: every code and what to do about each one.
  • Reference: the OpenAPI spec and the interactive reference for every route.