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.
# 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.
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.
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
- Method: POST, URL: https://api.example.com/v1/workspaces/<id>/posts
- Headers: X-API-Key, Content-Type: application/json, Idempotency-Key: {{zap_meta_human_now}}-{{row_id}}
- Data: the caption and target from the row
- 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
- Add the Make webhook URL as an endpoint on the Developers page, subscribed to POST_FAILED
- In Make, add a Set Variable step that verifies X-Contento-Signature before anything else
- 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
- Subscribe the n8n webhook to POST_PUBLISHED
- Add a Code node that recomputes the HMAC over `${timestamp}.${raw}` and stops the run if it differs
- 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.
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:
{
"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.
# 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: trueIdempotent-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.
RateLimit-Policy: 120;w=60
RateLimit-Limit: 50000
RateLimit-Remaining: 49873
RateLimit-Reset: 1900800
Retry-After: 37 # only on a 429Both 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”.
{
"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" }]
}
}