Social API reference

Social API · Posts

post/v1/communities/{community_id}/postsAuth

Create 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*string

Social community UUID. Must belong to the PAK's workspace.

Headers

Idempotency-Keystring

Opaque 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 · uuid

Social actor UUID who authors the post (returned from POST /actors).

Example: "aaaaaaaa-0000-0000-0000-000000000001"

kindstring

Post kind. Free-form short label; common values: text, link, image, story.

Example: "text"

titlestring

Optional title (1-240 chars).

Example: "Shipping Phase 8"

bodystring

Body markdown / plain text (up to 50000 chars).

Example: "Stories are live!"

urlstring

Optional URL (for link / image kinds).

Example: "https://cdn.example.com/img.png"

attributesobject

Free-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-time

ISO-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_forstring

Required 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 · uuid

For `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"

settingsobject

Per-post interaction settings (comment policy, hide reaction counts, allow repost/quote). Omitted keys default to the open shape. Enforced server-side.

tagsarray

Actor 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"]

assetsarray

Ordered 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 · uuid

Post UUID.

Example: "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"

community_id*string · uuid

Owning community UUID.

Example: "cccccccc-cccc-cccc-cccc-cccccccccccc"

actor_id*string · uuid

Author actor UUID.

Example: "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"

kind*string

Free-form post kind. Common: text, link, image, story, repost, quote.

Example: "text"

title*string

Optional title (1-240 chars).

Example: "Shipping Phase 8"

body*string

Body markdown / plain text (up to 50000 chars).

Example: "Stories are live!"

url*string

Optional URL.

Example: "https://cdn.example.com/img.png"

attributes*object

Free-form attributes blob (polls live at `attributes.poll`).

Example: {}

visibility*object

Visibility scope.

Example: "public"

status*object

Lifecycle 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*object

Map of reaction type to count, denormalised on the post row for cheap feed reads.

Example: {"like":12,"fire":3}

comment_count*number

Comment count, denormalised on the post row.

Example: 4

source_post_id*string · uuid

For kind='repost' / 'quote': the source post UUID.

Example: null

repost_count*number

Denormalised count of currently-published reposts.

Example: 0

quote_count*number

Denormalised count of currently-published quote posts.

Example: 0

edited_at*string · date-time

ISO timestamp of the most recent edit (body/title/attributes change). Null when never edited.

Example: null

edit_count*number

Number of edits applied; equals the count of post_revision rows.

Example: 0

view_count*number

Denormalised impression count, bumped via the batch POST /posts/views endpoint.

Example: 0

expires_at*string · date-time

ISO timestamp; `null` = no expiry. Stories typically set this 24h ahead.

Example: null

pinned*boolean

When `true`, surfaces in the author's highlights endpoint regardless of expiry.

Example: false

settings*object

Typed per-post interaction settings (comment policy, count hiding, repost/quote permission). Enforced server-side.

scheduled_for*string

ISO 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*array

Ordered image attachments (task 019). Ref-only; resolve renditions via GET /assets/:id.

created_at*string · date-time

ISO timestamp the row was inserted.

Example: "2026-05-01T12:00:00.000Z"

updated_at*string · date-time

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