Social API reference

Social API · Moderation-Admin

post/v1/workspaces/{workspace_id}/communities/{community_id}/moderation/actors/{actor_id}/shadow-banAuth

Apply a shadow ban to an actor. The actor sees their own content normally; everyone else sees nothing from them. Pass `duration_hours` for a timed ban or omit for indefinite. Pass an `Idempotency-Key` header so a retried timed ban doesn't restart the clock.

Path parameters

workspace_id*string · uuid

Id of the workspace.

community_id*string · uuid

Id of the community.

actor_id*string · uuid

Id of the actor.

Headers

Idempotency-Keystring

Opaque client-generated string (1–256 chars, `[A-Za-z0-9._:-]`) used to deduplicate retries within a 24h window. Replays return the original response with `Idempotent-Replay: true`; same key + different body returns 409 `IDEMPOTENCY_KEY_REUSE`.

Request body

duration_hoursnumber

Hours until auto-restore. Omit for indefinite.

Example: 168

reasonstring

Moderator note (1..1000 chars).

Response · 200 Shadow ban applied.

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"

shadow_banned_at*string · date-time

ISO timestamp the shadow ban was applied, or null.

shadow_banned_until*string

ISO timestamp the shadow ban auto-expires, or null for indefinite.

shadow_banned_reason*string

Moderator note attached to the ban.

Example

Request

POST https://social.productcraft.co/v1/workspaces/{workspace_id}/communities/{community_id}/moderation/actors/{actor_id}/shadow-ban
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "duration_hours": 168,
  "reason": "string"
}

Response

{
  "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",
  "shadow_banned_at": "2026-01-01T00:00:00.000Z",
  "shadow_banned_until": "string",
  "shadow_banned_reason": "string"
}