JSON in, JSON out. Bearer auth, rate-limited. This reference is generated from the OpenAPI spec, so it cannot drift from what the API actually does.
One public call returns your first key. The plaintext is shown once, store it now. No waitlist, no dashboard required, an agent can run this step itself. Prefer a UI? Sign in at app.socialkit.sh to mint and manage keys from the dashboard.
curl -X POST https://api.socialkit.sh/v1/account \
-H "Content-Type: application/json" \
-d '{ "email": "you@example.com" }'export SOCIALKIT_KEY="sk_live_..."curl -X POST https://api.socialkit.sh/v1/score \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{
"post": "Most onboarding flows fail at step one. We cut ours from 11 fields to 3 and activation jumped 40% in a week."
}'const res = await fetch("https://api.socialkit.sh/v1/score", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SOCIALKIT_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"post": "Most onboarding flows fail at step one. We cut ours from 11 fields to 3 and activation jumped 40% in a week."
}),
});
const data = await res.json();
console.log(data.overall, data.verdict);import os, requests
res = requests.post(
"https://api.socialkit.sh/v1/score",
headers={"Authorization": f"Bearer {os.environ['SOCIALKIT_KEY']}"},
json={
"post": "Most onboarding flows fail at step one. We cut ours from 11 fields to 3 and activation jumped 40% in a week."
},
)
data = res.json()
print(data["overall"], data["verdict"])You get an overall score (0-100), a one-line verdict, a per-dimension breakdown, and a ranked list of signals. See ScoreResult.
The visual engine returns a finished post: caption, hashtags, rendered image masters, and the design judge's score. How it decides, renders, judges, and revises is documented on how it works. Visual calls are model-backed and slow by API standards, tens of seconds to a few minutes, so send an Idempotency-Key header and be patient with timeouts. Like every model-backed call, a successful call costs one credit; a blocked result costs nothing.
businessContext.businessName is the only required context field, but everything you add grounds the result: the brand kit locks palette and fonts, the proof bank feeds specific claims, and real photos always lead over generated imagery.
curl -X POST https://api.socialkit.sh/v1/generate-visual-v2 \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: first-visual-post" \
-d '{
"businessContext": {
"businessName": "Driftwood Roasters",
"industry": "specialty coffee roaster",
"brandKit": {
"palette": { "primary": "#2B1D16", "secondary": "#F3EBDD", "accent": "#C96F2E" },
"fonts": { "display": "Oswald", "body": "Lato" }
},
"proofBank": [
{ "id": "p1", "kind": "fact", "text": "every bag roasted within 48 hours of shipping" }
]
},
"seed": { "platform": "instagram", "idea": "the Tuesday roast", "goal": "awareness" }
}'masters carries the rendered images per aspect ratio, caption and hashtags are platform-native, score is the judge's verdict, and spec is the post's revisable recipe. Treat the spec as opaque and store it. See GeneratedVisualPost.
Hand the spec back with freeform feedback. The revision is surgical: what the feedback does not target is held verbatim, so the photo stays while the headline moves.
curl -X POST https://api.socialkit.sh/v1/revise-visual-v2 \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{
"businessContext": { "businessName": "Driftwood Roasters" },
"feedback": "shorter headline, keep the photo",
"spec": { ...the spec from step 01 }
}'POST /v1/generate-carousel-v2 plans and renders a full swipe deck in one frame family with per-slide roles, and POST /v1/revise-carousel-v2 refines it the same way. See the Visual reference.
The published SDKs cover the text surface today; call the visual endpoints over REST until SDK support lands.
Every endpoint below is also exposed as an MCP tool at mcp.socialkit.sh, authed with the same bearer key. Point any MCP-aware client (Claude Code, Cursor, your own agent) at it and the whole toolkit shows up natively: score, rewrite, validate, generate, plan, plus the full post lifecycle and read-back of scores and metrics.
claude mcp add --transport http socialkit \
https://mcp.socialkit.sh \
--header "Authorization: Bearer $SOCIALKIT_KEY"{
"mcpServers": {
"socialkit": {
"type": "http",
"url": "https://mcp.socialkit.sh",
"headers": { "Authorization": "Bearer $SOCIALKIT_KEY" }
}
}
}Discovery is keyless, so an agent can read the catalog before it signs up. Tool calls use the same JSON contracts as REST and the bearer key. See the full catalog and the draft → grade → rewrite loop on the AI page.
# discover (no key needed)
curl https://mcp.socialkit.sh/tools/list
# call a tool (key required)
curl https://mcp.socialkit.sh -X POST \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"score_post","arguments":{"platform":"linkedin","post":"..."}}}'The server is more than tools. It also serves prompts (the canonical draft → grade → rewrite workflows your client can run) and resources (your account, brands, voices, channels, and calibration as attachable context, so a model can ground a draft without a tool call). Every tool carries read/write annotations, so a client auto-runs reads and confirms destructive writes. Details on the AI page.
A platform can run SocialKit for its own users without giving them SocialKit accounts. SocialKit issues the platform a partner key (sk_partner_...). The partner provisions tenants, one isolated SocialKit context per workspace, mints each tenant a key (sk_tenant_...), and reads one statement for all of them. A tenant generates, scores, rewrites, plans and renders with every brand and voice it owns. It never publishes: channels, scheduling, publishing and metrics answer not_available_for_tenants and its capabilities say so up front. Partner keys are issued by SocialKit, not self-serve: hello@socialkit.sh.
curl -X PUT https://api.socialkit.sh/v1/partner/tenants/ws_123 \
-H "Authorization: Bearer $PARTNER_KEY" -H "Content-Type: application/json" \
-d '{"name":"Acme Dental","brand":{"name":"Acme Dental","description":"Family dentistry in Austin"}}'curl -X POST https://api.socialkit.sh/v1/partner/tenants/ws_123/keys \
-H "Authorization: Bearer $PARTNER_KEY" -d '{"name":"agent-runtime"}'One bearer, no header plumbing, on REST or MCP. Or act as the tenant with the partner key plus X-SocialKit-Tenant, and attribute calls with X-SocialKit-Actor.
curl -X POST https://api.socialkit.sh/v1/generate \
-H "Authorization: Bearer $TENANT_KEY" -H "Content-Type: application/json" \
-d '{"platform":"linkedin","brief":"Announce Saturday hours"}'
# or, with the partner key
curl -X POST https://api.socialkit.sh/v1/generate \
-H "Authorization: Bearer $PARTNER_KEY" -H "X-SocialKit-Tenant: ws_123" \
-H "X-SocialKit-Actor: user_7" -H "Content-Type: application/json" \
-d '{"platform":"linkedin","brief":"Announce Saturday hours"}'curl "https://api.socialkit.sh/v1/partner/usage?period=2026-10" \
-H "Authorization: Bearer $PARTNER_KEY"
# or line by line, as CSV, for finance
curl "https://api.socialkit.sh/v1/partner/usage/export?period=2026-10" \
-H "Authorization: Bearer $PARTNER_KEY" -o statement.csv
# and who changed what, newest first
curl "https://api.socialkit.sh/v1/partner/audit" \
-H "Authorization: Bearer $PARTNER_KEY"Seed a kit on the brand (palette, fonts, a logo and photos by media id, uploaded by the tenant) and name the brand with brandId on a visual call: the engine grounds itself from it, and anything sent in businessContext alongside wins. A signed URL puts the rendered master straight into an <img src>. A tenant key minted with toolProfile: "core" presents the curated MCP catalog (generate, score, rewrite, plan, brands, voices, account, sign_media_url); what it may call does not change.
curl -X PUT https://api.socialkit.sh/v1/partner/tenants/ws_123 \
-H "Authorization: Bearer $PARTNER_KEY" -H "Content-Type: application/json" \
-d '{"brand":{"name":"Acme Dental","kit":{"palette":{"primary":"#004488","accent":"#FFB000"},
"fonts":{"display":"Anton","body":"Inter"},"logo":{"mediaId":"med_...","placement":"top-right"},
"photoMediaIds":["med_..."]}}}'
curl -X POST https://api.socialkit.sh/v1/generate-visual-v2 \
-H "Authorization: Bearer $TENANT_KEY" -H "Content-Type: application/json" \
-d '{"brandId":"brd_...","seed":{"platform":"instagram","idea":"Saturday hours"}}'
curl -X POST https://api.socialkit.sh/v1/media/med_.../signed-url \
-H "Authorization: Bearer $TENANT_KEY" -d '{"ttlSeconds":3600}'
# -> {"url":"https://api.socialkit.sh/v1/media/med_.../content?token=...","expiresAt":...}Metering is per tenant and per partner: a tenant meters into its own monthly bucket and the partner's aggregate, with weighted credits per operation (an image post costs 3, a carousel 5, everything else 1 by default). A refused call never charges, and a quota_exceeded or rate_limited error names its scope (tenant or partner). Deleting a tenant stops its keys at once and purges its data shortly after. The endpoints are under the Partner tag below; the operations a tenant cannot call carry a Not for tenants badge.
A partner's own people work it from the dashboard. Once SocialKit grants an email as an operator, app.socialkit.sh shows that person a context switcher (their personal account, then each partner) and a partner context at /p/<slug>: the overview and caps, tenants, the statement with a CSV download, the audit trail, and the writes an operator needs (mint and revoke partner keys, create and delete tenants, mint and revoke tenant keys, invite and remove operators), each audited as that person. Caps, status and credit weights stay with SocialKit.
Every request carries a single secret: your API key, sent as a bearer token. Keys are scoped to one account, start with sk_live_, and are shown in plaintext exactly once at creation. Store them like a password and rotate from the dashboard if one leaks.
curl https://api.socialkit.sh/v1/account \
-H "Authorization: Bearer $SOCIALKIT_KEY"No key yet? POST /v1/account mints one with no waitlist (see Quickstart), or sign in at app.socialkit.sh. A missing or revoked key returns 401 unauthorized. Discovery is keyless, so an agent can read GET /v1/meta and the MCP handshake before it signs up.
GET /v1/health is a keyless readiness probe: it checks the database and key-value store and returns 200 when both are healthy, 503 when either is degraded. For a bare liveness check with no dependency I/O, hit GET /healthz (returns the text ok) on any host.
Every error uses the same envelope, so one handler covers them all. The code is a stable machine string; the message is human-readable and may change. The requestId is unique to the call, also returned in the x-request-id response header on every request, success or failure. Log it, and quote it to support so we can pull the exact call from our logs.
{ "error": { "code": "quota_exceeded", "message": "Monthly credit allotment exhausted...", "requestId": "8f3c...-TLV" } }| Status | code | When |
|---|---|---|
| 400 | invalid_request, unsupported_platform | Malformed body, a failed field validation, or a post whose platform has no connected driver. |
| 401 | unauthorized | Missing, invalid, or revoked bearer key. |
| 402 | quota_exceeded | Monthly credit allotment spent. Upgrade or wait for the reset. |
| 404 | not_found | No such resource, or not owned by your key. |
| 409 | account_exists, invalid_state, idempotency_key_reused | A state clash: a duplicate signup, canceling a published post, or reusing an Idempotency-Key with a different body. |
| 429 | rate_limited | Request or LLM rate limit exceeded. Honor retry-after. |
| 503 | not_configured | A deployment-gated capability (publish, metrics) is not enabled on this deployment. |
| 5xx | internal, capability_failed | Our fault or an upstream model failure. Retry with backoff; the call was not charged. |
Two independent budgets guard every key: request volume and a tighter LLM-call budget, both enforced per key, plus monthly credits enforced per account. A credit is charged only after an LLM call succeeds, so a 429 or 402 never costs you one. Every authed response carries the request-budget headers; the model-backed endpoints (score, generate, rewrite, plan, and voice distillation) add the LLM-budget and credit headers on top:
| Header | On | Meaning |
|---|---|---|
x-ratelimit-limit / -remaining / -reset | Every authed response | Per-key request budget: ceiling, requests left, and the Unix second the window resets. |
x-ratelimit-llm-limit / -remaining / -reset | Model-backed endpoints | The tighter per-key budget for LLM-backed calls, same shape as above. |
x-credits-limit / -used / -remaining / -reset | Model-backed endpoints | Your account's monthly credit standing: plan allotment, used, left, and the Unix second the cycle resets. |
retry-after | 429 and 402 | Seconds to wait before retrying. |
Side-effectful calls are retry-safe. Send an Idempotency-Key header (any unique string up to 255 chars, a UUID is ideal) on the model calls (POST /v1/score, /v1/rewrite, /v1/generate, /v1/plan) or the creation calls (POST /v1/posts, POST /v1/posts/bulk-schedule). The first successful response is cached per key for 24 hours; a retry with the same header returns that exact response with idempotent-replay: true and does no new work, so a retried model call charges no second credit and a retried creation makes no duplicate. The body is fingerprinted with the key, so reusing a key with a different body returns 409 idempotency_key_reused instead of the stale result; a retry must be identical. Only 2xx responses are cached, so a failed call stays retryable.
curl -X POST https://api.socialkit.sh/v1/posts \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f9c1b2a-..." \
-d '{ "platform": "linkedin", "text": "..." }'List endpoints (GET /v1/posts, GET /v1/media, GET /v1/webhooks/:id/deliveries) take limit (default 50, max 100) and offset (default 0) query params. A non-numeric value is a 400 invalid_request. Each response carries a pagination object; keep paging while hasMore is true.
GET https://api.socialkit.sh/v1/posts?limit=50&offset=0
{
"posts": [ /* ... */ ],
"pagination": { "limit": 50, "offset": 0, "hasMore": true }
}Register an endpoint and SocialKit POSTs you a signed JSON event when something happens: a scheduled post goes live, a publish fails for good, a score lands, or a channel disconnects. Create and manage endpoints through the Webhooks API; the secret is returned once at creation, store it then.
| Event | Fires when |
|---|---|
post.published | A scheduled post is successfully published to its channel. |
post.failed | A post is dead-lettered after the scheduler exhausts its retries. |
post.scored | A post is scored (manually or as part of a flow). |
channel.disconnected | A connected channel's token is revoked or expires. |
Every delivery is the same envelope. The data shape depends on the event. The body is byte-identical across retries, so verify against the exact bytes you receive.
{
"id": "whd_...", // unique delivery id
"event": "post.published",
"createdAt": 1717689600000,
"data": { /* event-specific */ }
}| Header | Meaning |
|---|---|
x-socialkit-event | The event name, e.g. post.published. |
x-socialkit-delivery | Delivery id, also echoed in the body. Use it to dedupe retries. |
x-socialkit-timestamp | Unix seconds when the delivery was signed. Check it is recent. |
x-socialkit-signature | sha256=<hex>, an HMAC over the signed payload (below). |
The signature is an HMAC-SHA256 of {timestamp}.{rawBody} keyed with your endpoint secret, hex-encoded. Binding the timestamp into the signature lets you reject replays: check the timestamp is recent before comparing, and always compare in constant time.
import crypto from "node:crypto";
// rawBody MUST be the exact bytes received, not a re-serialized object.
function verifyWebhook(rawBody, headers, secret) {
const ts = headers["x-socialkit-timestamp"];
const sig = headers["x-socialkit-signature"]; // "sha256=<hex>"
// Reject anything older than 5 minutes to stop replays.
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const expected =
"sha256=" +
crypto.createHmac("sha256", secret)
.update(`${ts}.${rawBody}`)
.digest("hex");
const a = Buffer.from(sig);
const b = Buffer.from(expected);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}Return a 2xx within 10 seconds to acknowledge. Any other status, a timeout, or a connection error is retried up to 5 times with exponential backoff (1m, 5m, 30m, 2h), then dead-lettered. Make your handler idempotent on x-socialkit-delivery, since a slow 2xx can still be redelivered. Inspect delivery history with GET /v1/webhooks/:id/deliveries.
Score, rewrite, plan, generate. The knowledge primitives.
/v1/scoreBearerGrades a draft against the platform's feed-ranking behavior and returns an overall score (0-100), a per-dimension breakdown, ranked signals (what helps, what leaks reach), the detected hook archetype, and the format multiplier. LinkedIn and X are live, each scored with its own platform rubric; set `platform` to choose.
Idempotency-Keyrequired | string | A client-chosen key (max 255 chars) that makes this call safe to retry. The first successful (2xx) response is cached per API key for 24 hours; replaying the same key returns that stored response verbatim with an `idempotent-replay: true` header and does no new work, so a retried model call (score, rewrite, generate, plan) charges no second credit and a retried creation creates nothing new. The request body is fingerprinted with the key: reusing a key with a different body returns `409 idempotency_key_reused` rather than the stale stored result, so a retry must be identical. Non-2xx responses are not cached, so a failed call leaves the key reusable. Best-effort: a sequential retry after a timeout is deduped, but two truly concurrent requests may both execute. |
curl -X POST https://api.socialkit.sh/v1/score \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{
"post": "Most onboarding flows fail at step one. We cut ours from 11 fields to 3 and activation jumped 40% in a week."
}'/v1/rewriteBearerScores the original, rewrites it to lift the weak dimensions without inventing facts, then re-grades the rewrite. Returns both scores and the list of changes made. The after-score is reported as measured; it is never massaged to look like an improvement. Set `platform` to `linkedin` (default) or `x`; each rewrites against its own ranker.
Idempotency-Keyrequired | string | A client-chosen key (max 255 chars) that makes this call safe to retry. The first successful (2xx) response is cached per API key for 24 hours; replaying the same key returns that stored response verbatim with an `idempotent-replay: true` header and does no new work, so a retried model call (score, rewrite, generate, plan) charges no second credit and a retried creation creates nothing new. The request body is fingerprinted with the key: reusing a key with a different body returns `409 idempotency_key_reused` rather than the stale stored result, so a retry must be identical. Non-2xx responses are not cached, so a failed call leaves the key reusable. Best-effort: a sequential retry after a timeout is deduped, but two truly concurrent requests may both execute. |
curl -X POST https://api.socialkit.sh/v1/rewrite \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{
"post": "We are excited to announce that our team has been working hard on some new features we think you will really love."
}'/v1/generateBearerDrafts up to three native posts from a brief, scores each, and returns them sorted by overall score (best first). Set `platform` to `linkedin` (default) or `x`; each uses its own writing rubric.
Idempotency-Keyrequired | string | A client-chosen key (max 255 chars) that makes this call safe to retry. The first successful (2xx) response is cached per API key for 24 hours; replaying the same key returns that stored response verbatim with an `idempotent-replay: true` header and does no new work, so a retried model call (score, rewrite, generate, plan) charges no second credit and a retried creation creates nothing new. The request body is fingerprinted with the key: reusing a key with a different body returns `409 idempotency_key_reused` rather than the stale stored result, so a retry must be identical. Non-2xx responses are not cached, so a failed call leaves the key reusable. Best-effort: a sequential retry after a timeout is deduped, but two truly concurrent requests may both execute. |
curl -X POST https://api.socialkit.sh/v1/generate \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{
"brief": "A shipping receipt about cutting onboarding to 3 fields",
"count": 1
}'/v1/planBearerReturns a calendar of post ideas spread across content pillars and hook archetypes. Each item is an outline (hook, angle, format, archetype), not a finished draft. Use generate to expand an item into a post. Set `platform` to plan for LinkedIn (default) or X; each platform uses its own content pillars and media set.
Idempotency-Keyrequired | string | A client-chosen key (max 255 chars) that makes this call safe to retry. The first successful (2xx) response is cached per API key for 24 hours; replaying the same key returns that stored response verbatim with an `idempotent-replay: true` header and does no new work, so a retried model call (score, rewrite, generate, plan) charges no second credit and a retried creation creates nothing new. The request body is fingerprinted with the key: reusing a key with a different body returns `409 idempotency_key_reused` rather than the stale stored result, so a retry must be identical. Non-2xx responses are not cached, so a failed call leaves the key reusable. Best-effort: a sequential retry after a timeout is deduped, but two truly concurrent requests may both execute. |
curl -X POST https://api.socialkit.sh/v1/plan \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{
"brief": "AI-native engineering and build-in-public receipts",
"count": 5,
"cadence": "weekdays"
}'The visual engine: finished posts and carousels with rendered images. A call takes a brief plus a brand kit, deals a layout archetype and a typography voice, renders the design deterministically, and grades the result with a design judge before returning it. Every response carries a serializable, revisable spec; hand it back with freeform feedback to refine a post without re-rolling it.
/v1/generate-visual-v2BearerTurns a brief and a brand kit into a finished, postable post: caption, hashtags, on-image text, rendered image masters, and the design judge's score. The engine deals a layout archetype and a typography voice, renders deterministically, judges the result, and revises what falls short before returning. The response's `spec` is the post's revisable recipe; hand it to `/v1/revise-visual-v2` with feedback to refine without re-rolling. Model-backed and slow (tens of seconds to a few minutes); costs one credit on success.
Idempotency-Keyrequired | string | A client-chosen key (max 255 chars) that makes this call safe to retry. The first successful (2xx) response is cached per API key for 24 hours; replaying the same key returns that stored response verbatim with an `idempotent-replay: true` header and does no new work, so a retried model call (score, rewrite, generate, plan) charges no second credit and a retried creation creates nothing new. The request body is fingerprinted with the key: reusing a key with a different body returns `409 idempotency_key_reused` rather than the stale stored result, so a retry must be identical. Non-2xx responses are not cached, so a failed call leaves the key reusable. Best-effort: a sequential retry after a timeout is deduped, but two truly concurrent requests may both execute. |
curl -X POST https://api.socialkit.sh/v1/generate-visual-v2 \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{
"businessContext": {
"businessName": "Driftwood Roasters",
"industry": "specialty coffee roaster",
"brandKit": {
"palette": {
"primary": "#2B1D16",
"secondary": "#F3EBDD",
"accent": "#C96F2E"
},
"fonts": {
"display": "Oswald",
"body": "Lato"
}
}
},
"seed": {
"platform": "instagram",
"idea": "the Tuesday roast: Yirgacheffe, floral, sold by Friday",
"goal": "awareness"
}
}'/v1/revise-visual-v2BearerTakes the `spec` from a prior generate plus a freeform comment ("shorter headline", "warmer photo") and returns the refined post. The revision is surgical where possible: anything the feedback does not target is held verbatim, so the photo stays while the headline moves. Costs one credit on success.
Idempotency-Keyrequired | string | A client-chosen key (max 255 chars) that makes this call safe to retry. The first successful (2xx) response is cached per API key for 24 hours; replaying the same key returns that stored response verbatim with an `idempotent-replay: true` header and does no new work, so a retried model call (score, rewrite, generate, plan) charges no second credit and a retried creation creates nothing new. The request body is fingerprinted with the key: reusing a key with a different body returns `409 idempotency_key_reused` rather than the stale stored result, so a retry must be identical. Non-2xx responses are not cached, so a failed call leaves the key reusable. Best-effort: a sequential retry after a timeout is deduped, but two truly concurrent requests may both execute. |
curl -X POST https://api.socialkit.sh/v1/revise-visual-v2 \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{
"feedback": "string",
"spec": {}
}'/v1/generate-carousel-v2BearerPlans and renders a full swipe deck from a brief and a brand kit: an arc of slides in one frame family with per-slide roles, a caption, hashtags, and a set-level design score. Real brand photos lead when the context carries them; generated imagery stays name-free and atmospheric. The response's `spec` is the deck's revisable recipe for `/v1/revise-carousel-v2`. Model-backed and slow; costs one credit on success.
Idempotency-Keyrequired | string | A client-chosen key (max 255 chars) that makes this call safe to retry. The first successful (2xx) response is cached per API key for 24 hours; replaying the same key returns that stored response verbatim with an `idempotent-replay: true` header and does no new work, so a retried model call (score, rewrite, generate, plan) charges no second credit and a retried creation creates nothing new. The request body is fingerprinted with the key: reusing a key with a different body returns `409 idempotency_key_reused` rather than the stale stored result, so a retry must be identical. Non-2xx responses are not cached, so a failed call leaves the key reusable. Best-effort: a sequential retry after a timeout is deduped, but two truly concurrent requests may both execute. |
curl -X POST https://api.socialkit.sh/v1/generate-carousel-v2 \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{
"businessContext": {
"businessName": "Kiln House Ceramics",
"industry": "ceramics studio"
},
"seed": {
"platform": "instagram",
"idea": "wheel-throwing 101: your first cup in one session",
"goal": "save",
"slideCount": 5
}
}'/v1/revise-carousel-v2BearerTakes the `spec` from a prior carousel generate plus a freeform comment and returns the refined deck. Slides the feedback does not target are kept verbatim, backgrounds included, and the set is re-judged as a whole. Costs one credit on success.
Idempotency-Keyrequired | string | A client-chosen key (max 255 chars) that makes this call safe to retry. The first successful (2xx) response is cached per API key for 24 hours; replaying the same key returns that stored response verbatim with an `idempotent-replay: true` header and does no new work, so a retried model call (score, rewrite, generate, plan) charges no second credit and a retried creation creates nothing new. The request body is fingerprinted with the key: reusing a key with a different body returns `409 idempotency_key_reused` rather than the stale stored result, so a retry must be identical. Non-2xx responses are not cached, so a failed call leaves the key reusable. Best-effort: a sequential retry after a timeout is deduped, but two truly concurrent requests may both execute. |
curl -X POST https://api.socialkit.sh/v1/revise-carousel-v2 \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{
"feedback": "string",
"spec": {}
}'Sign up and manage API keys.
/v1/metaPublicPublic endpoint. Returns the scoring schema (version, max post length, supported platforms, media kinds, follower bands, and the six scoring dimensions with their weights) plus this deployment's live capabilities. Read it to build a valid request without scraping docs and to branch on what the deployment can do before attempting an action.
curl https://api.socialkit.sh/v1/meta/v1/healthPublicPublic readiness probe. Exercises the service's data dependencies (the database and key-value store) and reports each, so a green result means the service can serve real requests, not just that the process booted. Returns `200` when every check is `ok` and `503` when any dependency is degraded, so an uptime monitor can page on it. For a bare liveness check with no dependency I/O, use `GET /healthz` (returns the text `ok`).
curl https://api.socialkit.sh/v1/health/v1/accountBearerReturns the account and the API key making the request. The cheapest authed call: use it to confirm a key is live and read the plan, and read the `X-RateLimit-*` response headers for the current request budget before spending real quota.
curl https://api.socialkit.sh/v1/account \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/accountPublicPublic endpoint. Creates an account for an email and returns the first API key in plaintext. The plaintext is shown exactly once; store it now. Rate limited per IP.
curl -X POST https://api.socialkit.sh/v1/account \
-H "Content-Type: application/json" \
-d '{
"email": "string"
}'/v1/keysBearerReturns key metadata only. Secrets are never returned.
curl https://api.socialkit.sh/v1/keys \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/keysBearercurl -X POST https://api.socialkit.sh/v1/keys \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{}'/v1/keys/{id}/rotateBeareridrequired | string | The API key id (e.g. `key_...`). |
curl -X POST https://api.socialkit.sh/v1/keys/key_8fa3c1d9/rotate \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/keys/{id}Beareridrequired | string | The API key id (e.g. `key_...`). |
curl -X DELETE https://api.socialkit.sh/v1/keys/key_8fa3c1d9 \
-H "Authorization: Bearer $SOCIALKIT_KEY"The partner tier: a platform runs SocialKit for its own users. A partner key (`sk_partner_...`, issued by SocialKit) provisions tenants, mints their `sk_tenant_...` keys and reads statements. A tenant is an isolated SocialKit context the partner owns: it uses every generation, memory and draft endpoint with its tenant key, meters into its own monthly bucket and the partner's aggregate, and never publishes (channels, scheduling, publishing and metrics are refused with `not_available_for_tenants`). A partner can also act as one of its tenants by sending the partner key with `X-SocialKit-Tenant: <externalId>`.
/v1/partnerBearerPartner keys only. Returns the partner profile, the calling key, the live tenant count and the partner-wide credit standing for the current month. Every partner call carries the partner-wide request budget in the `x-ratelimit-*` headers.
curl https://api.socialkit.sh/v1/partner \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/partner/keys/rotateBearerReturns a new partner key in plaintext, exactly once. The partner's other live keys keep working for 24 hours so a vault can roll without an outage; pass `immediate=true` (a leaked key) to revoke them now.
immediaterequired | boolean | Revoke the other live keys now instead of after the grace window. |
curl -X POST https://api.socialkit.sh/v1/partner/keys/rotate \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{}'/v1/partner/tenantsBearerNewest first, cursor-paginated. `status=deleted` lists tenants awaiting purge.
limitrequired | integer | Page size, 1-200 (default 50). |
cursorrequired | string | The `nextCursor` of the previous page. |
statusrequired | string | `active` (default) or `deleted`. |
curl https://api.socialkit.sh/v1/partner/tenants \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/partner/tenants/{externalId}BearerexternalIdrequired | string | The partner's handle for the tenant (e.g. a workspace id): 1-128 characters from `A-Z a-z 0-9 . _ : -`, unique per partner. |
curl https://api.socialkit.sh/v1/partner/tenants/id_8fa3c1d9 \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/partner/tenants/{externalId}BearerIdempotent: 201 when the tenant is created, 200 when it already exists. `externalId` is the partner's own handle for the tenant (a workspace id), unique per partner and opaque to SocialKit. `name` sets or updates the display name; `brand` seeds the tenant's default brand on first sight and updates it after. A tenant that is being deleted is refused with `409 tenant_deleting` until the purge frees its id.
externalIdrequired | string | The partner's handle for the tenant (e.g. a workspace id): 1-128 characters from `A-Z a-z 0-9 . _ : -`, unique per partner. |
curl -X PUT https://api.socialkit.sh/v1/partner/tenants/id_8fa3c1d9 \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Dental",
"brand": {
"name": "Acme Dental",
"description": "Family dentistry in Austin",
"audience": "Parents in Austin",
"themes": [
"new patient tips",
"behind the chair"
]
}
}'/v1/partner/tenants/{externalId}BearerTombstones the tenant now (its keys stop working at once) and purges its stored media and rows shortly after, in bounded batches. Idempotent: a repeated call reports the same `deleting` state.
externalIdrequired | string | The partner's handle for the tenant (e.g. a workspace id): 1-128 characters from `A-Z a-z 0-9 . _ : -`, unique per partner. |
curl -X DELETE https://api.socialkit.sh/v1/partner/tenants/id_8fa3c1d9 \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/partner/tenants/{externalId}/keysBearerexternalIdrequired | string | The partner's handle for the tenant (e.g. a workspace id): 1-128 characters from `A-Z a-z 0-9 . _ : -`, unique per partner. |
curl https://api.socialkit.sh/v1/partner/tenants/id_8fa3c1d9/keys \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/partner/tenants/{externalId}/keysBearerReturns an `sk_tenant_...` key in plaintext, exactly once. The tenant's agent runtime uses it on the REST and MCP surfaces like any SocialKit key, scoped to that tenant. At most 10 live keys per tenant.
externalIdrequired | string | The partner's handle for the tenant (e.g. a workspace id): 1-128 characters from `A-Z a-z 0-9 . _ : -`, unique per partner. |
curl -X POST https://api.socialkit.sh/v1/partner/tenants/id_8fa3c1d9/keys \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{}'/v1/partner/tenants/{externalId}/keys/{keyId}BearerexternalIdrequired | string | The partner's handle for the tenant (e.g. a workspace id): 1-128 characters from `A-Z a-z 0-9 . _ : -`, unique per partner. |
keyIdrequired | string | The tenant key id (e.g. `key_...`). |
curl -X DELETE https://api.socialkit.sh/v1/partner/tenants/key_8fa3c1d9/keys/key_8fa3c1d9 \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/partner/auditBearerEvery administrative change under this partner: tenants created and deleted, tenant keys minted, revoked and rotated (by the partner or by the tenant itself), partner keys created and rotated, cap and status changes made by SocialKit, operator grants. Keyset-paged; follow `nextCursor` until it is null. Kept for 13 months.
limitrequired | integer | Events per page (default 50, max 200). |
cursorrequired | string | The `nextCursor` of the previous page. |
curl https://api.socialkit.sh/v1/partner/audit \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/partner/usageBearerCredits charged across all tenants in a calendar month (default: the current one), by operation and by tenant. One row per successful model call is kept for 13 months; a refused or failed call never appears.
periodrequired | string | Calendar month as `YYYY-MM` (UTC). Defaults to the current month. |
curl https://api.socialkit.sh/v1/partner/usage \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/partner/usage/exportBearerEvery ledger row of the period (default: the current month), oldest first, as `text/csv` with the columns `id` (the ledger line, stable across exports), `at` (ISO 8601), `tenant` (the external id), `accountId`, `operation`, `calls`, `credits`, `actor`, `requestId`. Streamed in batches, so a month of any size downloads. For finance; `GET /v1/partner/usage` is the aggregate.
periodrequired | string | Calendar month as `YYYY-MM` (UTC). Defaults to the current month. |
curl https://api.socialkit.sh/v1/partner/usage/export \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/partner/tenants/{externalId}/usageBearerCredits by operation and by actor (the `X-SocialKit-Actor` the calls carried).
externalIdrequired | string | The partner's handle for the tenant (e.g. a workspace id): 1-128 characters from `A-Z a-z 0-9 . _ : -`, unique per partner. |
periodrequired | string | Calendar month as `YYYY-MM` (UTC). Defaults to the current month. |
curl https://api.socialkit.sh/v1/partner/tenants/id_8fa3c1d9/usage \
-H "Authorization: Bearer $SOCIALKIT_KEY"Brands and voices. Reusable context that conditions generation: a brand is workspace context, a voice is a writing profile. Pass their ids to generate and plan.
/v1/brandsBearercurl https://api.socialkit.sh/v1/brands \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/brandsBearercurl -X POST https://api.socialkit.sh/v1/brands \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "SocialKit",
"description": "The social primitive your agent calls.",
"audience": "Founders and developers shipping in public.",
"themes": [
"shipping receipts",
"AI-native engineering"
],
"linkPolicy": "Never link out in the body."
}'/v1/brands/{id}Beareridrequired | string | The brand id (e.g. `brd_...`). |
curl https://api.socialkit.sh/v1/brands/brd_8fa3c1d9 \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/brands/{id}BearerPartial update. Only the fields present in the body are changed.
idrequired | string | The brand id (e.g. `brd_...`). |
curl -X PATCH https://api.socialkit.sh/v1/brands/brd_8fa3c1d9 \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{}'/v1/brands/{id}BearerDeletes the brand. Voices attached to it are kept but detached (their brandId becomes null).
idrequired | string | The brand id (e.g. `brd_...`). |
curl -X DELETE https://api.socialkit.sh/v1/brands/brd_8fa3c1d9 \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/voicesBearercurl https://api.socialkit.sh/v1/voices \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/voicesBearerCreates a voice. Supply `samples` and the profile is distilled from them (the common path, same as POST /v1/voices/build). Omit `samples` and the explicit `traits`/`doNot`/`exemplars` you pass are stored as-is.
curl -X POST https://api.socialkit.sh/v1/voices \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Founder voice",
"samples": [
"We shipped the new scorer today. 11 dimensions down to 6.",
"Paused a $675/day campaign. The CAC math stopped working."
]
}'/v1/voices/buildBearerReads sample posts, extracts the traits to imitate, the things to never do, and a few exemplar snippets, then saves the result as a voice. Returns the saved voice; pass its id to generate or plan.
curl -X POST https://api.socialkit.sh/v1/voices/build \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Founder voice",
"samples": [
"We shipped the new scorer today. 11 dimensions down to 6.",
"Paused a $675/day campaign. The CAC math stopped working."
]
}'/v1/voices/{id}Beareridrequired | string | The voice id (e.g. `voi_...`). |
curl https://api.socialkit.sh/v1/voices/voi_8fa3c1d9 \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/voices/{id}BearerPartial update. Only the fields present in the body are changed.
idrequired | string | The voice id (e.g. `voi_...`). |
curl -X PATCH https://api.socialkit.sh/v1/voices/voi_8fa3c1d9 \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{}'/v1/voices/{id}Beareridrequired | string | The voice id (e.g. `voi_...`). |
curl -X DELETE https://api.socialkit.sh/v1/voices/voi_8fa3c1d9 \
-H "Authorization: Bearer $SOCIALKIT_KEY"Connected social accounts (OAuth pipes). Connect via the platform's OAuth flow, report health, refresh tokens, and disconnect. Tokens are encrypted at rest and never returned. LinkedIn is the only platform live today.
/v1/channelsBearerNot for tenantsReturns channel metadata only. Tokens are never included.
curl https://api.socialkit.sh/v1/channels \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/channels/linkedin/connectBearerNot for tenantsStarts the OAuth handshake. Returns an authorization URL to redirect the member to, plus the opaque state token that ties the callback back to this account. PKCE is handled for you. Disabled (503) when the deployment has no token-vault key or LinkedIn app credentials.
curl -X POST https://api.socialkit.sh/v1/channels/linkedin/connect \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{}'/v1/channels/linkedin/callbackPublicNot for tenantsWhere LinkedIn redirects after the member authorizes. Public: trust comes from the single-use, account-bound state, not the query params. Exchanges the code for tokens, seals them into the vault, and returns the connected channel. Not called directly by API clients.
coderequired | string | The authorization code from LinkedIn. |
staterequired | string | The opaque state token returned by connect. |
curl https://api.socialkit.sh/v1/channels/linkedin/callback/v1/channels/{id}BearerNot for tenantsidrequired | string | The channel id (e.g. `chn_...`). |
curl https://api.socialkit.sh/v1/channels/id_8fa3c1d9 \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/channels/{id}BearerNot for tenantsWipes the stored tokens (unrecoverable) and marks the channel revoked. The row is kept for history.
idrequired | string | The channel id (e.g. `chn_...`). |
curl -X DELETE https://api.socialkit.sh/v1/channels/id_8fa3c1d9 \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/channels/{id}/refreshBearerNot for tenantsRefreshes the access token if it is at or near expiry; a no-op when the token is still fresh. Returns the current channel either way.
idrequired | string | The channel id (e.g. `chn_...`). |
curl -X POST https://api.socialkit.sh/v1/channels/id_8fa3c1d9/refresh \
-H "Authorization: Bearer $SOCIALKIT_KEY"Uploaded images, video, and PDF carousels referenced by posts at publish time. Bytes are stored in object storage; the API returns metadata and a content download endpoint.
/v1/mediaBearerResults are paginated newest-first; page with limit and offset and follow pagination.hasMore.
limitrequired | integer | Maximum media items to return (default 50, max 100). |
offsetrequired | integer | Number of media items to skip from the newest. |
curl https://api.socialkit.sh/v1/media \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/mediaBearerUpload raw bytes with the file's Content-Type header (validated against an allowlist). Optionally scope to a brand with the brandId query param and supply a filename with the X-Filename header. Returns the stored media metadata.
brandIdrequired | string | Optional brand to attach the media to. Must belong to the account. |
X-Filenamerequired | string | Optional original filename, reduced to a basename. |
curl -X POST https://api.socialkit.sh/v1/media \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/media/{id}Beareridrequired | string | The media id (e.g. `med_...`). |
curl https://api.socialkit.sh/v1/media/id_8fa3c1d9 \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/media/{id}BearerRemoves the metadata row and the stored object.
idrequired | string | The media id (e.g. `med_...`). |
curl -X DELETE https://api.socialkit.sh/v1/media/id_8fa3c1d9 \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/media/{id}/contentBearerWith a bearer key, the account's own media. With a `token` from `POST /v1/media/{id}/signed-url` instead, the same bytes with no key at all (what an `<img src>` in a partner UI uses); an expired token answers `token_expired`, a forged one `invalid_token`.
idrequired | string | The media id (e.g. `med_...`). |
tokenrequired | string | A signed-URL token, in place of the bearer key. |
curl https://api.socialkit.sh/v1/media/id_8fa3c1d9/content \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/media/{id}/signed-urlBearerA link to `GET /v1/media/{id}/content` that carries its own authorization, so a UI can show a rendered master or an upload without holding a key. Default 1 hour, at most 24 hours. Store the media id and sign again when needed, never the URL. Free: no credit, no model call.
idrequired | string | The media id (e.g. `med_...`). |
curl -X POST https://api.socialkit.sh/v1/media/id_8fa3c1d9/signed-url \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{}'The content lifecycle: draft, schedule, publish. Posts move through a strict state machine (draft -> scheduled/publishing -> published/failed). Publishing is exactly-once: a replayed or concurrent publish returns 409.
/v1/postsBearerOptionally filter by status. Results are paginated newest-first; page with limit and offset and follow pagination.hasMore. Posts carry no token material.
statusrequired | string | Filter to one post status. |
limitrequired | integer | Maximum posts to return (default 50, max 100). |
offsetrequired | integer | Number of posts to skip from the newest. |
curl https://api.socialkit.sh/v1/posts \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/postsBearerCreates a post. Supply the text plus optional brand, channel, and media references. Any brandId or channelId must belong to the calling account. Omit runAt to create a draft; pass runAt (epoch ms) to create and schedule the post in one call (it comes back in the `scheduled` state). Pass an Idempotency-Key header to make a retry of this call safe (a replay returns the original post, not a duplicate).
Idempotency-Keyrequired | string | A client-chosen key (max 255 chars) that makes this call safe to retry. The first successful (2xx) response is cached per API key for 24 hours; replaying the same key returns that stored response verbatim with an `idempotent-replay: true` header and does no new work, so a retried model call (score, rewrite, generate, plan) charges no second credit and a retried creation creates nothing new. The request body is fingerprinted with the key: reusing a key with a different body returns `409 idempotency_key_reused` rather than the stale stored result, so a retry must be identical. Non-2xx responses are not cached, so a failed call leaves the key reusable. Best-effort: a sequential retry after a timeout is deduped, but two truly concurrent requests may both execute. |
curl -X POST https://api.socialkit.sh/v1/posts \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "We cut onboarding from 11 fields to 3. Activation up 40%."
}'/v1/posts/validateBearerA fast, no-LLM, nothing-persisted check that returns every structural error and reach/voice warning at once, so an agent can fix them in one pass before spending a score or committing to create/publish. Errors block a clean publish (empty text, over length, unsupported platform, invalid media). Warnings are reach or voice hazards (6+ hashtags, an external link in the body, engagement-bait phrases, AI-tells).
curl -X POST https://api.socialkit.sh/v1/posts/validate \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{
"post": "Excited to share our new feature! Thoughts? Follow for more. #ai #saas #growth #startup #founder #buildinpublic"
}'/v1/posts/{id}Beareridrequired | string | The post id (e.g. `pst_...`). |
curl https://api.socialkit.sh/v1/posts/id_8fa3c1d9 \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/posts/{id}BearerPartial update. Only draft posts can be edited; editing a post in any other state returns 409. Omit a field to leave it unchanged.
idrequired | string | The post id (e.g. `pst_...`). |
curl -X PATCH https://api.socialkit.sh/v1/posts/id_8fa3c1d9 \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{}'/v1/posts/{id}Beareridrequired | string | The post id (e.g. `pst_...`). |
curl -X DELETE https://api.socialkit.sh/v1/posts/id_8fa3c1d9 \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/posts/{id}/publishBearerNot for tenantsPublishes immediately through the exactly-once path. A replayed or concurrent call returns 409 not_claimable. A revoked channel leaves the post failed and returns 409 channel_revoked with the failed post embedded. A platform error returns 502 publish_failed.
idrequired | string | The post id (e.g. `pst_...`). |
curl -X POST https://api.socialkit.sh/v1/posts/id_8fa3c1d9/publish \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/posts/{id}/scoreBearerScores the stored post's text and persists the score against the post, building the score-vs-reality dataset. Distinct from POST /v1/score, which grades arbitrary text without saving.
idrequired | string | The post id (e.g. `pst_...`). |
curl -X POST https://api.socialkit.sh/v1/posts/id_8fa3c1d9/score \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/posts/{id}/scoresBeareridrequired | string | The post id (e.g. `pst_...`). |
curl https://api.socialkit.sh/v1/posts/id_8fa3c1d9/scores \
-H "Authorization: Bearer $SOCIALKIT_KEY"Bulk-schedule a week of posts and read the cross-channel calendar of scheduled and published content. Due posts are published by a per-minute cron through the same exactly-once path as publish-now.
/v1/posts/bulk-scheduleBearerNot for tenantsCreates a batch of posts and schedules each for its runAt time in a single call (the /plan week made concrete). Each item is validated independently; any bad reference fails the whole batch. Pass an Idempotency-Key header to make a retry of the whole batch safe.
Idempotency-Keyrequired | string | A client-chosen key (max 255 chars) that makes this call safe to retry. The first successful (2xx) response is cached per API key for 24 hours; replaying the same key returns that stored response verbatim with an `idempotent-replay: true` header and does no new work, so a retried model call (score, rewrite, generate, plan) charges no second credit and a retried creation creates nothing new. The request body is fingerprinted with the key: reusing a key with a different body returns `409 idempotency_key_reused` rather than the stale stored result, so a retry must be identical. Non-2xx responses are not cached, so a failed call leaves the key reusable. Best-effort: a sequential retry after a timeout is deduped, but two truly concurrent requests may both execute. |
curl -X POST https://api.socialkit.sh/v1/posts/bulk-schedule \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"text": "Day one shipping receipt.",
"channelId": "chn_example",
"runAt": 1893456000000
},
{
"text": "Day two contrarian take.",
"channelId": "chn_example",
"runAt": 1893542400000
}
]
}'/v1/posts/{id}/scheduleBearerNot for tenantsSets the post to scheduled for runAt and enqueues a single pending job. Re-scheduling cancels the prior pending job. The per-minute cron publishes due posts through the exactly-once path.
idrequired | string | The post id (e.g. `pst_...`). |
curl -X POST https://api.socialkit.sh/v1/posts/id_8fa3c1d9/schedule \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{
"runAt": 1893456000000
}'/v1/posts/{id}/cancelBearerNot for tenantsMoves the post to canceled and cancels its pending job. A post in a terminal state (published, failed) cannot be canceled and returns 409.
idrequired | string | The post id (e.g. `pst_...`). |
curl -X POST https://api.socialkit.sh/v1/posts/id_8fa3c1d9/cancel \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/calendarBearerNot for tenantsReturns scheduled and published posts within an optional time window, ordered chronologically. from/to are unix-ms timestamps.
fromrequired | integer | Start of the window, unix epoch milliseconds. |
torequired | integer | End of the window, unix epoch milliseconds. |
curl https://api.socialkit.sh/v1/calendar \
-H "Authorization: Bearer $SOCIALKIT_KEY"Signed event callbacks (post.published, post.failed, post.scored, channel.disconnected). The signing secret is returned once at creation. Deliveries are retried with backoff; inspect them per endpoint.
/v1/webhooksBearerReturns the account's endpoints (secrets never included) plus the set of events you can subscribe to.
curl https://api.socialkit.sh/v1/webhooks \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/webhooksBearerRegisters a signed callback URL. The signing secret is returned once in this response and never again; store it now. Omit events to subscribe to all of them.
curl -X POST https://api.socialkit.sh/v1/webhooks \
-H "Authorization: Bearer $SOCIALKIT_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/hooks/socialkit"
}'/v1/webhooks/{id}Beareridrequired | string | The webhook endpoint id (e.g. `whk_...`). |
curl https://api.socialkit.sh/v1/webhooks/id_8fa3c1d9 \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/webhooks/{id}Beareridrequired | string | The webhook endpoint id (e.g. `whk_...`). |
curl -X DELETE https://api.socialkit.sh/v1/webhooks/id_8fa3c1d9 \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/webhooks/{id}/deliveriesBearerReturns delivery attempts with status and retry state, newest-first. Results are paginated; page with limit and offset and follow pagination.hasMore.
idrequired | string | The webhook endpoint id (e.g. `whk_...`). |
limitrequired | integer | Maximum deliveries to return (default 50, max 100). |
offsetrequired | integer | Number of deliveries to skip from the newest. |
curl https://api.socialkit.sh/v1/webhooks/id_8fa3c1d9/deliveries \
-H "Authorization: Bearer $SOCIALKIT_KEY"Engagement for published posts. Each poll appends a time-series snapshot; a per-minute cron sweeps the least-recently-polled posts. Roll snapshots up into account analytics, and correlate predicted scores with measured engagement in the calibration dataset.
/v1/posts/{id}/metricsBearerNot for tenantsReturns the latest engagement snapshot plus the full time-series history (newest first) for a published post. Counters are null when the platform does not expose that dimension for the post type.
idrequired | string | The post id (e.g. `pst_...`). |
curl https://api.socialkit.sh/v1/posts/id_8fa3c1d9/metrics \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/posts/{id}/metrics/refreshBearerNot for tenantsPolls the platform for the post's current engagement and stores a new snapshot. Mirrors the per-minute cron sweep for a single post. A draft or unpublished post returns 409; a revoked channel returns 409.
idrequired | string | The post id (e.g. `pst_...`). |
curl -X POST https://api.socialkit.sh/v1/posts/id_8fa3c1d9/metrics/refresh \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/analyticsBearerNot for tenantsAggregates the latest snapshot of every published post into account totals and a per-platform breakdown. Optional from/to filter on the post's published time (unix-ms).
fromrequired | integer | Start of the window, unix epoch milliseconds. |
torequired | integer | End of the window, unix epoch milliseconds. |
curl https://api.socialkit.sh/v1/analytics \
-H "Authorization: Bearer $SOCIALKIT_KEY"/v1/calibrationBearerThe calibration dataset: each published post that has both a recorded score and a metric snapshot, pairing the predicted score with the measured engagement. Posts missing either are omitted.
curl https://api.socialkit.sh/v1/calibration \
-H "Authorization: Bearer $SOCIALKIT_KEY"PlatformenumTarget platform for scoring and preflight. `linkedin` and `x` are live; `instagram`, `tiktok`, and `facebook` are planned. Each platform has its own rubric, character cap, and media set (e.g. `document` is LinkedIn only); the server validates the post against the selected platform.
linkedinxMediaKindenumThe media attached to the post. Drives the format multiplier.
nonesingle-imagemulti-imagedocumentvideopolllinkFollowerBandenumAuthor follower bucket. Optional context for calibration.
under-500500-2k2k-10k10k-50k50k-plusDimensionenumA scored dimension of the post.
hookalgorithmFitspecificitystructurevoiceengagementHookArchetypeenumThe classified shape of the post's opening hook.
contrarianstatementquestionpure-numberstoryotherScoreRequestobject| Field | Type | Notes |
|---|---|---|
platform | Platform | |
postrequired | string | The full post text to grade. The hard cap shown here is the largest across platforms (X long-form). The server enforces the selected platform's own limit: 3000 for LinkedIn, 25000 for X. |
authorName | string | Optional author name for context. |
authorHeadline | string | Optional author headline/title for context. |
followerBand | FollowerBand | |
media | MediaKind | |
hasExternalLink | boolean | Whether the post body or its preview points off-platform. External links cap algorithm fit. Derived from the post text when omitted. |
hashtagCount | integer | Number of hashtags. Six or more caps algorithm fit. Derived from the post text when omitted. |
dayOfWeek | integer | Planned publish day, Sunday=0. Optional. |
hourLocal | integer | Planned publish hour in the author's local time. Optional. |
ValidatePostRequestobject| Field | Type | Notes |
|---|---|---|
postrequired | string | The full draft text to preflight. The hard cap shown here is the largest across platforms (X long-form). The server enforces the selected platform's own limit: 3000 for LinkedIn, 25000 for X. |
platform | Platform | |
media | MediaKind | |
hasExternalLink | boolean | Whether the post body links off-platform. Derived from the post text when omitted. |
hashtagCount | integer | Number of hashtags. Derived from the post text when omitted. |
ValidationIssueobjectOne structural error or reach/voice warning found in the draft.
| Field | Type | Notes |
|---|---|---|
severityrequired | string | Errors block a clean publish; warnings are reach/voice hazards.errorwarning |
coderequired | string | Stable machine code, e.g. empty, too_long, unsupported_platform, invalid_media, too_many_hashtags, external_link, engagement_bait, ai_tell, em_dash. |
fieldrequired | string | The request field the issue is about (post, platform, media). |
messagerequired | string | A specific, human-readable explanation of the issue. |
ValidatePostResultobject| Field | Type | Notes |
|---|---|---|
validrequired | boolean | True when there are no error-severity issues. |
issuesrequired | ValidationIssue[] | |
signalsrequired | object | The signals actually evaluated (supplied or derived). |
ScoreBreakdownobjectPer-dimension scores, each 0-100.
| Field | Type | Notes |
|---|---|---|
hookrequired | number | |
algorithmFitrequired | number | |
specificityrequired | number | |
structurerequired | number | |
voicerequired | number | |
engagementrequired | number |
SignalobjectOne ranked observation about the post.
| Field | Type | Notes |
|---|---|---|
dimensionrequired | Dimension | |
impactrequired | string | positivenegative |
weightrequired | integer | How much this signal moved the score (1-5). |
labelrequired | string | Short headline a human reads at a glance. |
detailrequired | string | One sentence on the specific move in the post. |
rule | string | The named algorithm rule this ties to, if any. |
ScoreResultobject| Field | Type | Notes |
|---|---|---|
schemarequired | string | Score schema version. |
platformrequired | Platform | |
overallrequired | number | Weighted overall score. |
breakdownrequired | ScoreBreakdown | |
verdictrequired | string | One-line plain-language verdict. |
signalsrequired | Signal[] | |
hookArchetyperequired | HookArchetype | |
hookArchetypeNoterequired | string | Benchmark note for the detected hook archetype. |
formatMultiplierrequired | number | Reach multiplier implied by the chosen media format. |
formatNoterequired | string | Why the format multiplier is what it is. |
RewriteChangeobjectOne edit the rewrite made, tied to a scored dimension.
| Field | Type | Notes |
|---|---|---|
dimensionrequired | Dimension | |
noterequired | string | One sentence on what changed and why. |
RewriteResultobjectThe rewrite plus the before/after scores. The after-score is reported as measured and is never massaged to look like an improvement.
| Field | Type | Notes |
|---|---|---|
rewriterequired | string | The rewritten post. |
changesrequired | RewriteChange[] | |
beforerequired | ScoreResult | |
afterrequired | ScoreResult |
GenerateRequestobject| Field | Type | Notes |
|---|---|---|
briefrequired | string | What the post should be about. |
platform | object | Target platform for the drafts. `linkedin` (default) writes for the LinkedIn feed ranker; `x` writes reply-optimized posts for the X ranker. Each platform uses its own writing rubric and media set. |
authorName | string | Optional author name for voice context. |
authorHeadline | string | Optional author headline/title for context. |
followerBand | FollowerBand | |
media | MediaKind | |
archetype | HookArchetype | |
count | integer | How many drafts to produce (1-3, default 1). |
brandId | string | Optional brand id whose context (business, audience, themes, link policy) conditions the drafts. Must belong to the calling account. |
voiceId | string | Optional voice id whose traits and exemplars the drafts imitate. Must belong to the calling account. |
GeneratedCandidateobject| Field | Type | Notes |
|---|---|---|
postrequired | string | The generated post text. |
scorerequired | ScoreResult |
GenerateResultobject| Field | Type | Notes |
|---|---|---|
candidatesrequired | GeneratedCandidate[] | Drafts sorted by overall score, best first. |
CadenceenumPosting rhythm hint for the calendar.
dailyweekdays3x-weekPlanRequestobject| Field | Type | Notes |
|---|---|---|
briefrequired | string | Themes, goals, or topics the calendar should cover. |
platform | object | Target platform for the calendar. `linkedin` (default) or `x`. Each platform uses its own content pillars and media set. |
count | integer | Number of calendar slots (1-14, default 5). |
authorName | string | Optional author name for context. |
authorHeadline | string | Optional author headline/title for context. |
followerBand | FollowerBand | |
cadence | Cadence | |
brandId | string | Optional brand id whose context conditions the plan. Must belong to the calling account. |
voiceId | string | Optional voice id whose style conditions the plan. Must belong to the calling account. |
PlanItemobject| Field | Type | Notes |
|---|---|---|
slotrequired | integer | 1-based ordinal in the plan. |
pillarrequired | string | The content pillar this idea serves. |
hookrequired | string | The opening line to write. |
anglerequired | string | One sentence on the take or argument. |
formatrequired | MediaKind | |
archetyperequired | HookArchetype |
PlanResultobject| Field | Type | Notes |
|---|---|---|
platformrequired | Platform | |
itemsrequired | PlanItem[] |
Accountobject| Field | Type | Notes |
|---|---|---|
idrequired | string | Account id (e.g. `acc_...`). |
emailrequired | string | |
planrequired | string | Billing plan. New accounts start on `free`. |
name | string | null | Display name, or null if unset. |
avatarUrl | string | null | Avatar URL, or null if unset. |
createdAt | integer | Creation time, epoch milliseconds. |
ApiKeyobjectAPI key metadata. The secret is never included.
| Field | Type | Notes |
|---|---|---|
idrequired | string | Key id (e.g. `key_...`). |
namerequired | string | Human-readable label for the key. |
keyPrefixrequired | string | The first characters of the secret, for display. |
createdAtrequired | integer | Creation time, epoch milliseconds. |
lastUsedAtrequired | integer | null | Last successful auth, epoch milliseconds, or null. |
revokedAtrequired | integer | null | Revocation time, epoch milliseconds, or null if live. |
toolProfile | string | null | The MCP catalog this key presents on tools/list (tenant keys only): `core` for the curated generate, score, rewrite, plan, brands, voices and account set, null for every tool. Presentation only; what the key may call does not change. |
CreateAccountRequestobject| Field | Type | Notes |
|---|---|---|
emailrequired | string | |
name | string | Optional label for the first key. Defaults to `default`. |
CreateAccountResultobject| Field | Type | Notes |
|---|---|---|
accountrequired | Account | |
keyrequired | ApiKey | |
apiKeyrequired | string | The plaintext key, shown exactly once. Store it now; it cannot be retrieved again. |
WhoamiResultobject| Field | Type | Notes |
|---|---|---|
accountrequired | Account | |
keyrequired | ApiKey | |
capabilitiesrequired | Capabilities | |
creditsrequired | CreditStanding | |
tenant | TenantIdentity |
CreditStandingobjectThe live monthly credit standing. `scope` appears for partner tenants only and names the ceiling that bounds `remaining`: the tenant's own monthly cap or the partner-wide cap.
| Field | Type | Notes |
|---|---|---|
usedrequired | integer | |
includedrequired | integer | |
remainingrequired | integer | |
overagerequired | boolean | Whether the plan flows into billed overage past `included`. |
periodrequired | string | The `YYYY-MM` window. |
resetAtrequired | integer | Unix seconds when the allotment resets. |
scope | string | tenantpartner |
TenantIdentityobjectPresent when the calling key belongs to a partner tenant.
| Field | Type | Notes |
|---|---|---|
externalIdrequired | string | |
partnerrequired | object |
Partnerobject| Field | Type | Notes |
|---|---|---|
idrequired | string | Partner id (e.g. `par_...`). |
slugrequired | string | |
namerequired | string | |
statusrequired | string | activesuspended |
capsrequired | PartnerCaps | |
creditWeightsrequired | object | Credits a tenant is charged per operation (`score`, `rewrite`, `generate`, `plan`, `buildVoice`, `visual`, `carousel`). An operation absent here costs 1. |
createdAtrequired | integer | |
updatedAtrequired | integer |
PartnerCapsobject| Field | Type | Notes |
|---|---|---|
monthlyCreditCaprequired | integer | null | Partner-wide credits per month; null means no cap. |
tenantMonthlyCreditCaprequired | integer | null | Credits per tenant per month; null means no cap. |
maxTenantsrequired | integer | |
rateLimitPerHourrequired | integer | Requests per hour across the partner and all its tenants. |
llmRateLimitPerMinuterequired | integer | Model-backed calls per minute across all tenants. |
PartnerKeyobjectPartner key metadata. The secret is never included.
| Field | Type | Notes |
|---|---|---|
idrequired | string | |
namerequired | string | |
keyPrefixrequired | string | |
createdAtrequired | integer | |
lastUsedAtrequired | integer | null | |
expiresAtrequired | integer | null | Set on a key superseded by a rotation; it stops working then. |
revokedAtrequired | integer | null |
PartnerProfileResultobject| Field | Type | Notes |
|---|---|---|
partnerrequired | Partner | |
keyrequired | PartnerKey | |
tenantsrequired | integer | Live tenants. |
creditsrequired | object |
RotatePartnerKeyResultobject| Field | Type | Notes |
|---|---|---|
keyrequired | PartnerKey | |
apiKeyrequired | string | The plaintext partner key, shown exactly once. |
previousKeysGraceSecondsrequired | integer | How long the other live keys keep working (0 when `immediate`). |
Tenantobject| Field | Type | Notes |
|---|---|---|
externalIdrequired | string | |
accountIdrequired | string | The SocialKit account id behind the tenant (e.g. `acc_...`). |
namerequired | string | null | |
planrequired | string | Always `tenant`. |
statusrequired | string | activedeleting |
createdAtrequired | integer | |
deletedAtrequired | integer | null |
EnsureTenantRequestobject| Field | Type | Notes |
|---|---|---|
name | string | Display name for the tenant. |
brand | BrandCreateRequest |
TenantDetailResultobject| Field | Type | Notes |
|---|---|---|
tenantrequired | Tenant | |
creditsrequired | CreditStanding | |
countsrequired | object |
TenantListResultobject| Field | Type | Notes |
|---|---|---|
tenantsrequired | Tenant[] | |
nextCursorrequired | string | null |
UsageTotalsobject| Field | Type | Notes |
|---|---|---|
callsrequired | integer | Successful model calls. |
creditsrequired | integer | Credits charged (calls times the partner's weight). |
AuditEventobject| Field | Type | Notes |
|---|---|---|
idrequired | string | Event id (e.g. `aud_...`), stable across pages. |
atrequired | integer | When, epoch milliseconds. |
actionrequired | string | tenant.createdtenant.brand_updatedtenant.deletedtenant_key.createdtenant_key.revokedtenant_key.rotatedpartner_key.createdpartner_key.rotatedpartner_key.revokedpartner.updatedpartner.suspendedpartner.reinstatedoperator.grantedoperator.revoked |
actorKindrequired | string | Who made the change: a partner key, a tenant's own key (or the partner key acting as the tenant), SocialKit ops, a console operator, or the system.partner-keytenant-keyinternaloperatorsystem |
actorIdrequired | string | null | The acting key id or operator email, when known. |
targetrequired | string | null | The tenant's external id, a key id, or an operator email. |
detailsrequired | object | null | A small object with the specifics (key ids, the fields changed); never a secret. |
requestIdrequired | string | null |
AuditListResultobject| Field | Type | Notes |
|---|---|---|
eventsrequired | AuditEvent[] | |
nextCursorrequired | string | null | Pass as `cursor` for the next (older) page; null on the last. |
PartnerUsageobject| Field | Type | Notes |
|---|---|---|
periodrequired | string | |
callsrequired | integer | |
creditsrequired | integer | |
byOperationrequired | object | |
tenantsrequired | object[] |
PartnerUsageResultobject| Field | Type | Notes |
|---|---|---|
usagerequired | PartnerUsage |
TenantUsageobject| Field | Type | Notes |
|---|---|---|
periodrequired | string | |
callsrequired | integer | |
creditsrequired | integer | |
byOperationrequired | object | |
byActorrequired | object[] |
TenantUsageResultobject| Field | Type | Notes |
|---|---|---|
tenantrequired | Tenant | |
usagerequired | TenantUsage |
CapabilitiesobjectWhat this deployment can do, derived from which secrets are set. Branch on these before attempting an action instead of learning a capability is off only from an error. All three gate on the same vault + LinkedIn app creds today but are named separately so the contract is stable if the gating diverges.
| Field | Type | Notes |
|---|---|---|
publishrequired | boolean | Whether stored drafts can be published to a channel. |
metricsrequired | boolean | Whether published-post engagement metrics can be polled. |
connectChannelsrequired | boolean | Whether new social channels can be connected via OAuth. |
HealthResultobjectThe readiness report returned by GET /v1/health. `status` is `ok` only when every dependency check is `ok`; otherwise it is `degraded` and the response status is 503.
| Field | Type | Notes |
|---|---|---|
statusrequired | string | Overall readiness; `degraded` if any check failed.okdegraded |
checksrequired | object | |
versionrequired | string | The shipped product version (e.g. `0.10`). |
latencyMsrequired | integer | Wall-clock milliseconds spent running the dependency checks. |
timerequired | string | Server time when the probe ran (ISO 8601). |
ServiceMetaobjectThe self-describing service contract returned by GET /v1/meta. The enum lists (platforms, mediaKinds, followerBands) are the exact accepted values for a score request; dimensions carries the rubric weights; billing carries the credit cost model so an agent can budget keylessly.
| Field | Type | Notes |
|---|---|---|
scoreVersionrequired | string | The scoring schema version (e.g. `v0.3`). |
maxPostCharsrequired | integer | Maximum post length accepted by the scorer. |
platformsrequired | object[] | Supported platforms; `enabled` is false for not-yet-live ones. |
mediaKindsrequired | object[] | Accepted `media` values for a score request. |
followerBandsrequired | object[] | Accepted `followerBand` values. |
dimensionsrequired | object[] | The six scoring dimensions and their weights (sum to 100). |
capabilitiesrequired | Capabilities | |
billingrequired | CreditModel |
CreditModelobjectThe cost contract, so an agent can budget before spending. A credit is one successful model-backed call; reads, the post lifecycle, CRUD, and preflight validate are free.
| Field | Type | Notes |
|---|---|---|
unitrequired | string | The metering unit. Always `credit`. |
creditPerCallrequired | integer | Credits charged per billable call. Currently 1. |
chargedOnSuccessOnlyrequired | boolean | When true, a credit is charged only after the model call succeeds, so a rate limit, quota stop, or upstream error never costs one. |
billableOperationsrequired | string[] | The operations that cost a credit, by capability name (`score`, `rewrite`, `generate`, `plan`, `buildVoice`). Every other route is free. |
plansrequired | object[] | The plan ladder with each tier's monthly credit allowance. |
CreateKeyRequestobject| Field | Type | Notes |
|---|---|---|
name | string | Optional label for the key. Defaults to `default`. |
toolProfile | string | null | Tenant keys only. `core` makes the key's MCP tools/list the curated set (generate, score, rewrite, plan, brands, voices, get_account, sign_media_url); tools/call is unaffected. A self-serve key answers 400 when this is set. |
SignMediaUrlRequestobject| Field | Type | Notes |
|---|---|---|
ttlSeconds | integer | Seconds until the URL expires. Default 3600; clamped to the range. |
SignedMediaUrlResultobject| Field | Type | Notes |
|---|---|---|
mediaIdrequired | string | |
urlrequired | string | `https://api.socialkit.sh/v1/media/{id}/content?token=...`, usable with no key until `expiresAt`. |
expiresAtrequired | integer | Expiry, epoch milliseconds. |
CreateKeyResultobject| Field | Type | Notes |
|---|---|---|
keyrequired | ApiKey | |
apiKeyrequired | string | The plaintext key, shown exactly once. |
KeyListResultobject| Field | Type | Notes |
|---|---|---|
keysrequired | ApiKey[] |
RevokeResultobject| Field | Type | Notes |
|---|---|---|
revokedrequired | boolean | True when the key was revoked. |
BrandKitobjectA brand's persisted visual system. A v2 visual request that names the brand (`brandId`) is grounded from it: the palette and fonts become the engine's brand kit, the logo is placed, the photos lead. Media ids must be images uploaded to the same account (`POST /v1/media`).
| Field | Type | Notes |
|---|---|---|
palette | object | Hex colors, `#RRGGBB`. |
fonts | object | Google Fonts family names. Requires a palette. |
logo | object | |
photoMediaIds | string[] | Images on this account the engine may lead with. |
imageryStyle | string | Free-text imagery direction ("warm natural light, no stock"). |
BrandobjectWorkspace context that conditions generation.
| Field | Type | Notes |
|---|---|---|
idrequired | string | Brand id (e.g. `brd_...`). |
namerequired | string | |
descriptionrequired | string | null | Who the business is. |
audiencerequired | string | null | Who the brand talks to. |
themesrequired | string[] | Recurring themes the brand posts about. |
linkPolicyrequired | string | null | Free-text policy on outbound links. |
kitrequired | object | The persisted visual system, or null. |
createdAtrequired | integer | Creation time, epoch milliseconds. |
updatedAtrequired | integer | Last update time, epoch milliseconds. |
BrandCreateRequestobject| Field | Type | Notes |
|---|---|---|
namerequired | string | |
description | string | null | |
audience | string | null | |
themes | string[] | |
linkPolicy | string | null | |
kit | object |
BrandUpdateRequestobjectPartial update; omit a field to leave it unchanged.
| Field | Type | Notes |
|---|---|---|
name | string | |
description | string | null | |
audience | string | null | |
themes | string[] | |
linkPolicy | string | null | |
kit | object | Replace the kit wholesale, or null to clear it. |
BrandResultobject| Field | Type | Notes |
|---|---|---|
brandrequired | Brand |
BrandListResultobject| Field | Type | Notes |
|---|---|---|
brandsrequired | Brand[] |
VoiceobjectA reusable writing profile distilled from sample posts.
| Field | Type | Notes |
|---|---|---|
idrequired | string | Voice id (e.g. `voi_...`). |
brandIdrequired | string | null | The brand this voice belongs to, or null. |
namerequired | string | |
traitsrequired | string[] | Stylistic traits to imitate. |
doNotrequired | string[] | Things this voice never does. |
exemplarsrequired | string[] | Few-shot snippets that anchor the voice. |
createdAtrequired | integer | Creation time, epoch milliseconds. |
updatedAtrequired | integer | Last update time, epoch milliseconds. |
VoiceCreateRequestobject| Field | Type | Notes |
|---|---|---|
namerequired | string | |
brandId | string | Optional brand to attach the voice to. |
samples | string[] | 1-12 sample posts in the target voice. When present, the profile is distilled from them and any traits/doNot/exemplars you also pass are ignored. |
traits | string[] | |
doNot | string[] | |
exemplars | string[] |
VoiceUpdateRequestobjectPartial update; omit a field to leave it unchanged.
| Field | Type | Notes |
|---|---|---|
name | string | |
brandId | string | null | Reattach to a brand, or null to detach. |
traits | string[] | |
doNot | string[] | |
exemplars | string[] |
BuildVoiceRequestobject| Field | Type | Notes |
|---|---|---|
namerequired | string | |
brandId | string | Optional brand to attach the built voice to. |
samplesrequired | string[] | 1-12 sample posts written in the target voice. |
VoiceResultobject| Field | Type | Notes |
|---|---|---|
voicerequired | Voice |
VoiceListResultobject| Field | Type | Notes |
|---|---|---|
voicesrequired | Voice[] |
DeleteResultobject| Field | Type | Notes |
|---|---|---|
deletedrequired | boolean | True when the resource was deleted. |
ChannelStatusenumConnection health of the channel.
connectedexpiredrevokederrorChannelobjectA connected social account. Carries no token material.
| Field | Type | Notes |
|---|---|---|
idrequired | string | Channel id (e.g. `chn_...`). |
accountIdrequired | string | The owning account id. |
brandIdrequired | string | null | The brand this channel belongs to, or null. |
platformrequired | string | The platform, e.g. `linkedin`. |
platformUserIdrequired | string | null | The platform's stable user id for the connected member. |
handlerequired | string | null | A display handle or name for the connected account. |
statusrequired | ChannelStatus | |
scopesrequired | string[] | Granted OAuth scopes. |
expiresAtrequired | integer | null | Access token expiry, epoch milliseconds, or null. |
lastRefreshAtrequired | integer | null | Last token refresh, epoch milliseconds, or null. |
createdAtrequired | integer | Creation time, epoch milliseconds. |
updatedAtrequired | integer | Last update time, epoch milliseconds. |
ChannelResultobject| Field | Type | Notes |
|---|---|---|
channelrequired | Channel |
ChannelListResultobject| Field | Type | Notes |
|---|---|---|
channelsrequired | Channel[] |
ConnectChannelRequestobject| Field | Type | Notes |
|---|---|---|
brandId | string | Optional brand to scope the channel to. Must belong to the calling account. |
ConnectChannelResultobject| Field | Type | Notes |
|---|---|---|
urlrequired | string | The platform authorization URL to redirect the member to. |
staterequired | string | The opaque, single-use state token tying the callback to this account. Returned for visibility; the callback validates it. |
MediaobjectMetadata for an uploaded file. The storage key is never returned.
| Field | Type | Notes |
|---|---|---|
idrequired | string | Media id (e.g. `med_...`). |
accountIdrequired | string | The owning account id. |
brandIdrequired | string | null | The brand this media belongs to, or null. |
contentTyperequired | string | The validated MIME type of the stored bytes. |
sizerequired | integer | Size in bytes. |
filenamerequired | string | null | The original filename (basename), or null. |
sha256required | string | SHA-256 of the bytes, hex-encoded. |
createdAtrequired | integer | Upload time, epoch milliseconds. |
MediaResultobject| Field | Type | Notes |
|---|---|---|
mediarequired | Media |
MediaListResultobject| Field | Type | Notes |
|---|---|---|
mediarequired | Media[] | |
paginationrequired | object |
PostStatusenumWhere the post sits in its lifecycle.
draftscheduledpublishingpublishedfailedcanceledPostobjectA unit of content. Carries no token material.
| Field | Type | Notes |
|---|---|---|
idrequired | string | Post id (e.g. `pst_...`). |
accountIdrequired | string | The owning account id. |
brandIdrequired | string | null | The brand this post belongs to, or null. |
channelIdrequired | string | null | The channel this post publishes to, or null. |
platformrequired | string | The target platform, e.g. `linkedin`. |
statusrequired | PostStatus | |
textrequired | string | The post body. |
mediaIdsrequired | string[] | Ids of media attached to the post. |
scheduledForrequired | integer | null | Scheduled publish time, epoch milliseconds, or null. |
publishedAtrequired | integer | null | Actual publish time, epoch milliseconds, or null. |
platformPostIdrequired | string | null | The platform's id for the published post, or null. |
platformUrlrequired | string | null | Public URL of the published post, or null. |
errorrequired | string | null | The last publish error, or null. |
createdAtrequired | integer | Creation time, epoch milliseconds. |
updatedAtrequired | integer | Last update time, epoch milliseconds. |
PostResultobject| Field | Type | Notes |
|---|---|---|
postrequired | Post |
PostListResultobject| Field | Type | Notes |
|---|---|---|
postsrequired | Post[] | |
paginationrequired | object |
PostErrorResultobjectAn error with the affected post's terminal state embedded.
| Field | Type | Notes |
|---|---|---|
errorrequired | object | |
postrequired | Post |
CreatePostRequestobject| Field | Type | Notes |
|---|---|---|
textrequired | string | The post body. |
channelId | string | null | Channel to publish to. Must belong to the account. |
brandId | string | null | Brand to attach. Must belong to the account. |
platform | string | Target platform. Defaults from the channel, else linkedin. |
mediaIds | string[] | |
runAt | integer | Optional. Epoch milliseconds at which to publish. When set, the post is created and scheduled in one call and comes back in the `scheduled` state (instead of `draft`). Omit to create a plain draft. |
UpdatePostRequestobjectPartial update; omit a field to leave it unchanged. Draft only.
| Field | Type | Notes |
|---|---|---|
text | string | |
channelId | string | null | |
brandId | string | null | |
mediaIds | string[] |
SchedulePostRequestobject| Field | Type | Notes |
|---|---|---|
runAtrequired | integer | When to publish, epoch milliseconds. Must be in the future. |
BulkScheduleItemobject| Field | Type | Notes |
|---|---|---|
textrequired | string | |
runAtrequired | integer | When to publish this post, epoch milliseconds. |
channelId | string | null | |
brandId | string | null | |
platform | string | |
mediaIds | string[] |
BulkScheduleRequestobject| Field | Type | Notes |
|---|---|---|
itemsrequired | BulkScheduleItem[] |
PostScoreobjectA score recorded against a stored post.
| Field | Type | Notes |
|---|---|---|
idrequired | string | Score id (e.g. `psc_...`). |
postIdrequired | string | |
scorerequired | integer | The overall score, rounded. |
verdictrequired | string | null | One-line plain-language verdict, or null. |
payloadrequired | object | The full ScoreResult captured at scoring time. |
createdAtrequired | integer | When the score was recorded, epoch milliseconds. |
StoredScoreResultobject| Field | Type | Notes |
|---|---|---|
scorerequired | PostScore | |
resultrequired | ScoreResult |
PostScoreListResultobject| Field | Type | Notes |
|---|---|---|
scoresrequired | PostScore[] |
CalendarEntryobject| Field | Type | Notes |
|---|---|---|
postIdrequired | string | |
statusrequired | PostStatus | |
whenrequired | integer | Scheduled or published time, epoch milliseconds. |
channelIdrequired | string | null | |
platformrequired | string | |
previewrequired | string | A short preview of the post text. |
CalendarResultobject| Field | Type | Notes |
|---|---|---|
calendarrequired | CalendarEntry[] |
MetricSnapshotobjectOne engagement snapshot for a post. Each counter is null when the platform did not report that dimension (distinct from a reported zero).
| Field | Type | Notes |
|---|---|---|
idrequired | string | Snapshot id (e.g. `met_...`). |
postIdrequired | string | |
impressionsrequired | integer | null | |
likesrequired | integer | null | |
commentsrequired | integer | null | |
sharesrequired | integer | null | |
clicksrequired | integer | null | |
fetchedAtrequired | integer | When this snapshot was captured, epoch milliseconds. |
PostMetricsResultobject| Field | Type | Notes |
|---|---|---|
latestrequired | object | The most recent snapshot, or null if never polled. |
historyrequired | MetricSnapshot[] | All snapshots, newest first. |
MetricRefreshResultobject| Field | Type | Notes |
|---|---|---|
snapshotrequired | MetricSnapshot |
MetricTotalsobject| Field | Type | Notes |
|---|---|---|
postsrequired | integer | Posts counted (those with at least one snapshot). |
impressionsrequired | integer | |
likesrequired | integer | |
commentsrequired | integer | |
sharesrequired | integer | |
clicksrequired | integer | |
engagementsrequired | integer | likes + comments + shares + clicks. |
PlatformTotalsobject| Field | Type | Notes |
|---|
Analyticsobject| Field | Type | Notes |
|---|
AnalyticsResultobject| Field | Type | Notes |
|---|---|---|
analyticsrequired | Analytics |
CalibrationRowobjectA published post paired with its predicted score and measured engagement. Only posts that have both appear.
| Field | Type | Notes |
|---|---|---|
postIdrequired | string | |
platformrequired | string | |
scorerequired | integer | The latest recorded score. |
verdictrequired | string | null | |
publishedAtrequired | integer | null | When the post was published, epoch milliseconds. |
impressionsrequired | integer | null | |
likesrequired | integer | null | |
commentsrequired | integer | null | |
sharesrequired | integer | null | |
clicksrequired | integer | null | |
engagementsrequired | integer | likes + comments + shares + clicks (nulls counted as 0). |
CalibrationResultobject| Field | Type | Notes |
|---|---|---|
calibrationrequired | CalibrationRow[] |
WebhookEventenumAn event you can subscribe a webhook to.
post.publishedpost.failedpost.scoredchannel.disconnectedWebhookEndpointobjectA signed callback endpoint. The secret is never included here.
| Field | Type | Notes |
|---|---|---|
idrequired | string | Webhook id (e.g. `whk_...`). |
accountIdrequired | string | |
urlrequired | string | The callback URL. |
eventsrequired | WebhookEvent[] | |
statusrequired | string | activedisabled |
createdAtrequired | integer | Creation time, epoch milliseconds. |
updatedAtrequired | integer | Last update time, epoch milliseconds. |
CreateWebhookRequestobject| Field | Type | Notes |
|---|---|---|
urlrequired | string | The HTTPS callback URL to deliver events to. |
events | WebhookEvent[] | Events to subscribe to. Omit to subscribe to all. |
CreateWebhookResultobject| Field | Type | Notes |
|---|---|---|
webhookrequired | WebhookEndpoint | |
secretrequired | string | The signing secret, returned once (it cannot be retrieved again). Every delivery carries an x-socialkit-timestamp header (epoch seconds) and an x-socialkit-signature header of the form `sha256=<hex>`. To verify: reject the request if the timestamp is not recent (e.g. older than five minutes, which blocks replays), then compute HMAC-SHA256 over the string `<timestamp>.<raw body>` with this secret and compare it, in constant time, to the hex in the signature header. |
WebhookResultobject| Field | Type | Notes |
|---|---|---|
webhookrequired | WebhookEndpoint |
WebhookListResultobject| Field | Type | Notes |
|---|---|---|
webhooksrequired | WebhookEndpoint[] | |
eventsrequired | WebhookEvent[] | The full set of subscribable events. |
WebhookDeliveryobject| Field | Type | Notes |
|---|---|---|
idrequired | string | |
webhookIdrequired | string | |
eventrequired | string | |
statusrequired | string | pendingsendingdeliveredfaileddead |
attemptsrequired | integer | Number of delivery attempts so far. |
lastStatusCoderequired | integer | null | HTTP status of the last attempt, or null. |
lastErrorrequired | string | null | Error from the last attempt, or null. |
nextAttemptAtrequired | integer | null | When the next retry is due, epoch milliseconds, or null. |
createdAtrequired | integer | |
updatedAtrequired | integer |
DeliveryListResultobject| Field | Type | Notes |
|---|---|---|
deliveriesrequired | WebhookDelivery[] | |
paginationrequired | object |
Errorobject| Field | Type | Notes |
|---|---|---|
errorrequired | object |
VisualPlatformenumPlatforms the visual engine renders for.
instagramlinkedinfacebookxtiktokpinterestyoutube_shortsVisualAspectRatioenumMaster aspect ratios the renderer produces.
4:59:161:12:3VisualBusinessContextobjectWho the post is for. `businessName` is the only required field, but everything you add grounds the result: industry and description steer the idea, the brand kit locks palette and fonts, the proof bank feeds specific claims, and real photos always lead over generated imagery. Generated imagery stays name-free and atmospheric; the engine never fakes your storefront, staff, or logo.
| Field | Type | Notes |
|---|---|---|
businessNamerequired | string | |
industry | string | Short label like "specialty coffee roaster". |
description | string | A sentence or two on what the business actually does. |
brandKit | object | Palette and fonts the renderer must honor. |
proofBank | object[] | Concrete, reusable claims (numbers, facts, quotes) the copy may draw on. The engine will not invent proof it does not have. |
realPhotoUrls | string[] | Real brand photos by URL. Real photos lead the design. |
realPhotoDataUris | string[] | Real brand photos inlined as data URIs. |
logoDataUri | string | Brand logo as a data URI. |
VisualSeedobject| Field | Type | Notes |
|---|---|---|
platformrequired | VisualPlatform | |
idea | string | The idea to post about, in plain words. |
goal | string | What the post should be optimized to earn.awarenesssavelead |
format | string | Pin a static post TYPE. `proof-shot` is the testimonial post: the customer's real message or review, cropped out of the owner's screenshot with the pixels untouched, on the brand's field under five stars, plus a caption. Send 1 to 3 screenshots in `businessContext.realPhotoDataUris` with `pinnedPhotos: true`; the engine declines (422, stage `proof`) when they hold no happy customer message.proof-shot |
GenerateVisualRequestobject| Field | Type | Notes |
|---|---|---|
brandId | string | Ground the request from a saved brand instead of (or under) an inline businessContext: the brand's name, description, audience and themes, and its kit (palette, fonts, logo, photos) become the businessContext, and any businessContext fields sent alongside win over the brand. One of `brandId` or `businessContext.businessName` is required. |
businessContext | VisualBusinessContext | |
seedrequired | VisualSeed | |
aspectRatios | VisualAspectRatio[] | Which masters to render. Defaults to the engine's set. |
layout | string | Pin a text placement variant instead of letting the engine rotate.bottom-rulebottom-paneltop-rulecentercenter-panel |
preferFormat | string | Nudge the format choice; the engine may still refuse a format the content cannot carry.stat-cardquote-cardtip-cardannouncementphoto-hook |
pinnedPhotos | boolean | Treat the context's real photos as user-chosen for this post; the engine will never swap them for a generated scene. |
ReviseVisualRequestobject| Field | Type | Notes |
|---|---|---|
brandId | string | Ground the request from a saved brand instead of (or under) an inline businessContext: the brand's name, description, audience and themes, and its kit (palette, fonts, logo, photos) become the businessContext, and any businessContext fields sent alongside win over the brand. One of `brandId` or `businessContext.businessName` is required. |
businessContext | VisualBusinessContext | |
feedbackrequired | string | Freeform comment on the post ("shorter headline"). |
specrequired | object | The `spec` returned by a prior generate or revise. |
aspectRatios | VisualAspectRatio[] |
RenderedMasterobject| Field | Type | Notes |
|---|---|---|
aspectRatiorequired | VisualAspectRatio | |
imageUrlrequired | string | The rendered master, hosted on our object storage. |
mimeTyperequired | string | |
widthrequired | integer | |
heightrequired | integer |
VisualScoreobjectThe judge's verdict on the finished post. `score` is 0-100 and harsh by design; `verdict` is the judge's call after the revise loop settled; `singleFix` names the highest-leverage remaining change.
| Field | Type | Notes |
|---|---|---|
verdict | string | |
score | number | |
singleFix | string |
GeneratedVisualPostobject| Field | Type | Notes |
|---|---|---|
idrequired | string | |
engineId | string | |
formatId | string | The format the engine chose (e.g. photo-hook). |
mastersrequired | RenderedMaster[] | |
captionrequired | string | Platform-native caption; the long tail lives here. |
onImageText | string | The text rendered onto the image. |
hashtagsrequired | string[] | |
altText | string | |
scorerequired | VisualScore | |
specrequired | object | The post's revisable recipe. Treat it as opaque and hand it back to /v1/revise-visual-v2 with feedback; it records every decision (layout archetype, typography, colors, imagery) and the revision history. |
composition | object | The editable layered document seeded from the primary master's render spec, for callers building an editor on top. |
CarouselSeedobject| Field | Type | Notes |
|---|---|---|
platformrequired | VisualPlatform | |
idea | string | |
goal | string | awarenesssavelead |
slideCount | integer | Desired deck length; the planner may adjust. |
arc | string | Pin the deck's arc (a post type). `qa` is the "Ask us anything" deck: one real pre-purchase question and the owner's answer per slide, rendered in the native question-sticker treatment over a dimmed business photo. `product-reveal` is the four-slide reveal: one real product photo (the context's first real photo) under a torn-paper window that opens wider on every swipe, with the peek, the tease, the reveal and the invitation as its copy; it needs a real photo in the business context and is declined (422, stage `photo`) without one. Optional; the planner chooses otherwise.paslisticlehow-tobefore-aftermyth-buststoryqaproduct-reveal |
GenerateCarouselRequestobject| Field | Type | Notes |
|---|---|---|
brandId | string | Ground the request from a saved brand instead of (or under) an inline businessContext: the brand's name, description, audience and themes, and its kit (palette, fonts, logo, photos) become the businessContext, and any businessContext fields sent alongside win over the brand. One of `brandId` or `businessContext.businessName` is required. |
businessContext | VisualBusinessContext | |
seedrequired | CarouselSeed | |
aspectRatio | VisualAspectRatio | |
generatedImagery | boolean | Whether name-free generated atmosphere may back slides that have no real photo. Real photos always lead regardless. |
pinnedPhotos | boolean | Rank the context's real photos for order but never drop them from the deck. |
ReviseCarouselRequestobject| Field | Type | Notes |
|---|---|---|
brandId | string | Ground the request from a saved brand instead of (or under) an inline businessContext: the brand's name, description, audience and themes, and its kit (palette, fonts, logo, photos) become the businessContext, and any businessContext fields sent alongside win over the brand. One of `brandId` or `businessContext.businessName` is required. |
businessContext | VisualBusinessContext | |
feedbackrequired | string | |
specrequired | object | The `spec` returned by a prior carousel generate. |
CarouselSlideobject| Field | Type | Notes |
|---|---|---|
indexrequired | integer | 0-based swipe order. |
rolerequired | string | The slide's job in the arc (hook, rehook, body, cta). |
formatId | string | |
onImageTextrequired | string | |
masterrequired | RenderedMaster |
GeneratedCarouselobject| Field | Type | Notes |
|---|---|---|
idrequired | string | |
engineId | string | |
platformrequired | VisualPlatform | |
arc | string | The deck's narrative arc (e.g. how-to, myths). |
aspectRatio | VisualAspectRatio | |
slidesrequired | CarouselSlide[] | |
captionrequired | string | |
hashtagsrequired | string[] | |
cta | string | |
scorerequired | VisualScore | |
specrequired | object | The deck's revisable recipe for /v1/revise-carousel-v2. Opaque; hand it back with feedback. |
composition | object | Editable per-slide layered documents, for editors. |
SocialKit is a thin layer. If you want a new endpoint, a new surface, or a model swap, tell us. We ship weekly.