/v1/communities/{communityId}/postsList posts. Pass `author_id` to filter to a single author. 50/page (max 200), cursor-paginated.
Path parameters
communityId*stringQuery parameters
limitintegercursorstringOpaque cursor from `pagination.next_cursor`.
author_idstring · uuidLimit results to this actor.
Response · 200 Page of posts (only `published`, non-expired, public-visibility unless filtered by author).
data*arraypagination*objectnext_cursor*stringOpaque base64url cursor for the next page; `null` when no further pages.
Example: "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0wMVQxMjowMDowMC4wMDBaIiwiaWQiOiJiYmJiIn0"
has_more*boolean`true` when at least one more page exists. Mirrors `next_cursor !== null`; published as a separate field so SDKs can drive a `while` loop without parsing the cursor.
Example: true
Example
Request
GET /v1/communities/{communityId}/postsResponse
{
"data": [
{
"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,
"scheduled_for": null,
"created_at": "2026-05-01T12:00:00.000Z",
"updated_at": "2026-05-01T12:00:00.000Z"
}
],
"pagination": {
"next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0wMVQxMjowMDowMC4wMDBaIiwiaWQiOiJiYmJiIn0",
"has_more": true
}
}
Social-Actors
/v1/communities/{communityId}/actorsAuthList actors in a community. 50 per page by default (max 200) — paginate with the cursor returned in `pagination.next_cursor` while `pagination.has_more` is true.
Path parameters
communityId*stringSocial community UUID. Must belong to the PAK's workspace.
Query parameters
limitintegerPage size; capped at 200.
cursorstringOpaque cursor from the previous page's `pagination.next_cursor`.
Response · 200 Page of actors with `next_cursor` + `has_more`.
data*arraypagination*objectnext_cursor*stringOpaque base64url cursor for the next page; `null` when no further pages.
Example:
"eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0wMVQxMjowMDowMC4wMDBaIiwiaWQiOiJiYmJiIn0"has_more*boolean`true` when at least one more page exists. Mirrors `next_cursor !== null`; published as a separate field so SDKs can drive a `while` loop without parsing the cursor.
Example:
trueExample
Request
Response
/v1/communities/{communityId}/actorsAuthUpsert an actor by external_id. Creates on first call, updates on subsequent calls with the same external_id. Idempotent on `(community, external_id)`. Note: omitted fields on a follow-up call are overwritten with the new body — pass every field you want to keep on each call.
Path parameters
communityId*stringSocial community UUID. Must belong to the PAK's workspace.
Request body
external_id*stringCustomer-side identifier (your user id). Idempotency key for upsert; unique per community.
Example:
"user_abc123"display_namestringDisplay name shown in feeds / mentions.
Example:
"Ada Lovelace"avatar_urlstringAvatar URL.
Example:
"https://cdn.example.com/avatars/ada.png"metadataobjectFree-form metadata blob (e.g. plan tier, internal flags).
Example:
{"tier":"pro"}Response · 201 Created (`created: true`) or upserted (`created: false`); the actor row is returned in both cases.
actor*objectid*stringSocial actor UUID.
Example:
"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"community_id*stringOwning community UUID.
Example:
"cccccccc-cccc-cccc-cccc-cccccccccccc"external_id*stringCustomer-supplied stable identifier (your user id).
Example:
"user_abc123"display_name*stringDisplay name.
Example:
"Ada Lovelace"avatar_url*stringAvatar URL.
Example:
"https://cdn.example.com/avatars/ada.png"metadata*objectFree-form metadata blob.
Example:
{"tier":"pro"}status*enum (3)Lifecycle status. `suspended` is moderator-applied via PATCH `status=suspended`; `deleted` is soft-deletion. Shadow-banning is a separate moderation mechanism that does not change `status`.
Example:
"active"created_at*stringISO timestamp the row was inserted.
Example:
"2026-05-01T12:00:00.000Z"updated_at*stringISO timestamp of the last update.
Example:
"2026-05-01T12:00:00.000Z"created*boolean`true` on first call (row was inserted), `false` on subsequent upserts that updated an existing row.
Example:
trueExample
Request
Response
/v1/communities/{communityId}/actors/by-external/{externalId}AuthLook up an actor by the customer-supplied external_id.
Path parameters
communityId*stringSocial community UUID. Must belong to the PAK's workspace.
externalId*stringCustomer-supplied identifier for the user (the `external_id` you upserted with).
Response · 200 Actor row.
id*stringSocial actor UUID.
Example:
"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"community_id*stringOwning community UUID.
Example:
"cccccccc-cccc-cccc-cccc-cccccccccccc"external_id*stringCustomer-supplied stable identifier (your user id).
Example:
"user_abc123"display_name*stringDisplay name.
Example:
"Ada Lovelace"avatar_url*stringAvatar URL.
Example:
"https://cdn.example.com/avatars/ada.png"metadata*objectFree-form metadata blob.
Example:
{"tier":"pro"}status*enum (3)Lifecycle status. `suspended` is moderator-applied via PATCH `status=suspended`; `deleted` is soft-deletion. Shadow-banning is a separate moderation mechanism that does not change `status`.
Example:
"active"created_at*stringISO timestamp the row was inserted.
Example:
"2026-05-01T12:00:00.000Z"updated_at*stringISO timestamp of the last update.
Example:
"2026-05-01T12:00:00.000Z"Example
Request
Response
/v1/communities/{communityId}/actors/{actorId}AuthGet an actor by its UUID.
Path parameters
communityId*stringSocial community UUID. Must belong to the PAK's workspace.
actorId*stringSocial actor UUID (the id returned by upsert).
Response · 200 Actor row.
id*stringSocial actor UUID.
Example:
"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"community_id*stringOwning community UUID.
Example:
"cccccccc-cccc-cccc-cccc-cccccccccccc"external_id*stringCustomer-supplied stable identifier (your user id).
Example:
"user_abc123"display_name*stringDisplay name.
Example:
"Ada Lovelace"avatar_url*stringAvatar URL.
Example:
"https://cdn.example.com/avatars/ada.png"metadata*objectFree-form metadata blob.
Example:
{"tier":"pro"}status*enum (3)Lifecycle status. `suspended` is moderator-applied via PATCH `status=suspended`; `deleted` is soft-deletion. Shadow-banning is a separate moderation mechanism that does not change `status`.
Example:
"active"created_at*stringISO timestamp the row was inserted.
Example:
"2026-05-01T12:00:00.000Z"updated_at*stringISO timestamp of the last update.
Example:
"2026-05-01T12:00:00.000Z"Example
Request
Response
/v1/communities/{communityId}/actors/{actorId}AuthUpdate actor profile fields. Pass only the fields you want to change.
Path parameters
communityId*stringSocial community UUID. Must belong to the PAK's workspace.
actorId*stringSocial actor UUID.
Request body
display_namestringavatar_urlstringmetadataobjectstatusenum (3)Response · 200 Actor updated.
id*stringSocial actor UUID.
Example:
"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"community_id*stringOwning community UUID.
Example:
"cccccccc-cccc-cccc-cccc-cccccccccccc"external_id*stringCustomer-supplied stable identifier (your user id).
Example:
"user_abc123"display_name*stringDisplay name.
Example:
"Ada Lovelace"avatar_url*stringAvatar URL.
Example:
"https://cdn.example.com/avatars/ada.png"metadata*objectFree-form metadata blob.
Example:
{"tier":"pro"}status*enum (3)Lifecycle status. `suspended` is moderator-applied via PATCH `status=suspended`; `deleted` is soft-deletion. Shadow-banning is a separate moderation mechanism that does not change `status`.
Example:
"active"created_at*stringISO timestamp the row was inserted.
Example:
"2026-05-01T12:00:00.000Z"updated_at*stringISO timestamp of the last update.
Example:
"2026-05-01T12:00:00.000Z"Example
Request
Response
/v1/communities/{communityId}/actors/{actorId}AuthDelete an actor. Hard delete — cascades to every post, comment, edge, flag, and notification it owns.
Path parameters
communityId*stringSocial community UUID. Must belong to the PAK's workspace.
actorId*stringSocial actor UUID.
Response · 204
Actor deleted.