Docs — SocialKit

API reference

52 endpoints

Intelligence

Score, rewrite, plan, generate. The knowledge primitives.

POST/v1/scoreBearer

Grades 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 is the only platform live today.

Request body ScoreRequest

Example request

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."
}'

Responses

200Score computedScoreResult
400Invalid request bodyError
401Missing or invalid API keyError
429Rate limit exceededError

POST/v1/rewriteBearer

Scores 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.

Request body ScoreRequest

Example request

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."
}'

Responses

200Rewrite producedRewriteResult
400Invalid request bodyError
401Missing or invalid API keyError
429Rate limit exceeded. Two budgets apply per key: an overall request budget (headers `x-ratelimit-limit` / `-remaining` / `-reset`) and a separate, tighter budget for the model-backed endpoints (score, rewrite, generate, plan, and voice distillation), reported on those endpoints as `x-ratelimit-llm-limit` / `-remaining` / `-reset`. Either budget can trigger this response.Error
502The model or gateway misbehaved; safe to retryError

POST/v1/generateBearer

Drafts up to three native LinkedIn posts from a brief, scores each, and returns them sorted by overall score (best first).

Request body GenerateRequest

Example request

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
}'

Responses

200Candidates generatedGenerateResult
400Invalid request bodyError
401Missing or invalid API keyError
429Rate limit exceeded. Two budgets apply per key: an overall request budget (headers `x-ratelimit-limit` / `-remaining` / `-reset`) and a separate, tighter budget for the model-backed endpoints (score, rewrite, generate, plan, and voice distillation), reported on those endpoints as `x-ratelimit-llm-limit` / `-remaining` / `-reset`. Either budget can trigger this response.Error
502The model or gateway misbehaved; safe to retryError

POST/v1/planBearer

Returns 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.

Request body PlanRequest

Example request

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"
}'

Responses

200Plan producedPlanResult
400Invalid request bodyError
401Missing or invalid API keyError
429Rate limit exceeded. Two budgets apply per key: an overall request budget (headers `x-ratelimit-limit` / `-remaining` / `-reset`) and a separate, tighter budget for the model-backed endpoints (score, rewrite, generate, plan, and voice distillation), reported on those endpoints as `x-ratelimit-llm-limit` / `-remaining` / `-reset`. Either budget can trigger this response.Error
502The model or gateway misbehaved; safe to retryError

Account

POST/v1/accountPublic

Public 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.

Request body CreateAccountRequest

Example request

curl -X POST https://api.socialkit.sh/v1/account \
  -H "Content-Type: application/json" \
  -d '{
  "email": "string"
}'

Responses

201Account createdCreateAccountResult
400Invalid request bodyError
409An account already exists for that emailError
429Rate limit exceeded. Two budgets apply per key: an overall request budget (headers `x-ratelimit-limit` / `-remaining` / `-reset`) and a separate, tighter budget for the model-backed endpoints (score, rewrite, generate, plan, and voice distillation), reported on those endpoints as `x-ratelimit-llm-limit` / `-remaining` / `-reset`. Either budget can trigger this response.Error

GET/v1/keysBearer

Returns key metadata only. Secrets are never returned.

Example request

curl https://api.socialkit.sh/v1/keys \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Keys listedKeyListResult
401Missing or invalid API keyError

POST/v1/keysBearer

Request body CreateKeyRequest

Example request

curl -X POST https://api.socialkit.sh/v1/keys \
  -H "Authorization: Bearer $SOCIALKIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Responses

201Key createdCreateKeyResult
401Missing or invalid API keyError

POST/v1/keys/{id}/rotateBearer

Path parameters

idrequired string The API key id (e.g. `key_...`).

Example request

curl -X POST https://api.socialkit.sh/v1/keys/key_8fa3c1d9/rotate \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

201Key rotatedCreateKeyResult
401Missing or invalid API keyError
404Resource not found for this accountError

DELETE/v1/keys/{id}Bearer

Path parameters

idrequired string The API key id (e.g. `key_...`).

Example request

curl -X DELETE https://api.socialkit.sh/v1/keys/key_8fa3c1d9 \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Key revokedRevokeResult
401Missing or invalid API keyError
404Resource not found for this accountError

Memory

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.

GET/v1/brandsBearer

Example request

curl https://api.socialkit.sh/v1/brands \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Brands listedBrandListResult
401Missing or invalid API keyError

POST/v1/brandsBearer

Request body BrandCreateRequest

Example request

curl -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."
}'

Responses

201Brand createdBrandResult
400Invalid request bodyError
401Missing or invalid API keyError

GET/v1/brands/{id}Bearer

Path parameters

idrequired string The brand id (e.g. `brd_...`).

Example request

curl https://api.socialkit.sh/v1/brands/brd_8fa3c1d9 \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Brand foundBrandResult
401Missing or invalid API keyError
404Resource not found for this accountError

PATCH/v1/brands/{id}Bearer

Partial update. Only the fields present in the body are changed.

Path parameters

idrequired string The brand id (e.g. `brd_...`).

Request body BrandUpdateRequest

Example request

curl -X PATCH https://api.socialkit.sh/v1/brands/brd_8fa3c1d9 \
  -H "Authorization: Bearer $SOCIALKIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Responses

200Brand updatedBrandResult
400Invalid request bodyError
401Missing or invalid API keyError
404Resource not found for this accountError

DELETE/v1/brands/{id}Bearer

Deletes the brand. Voices attached to it are kept but detached (their brandId becomes null).

Path parameters

idrequired string The brand id (e.g. `brd_...`).

Example request

curl -X DELETE https://api.socialkit.sh/v1/brands/brd_8fa3c1d9 \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Brand deletedDeleteResult
401Missing or invalid API keyError
404Resource not found for this accountError

GET/v1/voicesBearer

Example request

curl https://api.socialkit.sh/v1/voices \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Voices listedVoiceListResult
401Missing or invalid API keyError

POST/v1/voicesBearer

Creates 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.

Request body VoiceCreateRequest

Example request

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."
  ]
}'

Responses

201Voice createdVoiceResult
400Invalid request bodyError
401Missing or invalid API keyError

POST/v1/voices/buildBearer

Reads 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.

Request body BuildVoiceRequest

Example request

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."
  ]
}'

Responses

201Voice built and savedVoiceResult
400Invalid request bodyError
401Missing or invalid API keyError
429Rate limit exceeded. Two budgets apply per key: an overall request budget (headers `x-ratelimit-limit` / `-remaining` / `-reset`) and a separate, tighter budget for the model-backed endpoints (score, rewrite, generate, plan, and voice distillation), reported on those endpoints as `x-ratelimit-llm-limit` / `-remaining` / `-reset`. Either budget can trigger this response.Error
502The model or gateway misbehaved; safe to retryError

GET/v1/voices/{id}Bearer

Path parameters

idrequired string The voice id (e.g. `voi_...`).

Example request

curl https://api.socialkit.sh/v1/voices/voi_8fa3c1d9 \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Voice foundVoiceResult
401Missing or invalid API keyError
404Resource not found for this accountError

PATCH/v1/voices/{id}Bearer

Partial update. Only the fields present in the body are changed.

Path parameters

idrequired string The voice id (e.g. `voi_...`).

Request body VoiceUpdateRequest

Example request

curl -X PATCH https://api.socialkit.sh/v1/voices/voi_8fa3c1d9 \
  -H "Authorization: Bearer $SOCIALKIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Responses

200Voice updatedVoiceResult
400Invalid request bodyError
401Missing or invalid API keyError
404Resource not found for this accountError

DELETE/v1/voices/{id}Bearer

Path parameters

idrequired string The voice id (e.g. `voi_...`).

Example request

curl -X DELETE https://api.socialkit.sh/v1/voices/voi_8fa3c1d9 \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Voice deletedDeleteResult
401Missing or invalid API keyError
404Resource not found for this accountError

Channels

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.

GET/v1/channelsBearer

Returns channel metadata only. Tokens are never included.

Example request

curl https://api.socialkit.sh/v1/channels \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Channels listedChannelListResult
401Missing or invalid API keyError

POST/v1/channels/linkedin/connectBearer

Starts 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.

Request body ConnectChannelRequest

Example request

curl -X POST https://api.socialkit.sh/v1/channels/linkedin/connect \
  -H "Authorization: Bearer $SOCIALKIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Responses

200Authorization URL mintedConnectChannelResult
400Invalid request bodyError
401Missing or invalid API keyError
503The capability is not configured on this deploymentError

GET/v1/channels/linkedin/callbackPublic

Where 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.

Path parameters

`code`required	`string`	The authorization code from LinkedIn.
`state`required	`string`	The opaque state token returned by connect.

Example request

curl https://api.socialkit.sh/v1/channels/linkedin/callback

Responses

200Channel connectedChannelResult
400Invalid or expired OAuth stateError
502The token exchange with the platform failedError
503The capability is not configured on this deploymentError

GET/v1/channels/{id}Bearer

Path parameters

idrequired string The channel id (e.g. `chn_...`).

Example request

curl https://api.socialkit.sh/v1/channels/id_8fa3c1d9 \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Channel foundChannelResult
401Missing or invalid API keyError
404Resource not found for this accountError

DELETE/v1/channels/{id}Bearer

Wipes the stored tokens (unrecoverable) and marks the channel revoked. The row is kept for history.

Path parameters

idrequired string The channel id (e.g. `chn_...`).

Example request

curl -X DELETE https://api.socialkit.sh/v1/channels/id_8fa3c1d9 \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Channel disconnectedChannelResult
401Missing or invalid API keyError
404Resource not found for this accountError

POST/v1/channels/{id}/refreshBearer

Refreshes 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.

Path parameters

idrequired string The channel id (e.g. `chn_...`).

Example request

curl -X POST https://api.socialkit.sh/v1/channels/id_8fa3c1d9/refresh \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Channel refreshed (or already fresh)ChannelResult
401Missing or invalid API keyError
404Resource not found for this accountError
502The token refresh with the platform failedError
503The capability is not configured on this deploymentError

Media

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.

GET/v1/mediaBearer

Results are paginated newest-first; page with limit and offset and follow pagination.hasMore.

Path parameters

`limit`required	`integer`	Maximum media items to return (default 50, max 100).
`offset`required	`integer`	Number of media items to skip from the newest.

Example request

curl https://api.socialkit.sh/v1/media \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Media listedMediaListResult
400Invalid request bodyError
401Missing or invalid API keyError

POST/v1/mediaBearer

Upload 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.

Path parameters

`brandId`required	`string`	Optional brand to attach the media to. Must belong to the account.
`X-Filename`required	`string`	Optional original filename, reduced to a basename.

Example request

curl -X POST https://api.socialkit.sh/v1/media \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

201Media uploadedMediaResult
400Invalid request bodyError
401Missing or invalid API keyError
413The file exceeds the size limit for its typeError
415Unsupported content typeError

GET/v1/media/{id}Bearer

Path parameters

idrequired string The media id (e.g. `med_...`).

Example request

curl https://api.socialkit.sh/v1/media/id_8fa3c1d9 \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Media foundMediaResult
401Missing or invalid API keyError
404Resource not found for this accountError

DELETE/v1/media/{id}Bearer

Removes the metadata row and the stored object.

Path parameters

idrequired string The media id (e.g. `med_...`).

Example request

curl -X DELETE https://api.socialkit.sh/v1/media/id_8fa3c1d9 \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Media deletedDeleteResult
401Missing or invalid API keyError
404Resource not found for this accountError

GET/v1/media/{id}/contentBearer

Path parameters

idrequired string The media id (e.g. `med_...`).

Example request

curl https://api.socialkit.sh/v1/media/id_8fa3c1d9/content \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200The raw file bytes, with the original Content-Type.
401Missing or invalid API keyError
404Resource not found for this accountError

Posts

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.

GET/v1/postsBearer

Optionally filter by status. Results are paginated newest-first; page with limit and offset and follow pagination.hasMore. Posts carry no token material.

Path parameters

`status`required	`string`	Filter to one post status.
`limit`required	`integer`	Maximum posts to return (default 50, max 100).
`offset`required	`integer`	Number of posts to skip from the newest.

Example request

curl https://api.socialkit.sh/v1/posts \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Posts listedPostListResult
400Invalid request bodyError
401Missing or invalid API keyError

POST/v1/postsBearer

Creates a post in the draft state. Supply the text plus optional brand, channel, and media references. Any brandId or channelId must belong to the calling account. Pass an Idempotency-Key header to make a retry of this call safe (a replay returns the original post, not a duplicate).

Path parameters

Idempotency-Keyrequired string A client-chosen key (max 255 chars) that makes a creation 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 creates nothing new. 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.

Request body CreatePostRequest

Example request

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%."
}'

Responses

201Post createdPostResult
400Invalid request bodyError
401Missing or invalid API keyError

GET/v1/posts/{id}Bearer

Path parameters

idrequired string The post id (e.g. `pst_...`).

Example request

curl https://api.socialkit.sh/v1/posts/id_8fa3c1d9 \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Post foundPostResult
401Missing or invalid API keyError
404Resource not found for this accountError

PATCH/v1/posts/{id}Bearer

Partial update. Only draft posts can be edited; editing a post in any other state returns 409. Omit a field to leave it unchanged.

Path parameters

idrequired string The post id (e.g. `pst_...`).

Request body UpdatePostRequest

Example request

curl -X PATCH https://api.socialkit.sh/v1/posts/id_8fa3c1d9 \
  -H "Authorization: Bearer $SOCIALKIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Responses

200Post updatedPostResult
400Invalid request bodyError
401Missing or invalid API keyError
404Resource not found for this accountError
409The request conflicts with the resource's current stateError

DELETE/v1/posts/{id}Bearer

Path parameters

idrequired string The post id (e.g. `pst_...`).

Example request

curl -X DELETE https://api.socialkit.sh/v1/posts/id_8fa3c1d9 \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Post deletedDeleteResult
401Missing or invalid API keyError
404Resource not found for this accountError

POST/v1/posts/{id}/publishBearer

Publishes 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.

Path parameters

idrequired string The post id (e.g. `pst_...`).

Example request

curl -X POST https://api.socialkit.sh/v1/posts/id_8fa3c1d9/publish \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Post publishedPostResult
400Invalid request bodyError
401Missing or invalid API keyError
404Resource not found for this accountError
409Not in a publishable state (not_claimable) or the channel is revoked (channel_revoked). The terminal post is embedded alongside the error.PostErrorResult
502The platform rejected the publish (publish_failed).PostErrorResult
503The capability is not configured on this deploymentError

POST/v1/posts/{id}/scoreBearer

Scores 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.

Path parameters

idrequired string The post id (e.g. `pst_...`).

Example request

curl -X POST https://api.socialkit.sh/v1/posts/id_8fa3c1d9/score \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Post scored and recordedStoredScoreResult
401Missing or invalid API keyError
404Resource not found for this accountError
502The model or gateway misbehaved; safe to retryError

GET/v1/posts/{id}/scoresBearer

Path parameters

idrequired string The post id (e.g. `pst_...`).

Example request

curl https://api.socialkit.sh/v1/posts/id_8fa3c1d9/scores \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Scores listed, newest firstPostScoreListResult
401Missing or invalid API keyError
404Resource not found for this accountError

Scheduling

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.

POST/v1/posts/bulk-scheduleBearer

Creates 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.

Path parameters

Request body BulkScheduleRequest

Example request

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
    }
  ]
}'

Responses

201Posts created and scheduledPostListResult
400Invalid request bodyError
401Missing or invalid API keyError

POST/v1/posts/{id}/scheduleBearer

Sets 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.

Path parameters

idrequired string The post id (e.g. `pst_...`).

Request body SchedulePostRequest

Example request

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
}'

Responses

200Post scheduledPostResult
400Invalid request bodyError
401Missing or invalid API keyError
404Resource not found for this accountError
409The request conflicts with the resource's current stateError

POST/v1/posts/{id}/cancelBearer

Moves the post to canceled and cancels its pending job. A post in a terminal state (published, failed) cannot be canceled and returns 409.

Path parameters

idrequired string The post id (e.g. `pst_...`).

Example request

curl -X POST https://api.socialkit.sh/v1/posts/id_8fa3c1d9/cancel \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Post canceledPostResult
401Missing or invalid API keyError
404Resource not found for this accountError
409The request conflicts with the resource's current stateError

GET/v1/calendarBearer

Returns scheduled and published posts within an optional time window, ordered chronologically. from/to are unix-ms timestamps.

Path parameters

`from`required	`integer`	Start of the window, unix epoch milliseconds.
`to`required	`integer`	End of the window, unix epoch milliseconds.

Example request

curl https://api.socialkit.sh/v1/calendar \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Calendar entriesCalendarResult
400Invalid request bodyError
401Missing or invalid API keyError

Webhooks

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.

GET/v1/webhooksBearer

Returns the account's endpoints (secrets never included) plus the set of events you can subscribe to.

Example request

curl https://api.socialkit.sh/v1/webhooks \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Webhooks listedWebhookListResult
401Missing or invalid API keyError

POST/v1/webhooksBearer

Registers 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.

Request body CreateWebhookRequest

Example request

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"
}'

Responses

201Webhook created; secret returned onceCreateWebhookResult
400Invalid request bodyError
401Missing or invalid API keyError

GET/v1/webhooks/{id}Bearer

Path parameters

idrequired string The webhook endpoint id (e.g. `whk_...`).

Example request

curl https://api.socialkit.sh/v1/webhooks/id_8fa3c1d9 \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Webhook foundWebhookResult
401Missing or invalid API keyError
404Resource not found for this accountError

DELETE/v1/webhooks/{id}Bearer

Path parameters

idrequired string The webhook endpoint id (e.g. `whk_...`).

Example request

curl -X DELETE https://api.socialkit.sh/v1/webhooks/id_8fa3c1d9 \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Webhook deletedDeleteResult
401Missing or invalid API keyError
404Resource not found for this accountError

GET/v1/webhooks/{id}/deliveriesBearer

Returns delivery attempts with status and retry state, newest-first. Results are paginated; page with limit and offset and follow pagination.hasMore.

Path parameters

`id`required	`string`	The webhook endpoint id (e.g. `whk_...`).
`limit`required	`integer`	Maximum deliveries to return (default 50, max 100).
`offset`required	`integer`	Number of deliveries to skip from the newest.

Example request

curl https://api.socialkit.sh/v1/webhooks/id_8fa3c1d9/deliveries \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Deliveries listedDeliveryListResult
400Invalid request bodyError
401Missing or invalid API keyError
404Resource not found for this accountError

Metrics

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.

GET/v1/posts/{id}/metricsBearer

Returns 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.

Path parameters

idrequired string The post id (e.g. `pst_...`).

Example request

curl https://api.socialkit.sh/v1/posts/id_8fa3c1d9/metrics \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Latest snapshot and historyPostMetricsResult
401Missing or invalid API keyError
404Resource not found for this accountError

POST/v1/posts/{id}/metrics/refreshBearer

Polls 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.

Path parameters

idrequired string The post id (e.g. `pst_...`).

Example request

curl -X POST https://api.socialkit.sh/v1/posts/id_8fa3c1d9/metrics/refresh \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200A fresh snapshot was storedMetricRefreshResult
400Invalid request bodyError
401Missing or invalid API keyError
404Resource not found for this accountError
409The request conflicts with the resource's current stateError
502The model or gateway misbehaved; safe to retryError
503The capability is not configured on this deploymentError

GET/v1/analyticsBearer

Aggregates 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).

Path parameters

`from`required	`integer`	Start of the window, unix epoch milliseconds.
`to`required	`integer`	End of the window, unix epoch milliseconds.

Example request

curl https://api.socialkit.sh/v1/analytics \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Aggregated analyticsAnalyticsResult
400Invalid request bodyError
401Missing or invalid API keyError

GET/v1/calibrationBearer

The 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.

Example request

curl https://api.socialkit.sh/v1/calibration \
  -H "Authorization: Bearer $SOCIALKIT_KEY"

Responses

200Calibration rows, newest firstCalibrationResult
401Missing or invalid API keyError

Schemas

80 types

Platformenum

Target platform. Only `linkedin` is live; others are planned.

linkedin

MediaKindenum

The media attached to the post. Drives the format multiplier.

nonesingle-imagemulti-imagedocumentvideopolllink

FollowerBandenum

Author follower bucket. Optional context for calibration.

under-500500-2k2k-10k10k-50k50k-plus

Dimensionenum

A scored dimension of the post.

hookalgorithmFitspecificitystructurevoiceengagement

HookArchetypeenum

The classified shape of the post's opening hook.

contrarianstatementquestionpure-numberstoryother

ScoreRequestobject

Field	Type	Notes
`platform`	`Platform`
`post`required	`string`	The full post text to grade.
`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.

ScoreBreakdownobject

Per-dimension scores, each 0-100.

Field	Type	Notes
`hook`required	`number`
`algorithmFit`required	`number`
`specificity`required	`number`
`structure`required	`number`
`voice`required	`number`
`engagement`required	`number`

Signalobject

One ranked observation about the post.

Field	Type	Notes
`dimension`required	`Dimension`
`impact`required	`string`	`positivenegative`
`weight`required	`integer`	How much this signal moved the score (1-5).
`label`required	`string`	Short headline a human reads at a glance.
`detail`required	`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
`schema`required	`string`	Score schema version.
`overall`required	`number`	Weighted overall score.
`breakdown`required	ScoreBreakdown
`verdict`required	`string`	One-line plain-language verdict.
`signals`required	Signal[]
`hookArchetype`required	`HookArchetype`
`hookArchetypeNote`required	`string`	Benchmark note for the detected hook archetype.
`formatMultiplier`required	`number`	Reach multiplier implied by the chosen media format.
`formatNote`required	`string`	Why the format multiplier is what it is.

RewriteChangeobject

One edit the rewrite made, tied to a scored dimension.

Field	Type	Notes
`dimension`required	`Dimension`
`note`required	`string`	One sentence on what changed and why.

RewriteResultobject

The 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
`rewrite`required	`string`	The rewritten post.
`changes`required	RewriteChange[]
`before`required	ScoreResult
`after`required	ScoreResult

GenerateRequestobject

Field	Type	Notes
`brief`required	`string`	What the post should be about.
`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
`post`required	`string`	The generated post text.
`score`required	ScoreResult

GenerateResultobject

Field	Type	Notes
`candidates`required	GeneratedCandidate[]	Drafts sorted by overall score, best first.

Cadenceenum

Posting rhythm hint for the calendar.

dailyweekdays3x-week

PlanRequestobject

Field	Type	Notes
`brief`required	`string`	Themes, goals, or topics the calendar should cover.
`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
`slot`required	`integer`	1-based ordinal in the plan.
`pillar`required	`string`	The content pillar this idea serves.
`hook`required	`string`	The opening line to write.
`angle`required	`string`	One sentence on the take or argument.
`format`required	`MediaKind`
`archetype`required	`HookArchetype`

PlanResultobject

Field	Type	Notes
`items`required	PlanItem[]

Accountobject

Field	Type	Notes
`id`required	`string`	Account id (e.g. `acc_...`).
`email`required	`string`
`plan`required	`string`	Billing plan. New accounts start on `free`.

ApiKeyobject

API key metadata. The secret is never included.

Field	Type	Notes
`id`required	`string`	Key id (e.g. `key_...`).
`name`required	`string`	Human-readable label for the key.
`keyPrefix`required	`string`	The first characters of the secret, for display.
`createdAt`required	`integer`	Creation time, epoch milliseconds.
`lastUsedAt`required	`integer \| null`	Last successful auth, epoch milliseconds, or null.
`revokedAt`required	`integer \| null`	Revocation time, epoch milliseconds, or null if live.

CreateAccountRequestobject

Field	Type	Notes
`email`required	`string`
`name`	`string`	Optional label for the first key. Defaults to `default`.

CreateAccountResultobject

Field	Type	Notes
`account`required	Account
`key`required	ApiKey
`apiKey`required	`string`	The plaintext key, shown exactly once. Store it now; it cannot be retrieved again.

CreateKeyRequestobject

Field	Type	Notes
`name`	`string`	Optional label for the key. Defaults to `default`.

CreateKeyResultobject

Field	Type	Notes
`key`required	ApiKey
`apiKey`required	`string`	The plaintext key, shown exactly once.

KeyListResultobject

Field	Type	Notes
`keys`required	ApiKey[]

RevokeResultobject

Field	Type	Notes
`revoked`required	`boolean`	True when the key was revoked.

Brandobject

Workspace context that conditions generation.

Field	Type	Notes
`id`required	`string`	Brand id (e.g. `brd_...`).
`name`required	`string`
`description`required	`string \| null`	Who the business is.
`audience`required	`string \| null`	Who the brand talks to.
`themes`required	`string[]`	Recurring themes the brand posts about.
`linkPolicy`required	`string \| null`	Free-text policy on outbound links.
`createdAt`required	`integer`	Creation time, epoch milliseconds.
`updatedAt`required	`integer`	Last update time, epoch milliseconds.

BrandCreateRequestobject

Field	Type	Notes
`name`required	`string`
`description`	`string \| null`
`audience`	`string \| null`
`themes`	`string[]`
`linkPolicy`	`string \| null`

BrandUpdateRequestobject

Partial update; omit a field to leave it unchanged.

Field	Type	Notes
`name`	`string`
`description`	`string \| null`
`audience`	`string \| null`
`themes`	`string[]`
`linkPolicy`	`string \| null`

BrandResultobject

Field	Type	Notes
`brand`required	Brand

BrandListResultobject

Field	Type	Notes
`brands`required	Brand[]

Voiceobject

A reusable writing profile distilled from sample posts.

Field	Type	Notes
`id`required	`string`	Voice id (e.g. `voi_...`).
`brandId`required	`string \| null`	The brand this voice belongs to, or null.
`name`required	`string`
`traits`required	`string[]`	Stylistic traits to imitate.
`doNot`required	`string[]`	Things this voice never does.
`exemplars`required	`string[]`	Few-shot snippets that anchor the voice.
`createdAt`required	`integer`	Creation time, epoch milliseconds.
`updatedAt`required	`integer`	Last update time, epoch milliseconds.

VoiceCreateRequestobject

Field	Type	Notes
`name`required	`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[]`

VoiceUpdateRequestobject

Partial 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
`name`required	`string`
`brandId`	`string`	Optional brand to attach the built voice to.
`samples`required	`string[]`	1-12 sample posts written in the target voice.

VoiceResultobject

Field	Type	Notes
`voice`required	Voice

VoiceListResultobject

Field	Type	Notes
`voices`required	Voice[]

DeleteResultobject

Field	Type	Notes
`deleted`required	`boolean`	True when the resource was deleted.

ChannelStatusenum

Connection health of the channel.

connectedexpiredrevokederror

Channelobject

A connected social account. Carries no token material.

Field	Type	Notes
`id`required	`string`	Channel id (e.g. `chn_...`).
`accountId`required	`string`	The owning account id.
`brandId`required	`string \| null`	The brand this channel belongs to, or null.
`platform`required	`string`	The platform, e.g. `linkedin`.
`platformUserId`required	`string \| null`	The platform's stable user id for the connected member.
`handle`required	`string \| null`	A display handle or name for the connected account.
`status`required	`ChannelStatus`
`scopes`required	`string[]`	Granted OAuth scopes.
`expiresAt`required	`integer \| null`	Access token expiry, epoch milliseconds, or null.
`lastRefreshAt`required	`integer \| null`	Last token refresh, epoch milliseconds, or null.
`createdAt`required	`integer`	Creation time, epoch milliseconds.
`updatedAt`required	`integer`	Last update time, epoch milliseconds.

ChannelResultobject

Field	Type	Notes
`channel`required	Channel

ChannelListResultobject

Field	Type	Notes
`channels`required	Channel[]

ConnectChannelRequestobject

Field	Type	Notes
`brandId`	`string`	Optional brand to scope the channel to. Must belong to the calling account.

ConnectChannelResultobject

Field	Type	Notes
`url`required	`string`	The platform authorization URL to redirect the member to.
`state`required	`string`	The opaque, single-use state token tying the callback to this account. Returned for visibility; the callback validates it.

Mediaobject

Metadata for an uploaded file. The storage key is never returned.

Field	Type	Notes
`id`required	`string`	Media id (e.g. `med_...`).
`accountId`required	`string`	The owning account id.
`brandId`required	`string \| null`	The brand this media belongs to, or null.
`contentType`required	`string`	The validated MIME type of the stored bytes.
`size`required	`integer`	Size in bytes.
`filename`required	`string \| null`	The original filename (basename), or null.
`sha256`required	`string`	SHA-256 of the bytes, hex-encoded.
`createdAt`required	`integer`	Upload time, epoch milliseconds.

MediaResultobject

Field	Type	Notes
`media`required	Media

MediaListResultobject

Field	Type	Notes
`media`required	Media[]
`pagination`required	`object`

PostStatusenum

Where the post sits in its lifecycle.

draftscheduledpublishingpublishedfailedcanceled

Postobject

A unit of content. Carries no token material.

Field	Type	Notes
`id`required	`string`	Post id (e.g. `pst_...`).
`accountId`required	`string`	The owning account id.
`brandId`required	`string \| null`	The brand this post belongs to, or null.
`channelId`required	`string \| null`	The channel this post publishes to, or null.
`platform`required	`string`	The target platform, e.g. `linkedin`.
`status`required	`PostStatus`
`text`required	`string`	The post body.
`mediaIds`required	`string[]`	Ids of media attached to the post.
`scheduledFor`required	`integer \| null`	Scheduled publish time, epoch milliseconds, or null.
`publishedAt`required	`integer \| null`	Actual publish time, epoch milliseconds, or null.
`platformPostId`required	`string \| null`	The platform's id for the published post, or null.
`platformUrl`required	`string \| null`	Public URL of the published post, or null.
`error`required	`string \| null`	The last publish error, or null.
`createdAt`required	`integer`	Creation time, epoch milliseconds.
`updatedAt`required	`integer`	Last update time, epoch milliseconds.

PostResultobject

Field	Type	Notes
`post`required	Post

PostListResultobject

Field	Type	Notes
`posts`required	Post[]
`pagination`required	`object`

PostErrorResultobject

An error with the affected post's terminal state embedded.

Field	Type	Notes
`error`required	`object`
`post`required	Post

CreatePostRequestobject

Field	Type	Notes
`text`required	`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[]`

UpdatePostRequestobject

Partial 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
`runAt`required	`integer`	When to publish, epoch milliseconds. Must be in the future.

BulkScheduleItemobject

Field	Type	Notes
`text`required	`string`
`runAt`required	`integer`	When to publish this post, epoch milliseconds.
`channelId`	`string \| null`
`brandId`	`string \| null`
`platform`	`string`
`mediaIds`	`string[]`

BulkScheduleRequestobject

Field	Type	Notes
`items`required	BulkScheduleItem[]

PostScoreobject

A score recorded against a stored post.

Field	Type	Notes
`id`required	`string`	Score id (e.g. `psc_...`).
`postId`required	`string`
`score`required	`integer`	The overall score, rounded.
`verdict`required	`string \| null`	One-line plain-language verdict, or null.
`payload`required	`object`	The full ScoreResult captured at scoring time.
`createdAt`required	`integer`	When the score was recorded, epoch milliseconds.

StoredScoreResultobject

Field	Type	Notes
`score`required	PostScore
`result`required	ScoreResult

PostScoreListResultobject

Field	Type	Notes
`scores`required	PostScore[]

CalendarEntryobject

Field	Type	Notes
`postId`required	`string`
`status`required	`PostStatus`
`when`required	`integer`	Scheduled or published time, epoch milliseconds.
`channelId`required	`string \| null`
`platform`required	`string`
`preview`required	`string`	A short preview of the post text.

CalendarResultobject

Field	Type	Notes
`calendar`required	CalendarEntry[]

MetricSnapshotobject

One 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
`id`required	`string`	Snapshot id (e.g. `met_...`).
`postId`required	`string`
`impressions`required	`integer \| null`
`likes`required	`integer \| null`
`comments`required	`integer \| null`
`shares`required	`integer \| null`
`clicks`required	`integer \| null`
`fetchedAt`required	`integer`	When this snapshot was captured, epoch milliseconds.

PostMetricsResultobject

Field	Type	Notes
`latest`required	`object`	The most recent snapshot, or null if never polled.
`history`required	MetricSnapshot[]	All snapshots, newest first.

MetricRefreshResultobject

Field	Type	Notes
`snapshot`required	MetricSnapshot

MetricTotalsobject

Field	Type	Notes
`posts`required	`integer`	Posts counted (those with at least one snapshot).
`impressions`required	`integer`
`likes`required	`integer`
`comments`required	`integer`
`shares`required	`integer`
`clicks`required	`integer`
`engagements`required	`integer`	likes + comments + shares + clicks.

PlatformTotalsobject

Field	Type	Notes

Analyticsobject

Field	Type	Notes

AnalyticsResultobject

Field	Type	Notes
`analytics`required	Analytics

CalibrationRowobject

A published post paired with its predicted score and measured engagement. Only posts that have both appear.

Field	Type	Notes
`postId`required	`string`
`platform`required	`string`
`score`required	`integer`	The latest recorded score.
`verdict`required	`string \| null`
`publishedAt`required	`integer \| null`	When the post was published, epoch milliseconds.
`impressions`required	`integer \| null`
`likes`required	`integer \| null`
`comments`required	`integer \| null`
`shares`required	`integer \| null`
`clicks`required	`integer \| null`
`engagements`required	`integer`	likes + comments + shares + clicks (nulls counted as 0).

CalibrationResultobject

Field	Type	Notes
`calibration`required	CalibrationRow[]

WebhookEventenum

An event you can subscribe a webhook to.

post.publishedpost.failedpost.scoredchannel.disconnected

WebhookEndpointobject

A signed callback endpoint. The secret is never included here.

Field	Type	Notes
`id`required	`string`	Webhook id (e.g. `whk_...`).
`accountId`required	`string`
`url`required	`string`	The callback URL.
`events`required	`WebhookEvent[]`
`status`required	`string`	`activedisabled`
`createdAt`required	`integer`	Creation time, epoch milliseconds.
`updatedAt`required	`integer`	Last update time, epoch milliseconds.

CreateWebhookRequestobject

Field	Type	Notes
`url`required	`string`	The HTTPS callback URL to deliver events to.
`events`	`WebhookEvent[]`	Events to subscribe to. Omit to subscribe to all.

CreateWebhookResultobject

Field	Type	Notes
`webhook`required	WebhookEndpoint
`secret`required	`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
`webhook`required	WebhookEndpoint

WebhookListResultobject

Field	Type	Notes
`webhooks`required	WebhookEndpoint[]
`events`required	`WebhookEvent[]`	The full set of subscribable events.

WebhookDeliveryobject

Field	Type	Notes
`id`required	`string`
`webhookId`required	`string`
`event`required	`string`
`status`required	`string`	`pendingsendingdeliveredfaileddead`
`attempts`required	`integer`	Number of delivery attempts so far.
`lastStatusCode`required	`integer \| null`	HTTP status of the last attempt, or null.
`lastError`required	`string \| null`	Error from the last attempt, or null.
`nextAttemptAt`required	`integer \| null`	When the next retry is due, epoch milliseconds, or null.
`createdAt`required	`integer`
`updatedAt`required	`integer`

DeliveryListResultobject

Field	Type	Notes
`deliveries`required	WebhookDelivery[]
`pagination`required	`object`

Errorobject

Field	Type	Notes
`error`required	`object`

200Rewrite producedRewriteResult

400Invalid request bodyError

401Missing or invalid API keyError

429Rate limit exceeded. Two budgets apply per key: an overall request budget (headers `x-ratelimit-limit` / `-remaining` / `-reset`) and a separate, tighter budget for the model-backed endpoints (score, rewrite, generate, plan, and voice distillation), reported on those endpoints as `x-ratelimit-llm-limit` / `-remaining` / `-reset`. Either budget can trigger this response.Error

502The model or gateway misbehaved; safe to retryError

200Candidates generatedGenerateResult

200Plan producedPlanResult

201Account createdCreateAccountResult

409An account already exists for that emailError

201Voice built and savedVoiceResult

200Channel refreshed (or already fresh)ChannelResult

404Resource not found for this accountError

502The token refresh with the platform failedError

503The capability is not configured on this deploymentError

200Post publishedPostResult

409Not in a publishable state (not_claimable) or the channel is revoked (channel_revoked). The terminal post is embedded alongside the error.PostErrorResult

502The platform rejected the publish (publish_failed).PostErrorResult

200A fresh snapshot was storedMetricRefreshResult

409The request conflicts with the resource's current stateError

The SocialKit API.

Quickstart

Create an account

Export your key

Score your first post

Read the response

API reference

Schemas

Need something we don't have?