/v1/workspaces/{workspace_id}/communities/{community_id}/moderation/actors/{actor_id}/shadow-banAuthApply 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 · uuidId of the workspace.
community_id*string · uuidId of the community.
actor_id*string · uuidId of the actor.
Headers
Idempotency-KeystringOpaque 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_hoursnumberHours until auto-restore. Omit for indefinite.
Example: 168
reasonstringModerator note (1..1000 chars).
Response · 200 Shadow ban applied.
id*string · uuidSocial actor UUID.
Example: "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
community_id*string · uuidOwning 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*objectLifecycle 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*booleanWhen 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-timeISO timestamp the row was inserted.
Example: "2026-05-01T12:00:00.000Z"
updated_at*string · date-timeISO timestamp of the last update.
Example: "2026-05-01T12:00:00.000Z"
shadow_banned_at*string · date-timeISO timestamp the shadow ban was applied, or null.
shadow_banned_until*stringISO timestamp the shadow ban auto-expires, or null for indefinite.
shadow_banned_reason*stringModerator 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"
}