Social API reference

Social API · Posts

patch/v1/communities/{community_id}/posts/{post_id}Auth

Update post fields. `pinned` is the highlights toggle for stories; status transitions to `hidden`/`removed` should usually go through the moderation lane.

Path parameters

community_id*string

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

post_id*string

Social post UUID.

Request body

titlestring

Updated title.

bodystring

Updated body.

urlstring

Updated URL.

attributesobject

Replaces the attributes blob entirely.

visibilityenum (4)

Who can see the post.

statusenum (6)

Direct status transition. Pass `published` to promote a `draft`/`scheduled` or restore an `archived` post; pass `archived` to hide-without-deleting (engagement kept). Prefer the moderation lane for `hidden`/`removed`.

expires_atstring · date-time

ISO-8601 expiry timestamp; pass null to clear.

scheduled_forstring

ISO-8601 publish-at timestamp. Updating only valid while the post is `status="scheduled"`. Pass null to clear (typically only the scheduler does this on promotion).

pinnedboolean

Toggle pinned status (used by highlights / stories).

settingsobject

Partial update of the per-post interaction settings. Only the keys you pass change; the rest keep their current value.

tagsarray

Additional actor UUIDs to tag (task 011). Additive — creates new pending tags; never resets existing approved/removed tags. Max 30.

Example: ["aaaaaaaa-0000-0000-0000-000000000002"]

Response · 200 Post updated.

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

PATCH https://social.productcraft.co/v1/communities/{community_id}/posts/{post_id}
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "title": "string",
  "body": "string",
  "url": "string",
  "attributes": {},
  "visibility": "public",
  "status": "published",
  "expires_at": "2026-01-01T00:00:00.000Z",
  "scheduled_for": "string",
  "pinned": false,
  "settings": {},
  "tags": [
    "aaaaaaaa-0000-0000-0000-000000000002"
  ]
}

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