API v1

The same product, from your own code.

Everything the dashboard does, this API does - because they are the same endpoints. Plan, schedule and publish to every Facebook Page and Instagram account you manage, and know exactly what happened to each post.

Quickstart: publish a post

Three calls: upload or pick media, create the post with one target per account, then publish. Each account keeps its own format and its own limits, and the API refuses a combination Meta would reject before anything goes out.

bash
# 1. Create the post, with one target per account.
POST_ID=$(curl -s https://api.example.com/v1/workspaces/$WORKSPACE_ID/posts \
  -H "X-API-Key: $CONTENTO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "caption": "Morning brew, out of the new roaster.",
    "mediaIds": ["'"$MEDIA_ID"'"],
    "targets": [{ "socialAccountId": "'"$ACCOUNT_ID"'", "kind": "INSTAGRAM_FEED" }]
  }' | jq -r .data.id)

# 2. Send it now - or POST /schedule with scheduledAt to set a time.
curl -s https://api.example.com/v1/workspaces/$WORKSPACE_ID/posts/$POST_ID/publish \
  -H "X-API-Key: $CONTENTO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "timezone": "Europe/London" }'

Ask what happened with GET /posts/:postId/timeline - it returns the post’s whole life in order, across every account it went to.

Webhooks

Add an endpoint on the Developers page and pick the events you want. We POST a JSON body and retry with exponential backoff for about a day - roughly a minute, five, thirty, two hours, six, then a day - and stop. Every attempt is in the delivery log, with the answer your server gave.

http
POST /your/endpoint
X-Contento-Event: POST_PUBLISHED
X-Contento-Delivery: 0f2c…
X-Contento-Timestamp: 1793650000
X-Contento-Signature: v1=4f7a…

{
  "id": "evt_8sKq2mN1pQ7x",
  "type": "POST_PUBLISHED",
  "createdAt": "2026-11-03T09:30:02.114Z",
  "workspaceId": "b3d1…",
  "data": {
    "postId": "a91c…",
    "targetId": "5de0…",
    "socialAccountId": "7c1f…",
    "kind": "INSTAGRAM_FEED",
    "metaPostId": "17854…",
    "publishedAt": "2026-11-03T09:30:02.090Z"
  }
}

Verify the signature before you trust a payload. It is HMAC-SHA256 over `${timestamp}.${rawBody}`, with the secret shown once when you created the endpoint. Sign the raw body - re-serialising parsed JSON will not give the same bytes.

javascript
import { createHmac, timingSafeEqual } from 'node:crypto';

// The signed string is "<timestamp>.<raw body>". Sign the RAW body —
// re-serialising parsed JSON will not produce the same bytes.
export function verify(req, secret) {
  const presented = req.headers['x-contento-signature'];
  const timestamp = Number(req.headers['x-contento-timestamp']);
  const raw = req.rawBody; // a Buffer or string, before JSON.parse

  // Refuse anything older than five minutes, so a captured delivery
  // cannot be replayed at you forever.
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;

  const mac = createHmac('sha256', secret)
    .update(`${timestamp}.${raw}`)
    .digest('hex');
  const expected = Buffer.from(`v1=${mac}`);
  const given = Buffer.from(presented ?? '');

  return expected.length === given.length && timingSafeEqual(expected, given);
}

Zapier, Make and n8n

Nothing special is needed for the no-code tools: a generic HTTP step and a webhook trigger are enough. These are the three shapes people ask for most.

Zapier

Publish from a Google Sheet row

Trigger: Google Sheets - New Spreadsheet Row
Action: Webhooks by Zapier - Custom Request

  1. Method: POST, URL: https://api.example.com/v1/workspaces/<id>/posts
  2. Headers: X-API-Key, Content-Type: application/json, Idempotency-Key: {{zap_meta_human_now}}-{{row_id}}
  3. Data: the caption and target from the row
  4. Add a second step POSTing to /posts/{{id}}/publish

The Idempotency-Key built from the row id is what stops a Zap retry from posting twice.

Make

Tell Slack when a post fails

Trigger: Webhooks - Custom webhook
Action: Slack - Create a Message

  1. Add the Make webhook URL as an endpoint on the Developers page, subscribed to POST_FAILED
  2. In Make, add a Set Variable step that verifies X-Contento-Signature before anything else
  3. Map data.detail into the Slack message, so the channel sees Meta’s actual reason

Verify the signature first. An unverified webhook endpoint is a public write to your Slack.

n8n

Mirror published posts into Notion

Trigger: Webhook node (POST)
Action: Notion - Create Database Page

  1. Subscribe the n8n webhook to POST_PUBLISHED
  2. Add a Code node that recomputes the HMAC over `${timestamp}.${raw}` and stops the run if it differs
  3. Fetch GET /posts/{{data.postId}} with your key for the caption and media

n8n gives you the raw body on $binary or $json - sign the raw one, not the parsed one.

Authentication

Send your key in the X-API-Key header. Keys are made on the Developers page of a workspace, are scoped to that one workspace, and are shown exactly once - we store a SHA-256 hash, so we could not show you one again if we wanted to.

bash
curl https://api.example.com/v1/workspaces/$WORKSPACE_ID/social-accounts \
  -H "X-API-Key: $CONTENTO_API_KEY"

Every response is the same envelope, success or failure:

json
{
  "success": true,
  "data": [
    {
      "id": "7c1f…",
      "platform": "INSTAGRAM",
      "name": "Acme",
      "username": "acme",
      "tokenStatus": "VALID",
      "capabilities": ["INSTAGRAM_FEED", "INSTAGRAM_REEL"]
    }
  ]
}

Connecting an account is the one thing the API cannot do. It is a person consenting at Meta in a browser, so it happens in the dashboard - after that, every account is reachable here.

Scopes

A key carries a role and a list of scopes. The role is the same ladder your teammates are on; the scopes narrow it further, so a key written for a reporting script cannot publish even if its role would allow it.

posts:readThe planner, posts, targets and their timelines.
posts:writeCompose, schedule, publish, cancel, requeue.
accounts:readConnected Pages and Instagram accounts.
media:readThe library, its folders and signed read URLs.
media:writeUpload, finalize, file and move.
organise:readLabels, campaigns, categories, UTM presets, short links.
organise:writeCreate and change those.
webhooks:manageAdd, change and remove webhook endpoints.

A request outside a key’s scopes answers 403 INSUFFICIENT_SCOPE, and names the scope it wanted.

Idempotency

Every write accepts an Idempotency-Key header and honours it. Replaying a key returns the first response and produces no second effect, which is what makes a retry safe on a publish.

bash
# Send the same write twice with the same key.
# The second answers with the first response and publishes nothing new.
KEY=$(uuidgen)

for i in 1 2; do
  curl -s -o /dev/null -w "%{http_code} %{header_json}" \
    https://api.example.com/v1/workspaces/$WORKSPACE_ID/posts \
    -H "X-API-Key: $CONTENTO_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $KEY" \
    -d "$BODY"
done
# The replay carries: Idempotent-Replay: true
Idempotent-Replay: trueOn a response we have served before.
409 IDEMPOTENCY_IN_FLIGHTThe first request with this key is still running. Retry in a moment.
422 IDEMPOTENCY_KEY_REUSEDThe same key arrived with a different body. That is a bug in the caller, so we say so rather than guessing which body you meant.

Rate limits and quotas

Two separate things. A burst limit is how fast you may go right now, counted per key. A monthly quota is how many requests your plan includes. They never share a counter, and both are described in the response headers.

http
RateLimit-Policy: 120;w=60
RateLimit-Limit: 50000
RateLimit-Remaining: 49873
RateLimit-Reset: 1900800
Retry-After: 37        # only on a 429

Both refusals are 429 with Retry-After: burst answers RATE_LIMITED, a spent month answers QUOTA_EXCEEDED and names the plan that lifts it.

Errors

error.code is a stable enum - switch on it. message is written to be shown to a person, and when Meta refuses something it carries Meta’s actual reason and numbers rather than “something went wrong”.

json
{
  "success": false,
  "error": {
    "code": "MEDIA_INVALID_FOR_NETWORK",
    "message": "Meta refused this post: the video is 1920×1920, and a Reel must be between 0.01:1 and 10:9. Re-export it at 1080×1920 and try again.",
    "details": [{ "accountName": "Acme", "code": "MEDIA_INVALID_FOR_NETWORK" }]
  }
}