Social API reference

Social API · Actors

post/v1/communities/{community_id}/actorsAuth

Upsert 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

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._:-]`) that makes a retry safe: within 24 h a repeat with the same key and body returns the original response with `Idempotent-Replay: true` instead of running again. Same key with a different body is `409 IDEMPOTENCY_KEY_REUSE`.

Request body

external_id*string

Customer-side identifier (your user id). Idempotency key for upsert; unique per community.

Example: "user_abc123"

display_namestring

Display name shown in feeds / mentions.

Example: "Ada Lovelace"

avatar_urlstring

Avatar URL.

Example: "https://cdn.example.com/avatars/ada.png"

metadataobject

Free-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*object
id*string · uuid

Social actor UUID.

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

community_id*string · uuid

Owning community UUID.

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

external_id*string

Customer-supplied stable identifier (your user id).

Example: "user_abc123"

display_name*string

Display name.

Example: "Ada Lovelace"

avatar_url*string

Avatar URL.

Example: "https://cdn.example.com/avatars/ada.png"

metadata*object

Free-form metadata blob.

Example: {"tier":"pro"}

status*object

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"

is_private*boolean

When true, the actor is private (task 014): effective post visibility is capped at `followers` and following requires an approved follow request.

Example: false

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"

created*boolean

`true` on first call (row was inserted), `false` on subsequent upserts that updated an existing row.

Example: true

Example

Request

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

{
  "external_id": "user_abc123",
  "display_name": "Ada Lovelace",
  "avatar_url": "https://cdn.example.com/avatars/ada.png",
  "metadata": {
    "tier": "pro"
  }
}

Response

{
  "actor": {
    "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "community_id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
    "external_id": "user_abc123",
    "display_name": "Ada Lovelace",
    "avatar_url": "https://cdn.example.com/avatars/ada.png",
    "metadata": {
      "tier": "pro"
    },
    "status": "active",
    "is_private": false,
    "created_at": "2026-05-01T12:00:00.000Z",
    "updated_at": "2026-05-01T12:00:00.000Z"
  },
  "created": true
}