SotialMedia API

1. Create a draft in a workspace. The draft is channel-agnostic; per-channel overrides are optional variants.

curl -X POST https://sotialmedia.com/api/v1/workspaces/$WORKSPACE_ID/drafts \
  -H "Authorization: Bearer $SOTIALMEDIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Launch day",
    "body": "We are live. Read the announcement on our site."
  }'

2. Schedule it on a connected account. scheduledFor is either an instant with a zone offset or a wall clock time in timezone. Send an Idempotency-Key so a retried request never creates a second publication: the same key with the same body returns the original (with Idempotent-Replayed: true), the same key with a different body is rejected with 422 idempotency_mismatch.

curl -X POST https://sotialmedia.com/api/v1/workspaces/$WORKSPACE_ID/publications \
  -H "Authorization: Bearer $SOTIALMEDIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-2026-11-02-x" \
  -d '{
    "draftId": "$DRAFT_ID",
    "socialConnectionId": "$CONNECTION_ID",
    "scheduledFor": "2026-11-02T09:00:00",
    "timezone": "America/Denver"
  }'

3. Poll the publication or subscribe to webhooks. The detail response includes the status history and an attempt summary; platform level request details stay with operators.

curl https://sotialmedia.com/api/v1/workspaces/$WORKSPACE_ID/publications/$PUBLICATION_ID \
  -H "Authorization: Bearer $SOTIALMEDIA_API_KEY"

Register an HTTPS endpoint and choose event types (publication.scheduled, publication.published, publication.failed, publication.needs_attention, publication.cancelled, connection.connected, connection.revoked, connection.error). Each delivery is a POST with a JSON body { type, occurredAt, data } and the header:

X-SotialMedia-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">

Verify with the signing secret shown once when the endpoint is created. After a rotation, deliveries carry two v1 values for 24 hours so you can switch secrets without downtime. Reject timestamps older than five minutes. Failed deliveries are retried with exponential backoff; the delivery log is available through the API and the console.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifySotialMediaSignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return header.split(",").some((p) => p.startsWith("v1=") && safeEqual(p.slice(3), expected));
}

function safeEqual(a, b) {
  const x = Buffer.from(a, "hex"), y = Buffer.from(b, "hex");
  return x.length === y.length && timingSafeEqual(x, y);
}