Social API reference

Social API · Posts

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

Get a post by id. Visibility-aware: pass `actor_id` for non-public posts.

Without `actor_id`, only `public` posts return. With one, `followers` / `close_friends` / the requester's own `private` posts surface per the visibility matrix. Returns 404 (opacity) when the requester is not allowed to read the post — never 403.

Path parameters

community_id*string

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

post_id*string

Social post UUID.

Query parameters

actor_idstring · uuid

Social actor UUID of the viewer. Surfaces non-public posts they are entitled to see.

Response · 200 Post.

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

GET https://social.productcraft.co/v1/communities/{community_id}/posts/{post_id}
Authorization: Bearer YOUR_TOKEN

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