/v1/communities/{community_id}/postsAuthCreate a post on behalf of an actor. Pass an `Idempotency-Key` header to make retries safe — replays return the original response with `Idempotent-Replay: true` for 24h.
Path parameters
community_id*stringSocial community UUID. Must belong to the PAK's workspace.
Headers
Idempotency-KeystringOpaque client-generated string (1–256 chars, `[A-Za-z0-9._:-]`) used to deduplicate retries within a 24h window. Same key + different body returns 409 `IDEMPOTENCY_KEY_REUSE`.
Request body
actor_id*string · uuidSocial actor UUID who authors the post (returned from POST /actors).
Example: "aaaaaaaa-0000-0000-0000-000000000001"
kindstringPost kind. Free-form short label; common values: text, link, image, story.
Example: "text"
titlestringOptional title (1-240 chars).
Example: "Shipping Phase 8"
bodystringBody markdown / plain text (up to 50000 chars).
Example: "Stories are live!"
urlstringOptional URL (for link / image kinds).
Example: "https://cdn.example.com/img.png"
attributesobjectFree-form attributes blob. Polls live here at `attributes.poll`.
Example: {"media_url":"https://cdn.example.com/stories/1.jpg"}
visibilityenum (4)Visibility scope. Defaults to `public`.
Example: "public"
expires_atstring · date-timeISO-8601 expiry timestamp. Used by stories (24h disappearing).
Example: "2026-05-02T12:00:00Z"
statusenum (3)Initial status. Defaults to `published`. Pass `draft` to save unpublished; pass `scheduled` with a future `scheduled_for` to defer publication. Scheduled posts are invisible to everyone except the author until the per-minute scheduler promotes them.
scheduled_forstringRequired when status='scheduled'. ISO timestamp at least 30 seconds in the future. The PostSchedulerCron promotes scheduled posts to published once now() >= scheduled_for.
source_post_idstring · uuidFor `kind='quote'` ONLY: the source post being quoted. Reposts use the dedicated POST /posts/:post_id/repost route instead. Validation: when `kind='quote'`, both `source_post_id` and a non-empty `body` are required.
Example: "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
settingsobjectPer-post interaction settings (comment policy, hide reaction counts, allow repost/quote). Omitted keys default to the open shape. Enforced server-side.
tagsarrayActor UUIDs to tag in the post (task 011). Each lands as a pending tag the actor approves. Non-actors and blocked pairs are skipped. Max 30.
Example: ["aaaaaaaa-0000-0000-0000-000000000002"]
assetsarrayOrdered image attachments (task 019). Each references a `ready` asset in this community owned by the author. Max 20.
Response · 201 Post created. Defaults: `kind=text`, `visibility=public`, `status=published`.
id*string · uuidPost UUID.
Example: "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
community_id*string · uuidOwning community UUID.
Example: "cccccccc-cccc-cccc-cccc-cccccccccccc"
actor_id*string · uuidAuthor actor UUID.
Example: "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
kind*stringFree-form post kind. Common: text, link, image, story, repost, quote.
Example: "text"
title*stringOptional title (1-240 chars).
Example: "Shipping Phase 8"
body*stringBody markdown / plain text (up to 50000 chars).
Example: "Stories are live!"
url*stringOptional URL.
Example: "https://cdn.example.com/img.png"
attributes*objectFree-form attributes blob (polls live at `attributes.poll`).
Example: {}
visibility*objectVisibility scope.
Example: "public"
status*objectLifecycle status. Public list/feed surfaces only return `published`; `draft`, `scheduled`, and `archived` rows surface exclusively on their author-scoped listings and author reads. `removed` rows are hidden from reads. `archived` keeps engagement but is author-only.
Example: "published"
reaction_counts*objectMap of reaction type to count, denormalised on the post row for cheap feed reads.
Example: {"like":12,"fire":3}
comment_count*numberComment count, denormalised on the post row.
Example: 4
source_post_id*string · uuidFor kind='repost' / 'quote': the source post UUID.
Example: null
repost_count*numberDenormalised count of currently-published reposts.
Example: 0
quote_count*numberDenormalised count of currently-published quote posts.
Example: 0
edited_at*string · date-timeISO timestamp of the most recent edit (body/title/attributes change). Null when never edited.
Example: null
edit_count*numberNumber of edits applied; equals the count of post_revision rows.
Example: 0
view_count*numberDenormalised impression count, bumped via the batch POST /posts/views endpoint.
Example: 0
expires_at*string · date-timeISO timestamp; `null` = no expiry. Stories typically set this 24h ahead.
Example: null
pinned*booleanWhen `true`, surfaces in the author's highlights endpoint regardless of expiry.
Example: false
settings*objectTyped per-post interaction settings (comment policy, count hiding, repost/quote permission). Enforced server-side.
scheduled_for*stringISO publish-at timestamp, set while status='scheduled'. The scheduler cron promotes the post to published and clears this field; a manual PATCH promotion leaves the last value in place unless the caller also passes scheduled_for: null.
Example: null
assets*arrayOrdered image attachments (task 019). Ref-only; resolve renditions via GET /assets/:id.
created_at*string · date-timeISO timestamp the row was inserted.
Example: "2026-05-01T12:00:00.000Z"
updated_at*string · date-timeISO timestamp of the last update.
Example: "2026-05-01T12:00:00.000Z"
Example
Request
POST https://social.productcraft.co/v1/communities/{community_id}/posts
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"actor_id": "aaaaaaaa-0000-0000-0000-000000000001",
"kind": "text",
"title": "Shipping Phase 8",
"body": "Stories are live!",
"url": "https://cdn.example.com/img.png",
"attributes": {
"media_url": "https://cdn.example.com/stories/1.jpg"
},
"visibility": "public",
"expires_at": "2026-05-02T12:00:00Z",
"status": "published",
"scheduled_for": "string",
"source_post_id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
"settings": {},
"tags": [
"aaaaaaaa-0000-0000-0000-000000000002"
],
"assets": [
{
"asset_id": "eeeeeeee-0000-0000-0000-000000000001",
"alt_text": "string"
}
]
}Response
{
"id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
"community_id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
"actor_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
"kind": "text",
"title": "Shipping Phase 8",
"body": "Stories are live!",
"url": "https://cdn.example.com/img.png",
"attributes": {},
"visibility": "public",
"status": "published",
"reaction_counts": {
"like": 12,
"fire": 3
},
"comment_count": 4,
"source_post_id": null,
"repost_count": 0,
"quote_count": 0,
"edited_at": null,
"edit_count": 0,
"view_count": 0,
"expires_at": null,
"pinned": false,
"settings": {},
"scheduled_for": null,
"assets": [
{
"asset_id": "eeeeeeee-0000-0000-0000-000000000001",
"alt_text": "A golden retriever on a beach"
}
],
"created_at": "2026-05-01T12:00:00.000Z",
"updated_at": "2026-05-01T12:00:00.000Z"
}