Schedule posts
with code.

#How it works

The Publishing API is the programmatic counterpart of the planner in the Social Analyze panel. Everything you do there — choosing accounts, uploading media, per-platform suitability checks, scheduling, editing, cancelling — exists here and goes through the same validation. Posts created through the API show up in the panel with an “API” badge and can be edited there too.

1. Create a keyPanel → Brand settings → API. Pick platforms and permissions; the secret is shown only once.
2. Prepare mediaImport the video/image from a URL or upload it in chunks; you get a media id when it is ready.
3. Check suitabilityFind out which accounts the content suits, or let targets:"auto" send it to the suitable ones.
4. ScheduleGive a time in the brand's timezone. Get the result by webhook or poll the status.

#Quick start

The flow below schedules a video, at a time in the brand's timezone, to every allowed account the content suits. Keep the key and secret in environment variables; never put them in client-side code.

export SA_KEY="sak_…"      # from the panel
export SA_SECRET="sas_…"

# 1) Verify the connection
curl https://app.socialanalyze.org/api/v1/me -H "X-API-Key: $SA_KEY" -H "X-API-Secret: $SA_SECRET"

# 2) Import the video from a URL  → 202 + media id
curl -X POST https://app.socialanalyze.org/api/v1/media/import -H "X-API-Key: $SA_KEY" -H "X-API-Secret: $SA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://cdn.example.com/launch.mp4"}'

# 3) Wait until it is ready  (status: "ready")
curl https://app.socialanalyze.org/api/v1/media/MEDIA_ID -H "X-API-Key: $SA_KEY" -H "X-API-Secret: $SA_SECRET"

# 4) Schedule to the suitable accounts
curl -X POST https://app.socialanalyze.org/api/v1/publications -H "X-API-Key: $SA_KEY" -H "X-API-Secret: $SA_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-2026-10-10" \
  -d '{
    "text": "The new release is live! 🚀",
    "media": ["MEDIA_ID"],
    "targets": "auto",
    "local_time": "2026-10-10T09:00",
    "external_ref": "cms-post-4821"
  }'

Successful response (201):

{
  "data": {
    "id": "7ed788c0-878c-4c8e-a46e-a83621a55521",
    "status": "scheduled",
    "text": "The new release is live! 🚀",
    "media": [{ "id": "588ff7a4-…", "kind": "video", "mime": "video/mp4", "size": 18349211, "name": "launch.mp4", "url": "https://app.socialanalyze.org/api/social/media/94e3….mp4" }],
    "scheduled_at": "2026-10-10T06:00:00.000Z",
    "published_at": null,
    "external_ref": "cms-post-4821",
    "source": "api",
    "targets": [
      { "account_id": "fb17aa48-…", "platform": "instagram", "text": null, "options": {}, "result": null },
      { "account_id": "4f030b35-…", "platform": "tiktok",    "text": null, "options": {}, "result": null }
    ]
  },
  "skipped": [
    { "account_id": "9c1d…", "platform": "youtube", "reason": "YouTube: video başlığı gerekli." }
  ]
}

#Authentication

Every request carries two headers: the public key identifier (sak_…) and the secret (sas_…). The secret must never appear in URLs, logs or client-side code. All requests use HTTPS.

curl https://app.socialanalyze.org/api/v1/me \
  -H "X-API-Key: sak_5a2ebf67ddb00876af15202e" \
  -H "X-API-Secret: sas_••••••••••••••••••••••••••••••••"

# Alternative: HTTP Basic (key:secret)
curl -u "$SA_KEY:$SA_SECRET" https://app.socialanalyze.org/api/v1/me

• You see the secret only at creation/rotation; we store only its SHA-256 hash, so rotate it if lost.
• A wrong key and a wrong secret return the same response (401 invalid_credentials); key existence is not leaked.
• Rotating invalidates the old secret immediately. For a zero-downtime switch, create a second key, move your system over, then revoke the old one.
• If you set an IP allowlist, only requests from those IPs/CIDRs are accepted (403 ip_not_allowed).

#Keys & permissions

Keys are managed in the panel under Brand settings → API (account owner only). A brand can have up to 10 active keys, each with its own platforms, permissions and limits.

Platform access is per key: if a key is allowed only Instagram and TikTok, targeting any other platform returns 403 platform_not_allowed. If a new account is later connected to the brand, the key sees it automatically if its platform is allowed.

#Conventions

#Publication lifecycle

draft ──schedule──▶ scheduled ──(time reached)──▶ publishing ──▶ published
  ▲                      │  ▲                           │  └──▶ partial   (some targets published)
  └────unschedule────────┘  └─────── edit ──────────────┘  └──▶ failed    (none published)
                           failed / partial ──retry (publish / reschedule)──▶ publishing

Per-target results are always in targets[].result: status (published | processing | failed), external_id, permalink and the error message. A target that is already published is never sent again on retry.

#Targets & compatibility

The same content does not suit every platform: Instagram and TikTok need media, YouTube accepts only video and needs a title, and text limits differ. The API applies these rules for you and answers “which platforms does it suit?” in three ways:

To ask in advance use POST /compatibility — you can even ask before uploading, with just the kinds (media_kinds).

#Time & timezones

You can give the time in two ways; do not send both:

• The time must be at least 1 minute and at most 1 year ahead.
• The scheduler runs every minute; a post goes out in its scheduled minute.
• scheduled_at: null (in PATCH) removes the schedule and returns the post to draft.

#Idempotency & external_ref

To safely retry after a network error, add a unique Idempotency-Key header to POST /publications. When the same key + Idempotency-Key arrives again no new post is created; the original is returned with 200 and an Idempotent-Replayed: true header.

Store your own system's identifier in external_ref (≤120 chars) and find it again with GET /publications?external_ref=…. metadata is a free-form JSON object and comes back unchanged in webhooks.

#Endpoints

{
  "data": {
    "key": {
      "key_id": "sak_5a2e…",
      "name": "CMS otomasyonu",
      "scopes": ["accounts:read", "media:write", "publications:read", "publications:write"],
      "platforms": ["instagram", "tiktok"],
      "expires_at": null,
      "rate_limit_per_min": 60,
      "daily_publication_limit": 100,
      "ip_restricted": false,
      "webhook_configured": true,
      "webhook_events": [],
      "created_at": "2026-10-02T11:10:09.784Z"
    },
    "brand": { "id": "b193a53c-…", "name": "Fonoloji", "timezone": "Europe/Istanbul", "local_date": "2026-10-02" }
  }
}

{
  "data": [
    {
      "id": "fb17aa48-a440-470b-af3d-873044f93d54",
      "platform": "instagram",
      "name": "Fonoloji",
      "username": "fonoloji",
      "avatar_url": "https://…",
      "profile_url": "https://www.instagram.com/fonoloji/",
      "status": "active",
      "capabilities": {
        "publish": true,
        "publish_kinds": ["image", "video", "carousel"],
        "requires_media": true,
        "max_text_length": 2200,
        "max_media": 10
      }
    }
  ]
}

curl -X POST https://app.socialanalyze.org/api/v1/compatibility -H "X-API-Key: $SA_KEY" -H "X-API-Secret: $SA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"text":"New video","media_kinds":["video"]}'

Media

Videos and images are first brought into Social Analyze, then attached to a post by media id. There are two ways: (1) import from a public URL (easiest), (2) upload in 5 MB chunks. Supported: JPG, PNG, WEBP (≤30 MB), GIF (≤15 MB), MP4, MOV, WEBM (≤1 GB). File contents are verified against the declared type; mismatches are rejected.

curl -X POST https://app.socialanalyze.org/api/v1/media/import -H "X-API-Key: $SA_KEY" -H "X-API-Secret: $SA_SECRET" -H "Content-Type: application/json" \
  -d '{"url":"https://cdn.example.com/launch.mp4"}'

# 1) Start
curl -X POST https://app.socialanalyze.org/api/v1/media/uploads -H "X-API-Key: $SA_KEY" -H "X-API-Secret: $SA_SECRET" -H "Content-Type: application/json" \
  -d '{"name":"launch.mp4","mime":"video/mp4","size":18349211}'
# → { "data": { "id": "…", "chunk_size": 5242880, "chunk_count": 4, "status": "uploading" } }

# 2) Each chunk (index starts at 0)
curl -X PUT "https://app.socialanalyze.org/api/v1/media/uploads/MEDIA_ID/chunk?index=0" -H "X-API-Key: $SA_KEY" -H "X-API-Secret: $SA_SECRET" \
  -H "Content-Type: application/octet-stream" --data-binary @chunk0.bin

# 3) Complete
curl -X POST https://app.socialanalyze.org/api/v1/media/uploads/MEDIA_ID/complete -H "X-API-Key: $SA_KEY" -H "X-API-Secret: $SA_SECRET"

{
  "text": "The new release is live! 🚀",
  "media": ["588ff7a4-0c36-44bf-b0b9-7f942ed9f76e"],
  "targets": "auto",
  "local_time": "2026-10-10T09:00",
  "external_ref": "cms-post-4821",
  "metadata": { "campaign": "launch" }
}

{
  "text": "Compare funds with Fonoloji",
  "media": ["588ff7a4-…"],
  "targets": [
    { "platform": "youtube",   "text": "Fund comparison guide — description text…", "options": { "title": "How do I compare funds?", "privacy": "public", "tags": ["fon", "yatırım"] } },
    { "platform": "instagram", "options": { "type": "reel", "first_comment": "Link in bio" } },
    { "platform": "tiktok",    "options": { "title": "Compare funds", "privacy_level": "SELF_ONLY", "disable_duet": true } }
  ],
  "scheduled_at": "2026-10-10T09:00:00+03:00"
}

curl -X POST https://app.socialanalyze.org/api/v1/publications -H "X-API-Key: $SA_KEY" -H "X-API-Secret: $SA_SECRET" -H "Content-Type: application/json" \
  -d '{"text":"deneme","media":["MEDIA_ID"],"targets":"auto","local_time":"2027-03-01T10:00","validate_only":true}'
# → { "data": { "valid": true, "mode": "schedule", "scheduled_at": "2027-03-01T07:00:00.000Z",
#               "targets": [ { "account_id": "…", "platform": "instagram" }, … ] }, "skipped": [] }

# Everything scheduled next week
curl "https://app.socialanalyze.org/api/v1/publications?status=scheduled&from=2026-10-12T00:00:00Z&to=2026-10-19T00:00:00Z&sort=scheduled_at" -H "X-API-Key: $SA_KEY" -H "X-API-Secret: $SA_SECRET"

# Change the time and text
curl -X PATCH https://app.socialanalyze.org/api/v1/publications/PUB_ID -H "X-API-Key: $SA_KEY" -H "X-API-Secret: $SA_SECRET" -H "Content-Type: application/json" \
  -d '{"text":"Updated text","local_time":"2026-10-11T18:30"}'

# Remove the schedule (back to draft)
curl -X PATCH https://app.socialanalyze.org/api/v1/publications/PUB_ID -H "X-API-Key: $SA_KEY" -H "X-API-Secret: $SA_SECRET" -H "Content-Type: application/json" -d '{"scheduled_at":null}'

# Change targets: Instagram only
curl -X PATCH https://app.socialanalyze.org/api/v1/publications/PUB_ID -H "X-API-Key: $SA_KEY" -H "X-API-Secret: $SA_SECRET" -H "Content-Type: application/json" -d '{"targets":["instagram"]}'

# Retry a failed post with a new time
curl -X PATCH https://app.socialanalyze.org/api/v1/publications/PUB_ID -H "X-API-Key: $SA_KEY" -H "X-API-Secret: $SA_SECRET" -H "Content-Type: application/json" -d '{"mode":"schedule","local_time":"2026-10-12T09:00"}'

curl -X POST https://app.socialanalyze.org/api/v1/publications/PUB_ID/publish -H "X-API-Key: $SA_KEY" -H "X-API-Secret: $SA_SECRET"

curl -X DELETE https://app.socialanalyze.org/api/v1/publications/PUB_ID -H "X-API-Key: $SA_KEY" -H "X-API-Secret: $SA_SECRET"
# → { "data": { "id": "…", "deleted": true } }

#Platform guide

Rules follow each platform's official API and can change; for a definitive answer use /accounts → capabilities and /compatibility.

Platform options

Options are flat snake_case: options: { … } on a target or, in bulk, platform_options: { platform: { … } }. An unknown key returns 400 invalid_options.

#Webhooks

Instead of polling, let us tell you the result. When you set an https webhook URL on a key, a signed POST is sent whenever the status of a publication created with that key changes. The URL must be public (internal/private IPs are blocked).

Request headers and body:

POST /your/webhook  HTTP/1.1
Content-Type: application/json
User-Agent: SocialAnalyze-Webhooks/1.0
X-SocialAnalyze-Event: publication.published
X-SocialAnalyze-Delivery: 2b4f9e6e-…
X-SocialAnalyze-Timestamp: 1790939393
X-SocialAnalyze-Signature: sha256=38877139…

{
  "id": "evt_2b4f9e6e…",
  "type": "publication.published",
  "created_at": "2026-10-10T06:00:07.214Z",
  "data": { …publication object (same as GET /publications/{id})… }
}

Verifying the signature

Signature = HMAC-SHA256(webhook_secret, `${timestamp}.${raw_body}`) (hex) with a “sha256=” prefix. Use the raw body (before parsing), check the timestamp is no older than 5 minutes and compare in constant time. You can view the webhook secret by editing the key in the panel.

import crypto from "node:crypto";

// Express: app.post("/hook", express.raw({ type: "application/json" }), handler)
function verify(req, secret) {
  const ts = req.header("X-SocialAnalyze-Timestamp");
  const sig = req.header("X-SocialAnalyze-Signature") ?? "";
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // replay koruması
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(`${ts}.${req.body}`).digest("hex");
  const a = Buffer.from(sig), b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Delivery & retries

• Return 2xx for success. Respond within 10 seconds; push heavy work to the background.
• A failed delivery is retried after 1 min, 5 min, 30 min, 2 h and 6 h (6 attempts in total), then marked failed. You can retry manually from the key's log in the panel.
• The same event may arrive more than once (at-least-once): dedupe using the id field.
• Order is not guaranteed; rely on data.status and updated_at in the event.
• Use “Send test” in the panel to deliver a ping event.

#Error codes

Every error has the same shape. Branch on the stable error.code, not on the HTTP status or message.

{
  "error": {
    "code": "validation_failed",
    "message": "Instagram: Reels için tek video seçin.",
    "details": { "targets": { "fb17aa48-a440-470b-af3d-873044f93d54": "Instagram: Reels için tek video seçin." } }
  }
}

#Limits

#Plans & API allowance

The external API is metered like a separate service: it has its own monthly post and video allowance, key count and request rate. It is included from Studio up; on a lower plan it can be added as a separate service with an allowance sized to your needs.

#Best practices

• Put an Idempotency-Key on every POST. Derive it from your content id (e.g. cms-post-4821-v3); retry with the same key on 429/5xx or timeouts.
• Honour Retry-After on 429 and back off exponentially. Spread bulk imports below the per-minute limit.
• Get results by webhook. As a safety net, reconcile occasionally with GET /publications?status=publishing,partial,failed.
• Validate first. In approval flows show users where a post will go (and why not) using validate_only:true.
• For big videos: media first, post second. Finish import/upload well before the scheduled time; only ready media can be attached.
• Surface platform errors. On partial/failed, targets[].result.error carries the platform's real error; fix and retry via PATCH + /publish.
• Grant least privilege. Use the “Scheduling” preset (no immediate publishing) for review workflows, a separate key per integration and an IP allowlist where possible.
• One key set per brand. A key reaches a single brand; in multi-brand systems keep a brand → key mapping on your side.

#Changelog