/v1/workspaces/{workspace_id}/communitiesAuthCreate an social community. `app_id` is optional — when supplied Social connects the community to an Auth app and refuses if the app belongs to a different workspace (cross-tenant gate) or is already connected. Omit `app_id` for a standalone community (no Auth integration; the customer manages actor identity). Pass an `Idempotency-Key` header to make retries safe.
Path parameters
workspace_id*stringProductCraft workspace UUID owning the community.
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
app_idstring · uuidOptional Auth App UUID this community wraps. When supplied, the app must be owned by the calling workspace (cross-tenant gate). Omit to create a standalone community with no Auth integration — actor identity is then managed entirely by the customer.
Example: "33333333-3333-3333-3333-333333333333"
slug*stringURL-friendly community slug. Lowercase letters, digits, and hyphens (3-64 chars).
Example: "my-product-community"
display_name*stringDisplay name shown in the console and on responses.
Example: "My Product Community"
descriptionstringOptional human-readable description (up to 500 chars).
Example: "Where our customers post stories and threads."
settingsobjectPer-community settings blob. Supported keys are typed on CommunitySettingsDto; unrecognized keys are stored verbatim but not consumed.
Response · 201 Community created.
id*string · uuidCommunity UUID.
Example: "cccccccc-cccc-cccc-cccc-cccccccccccc"
workspace_id*string · uuidOwning workspace UUID.
Example: "11111111-1111-1111-1111-111111111111"
app_id*string · uuidAuth app UUID this community wraps; `null` for standalone communities.
Example: "33333333-3333-3333-3333-333333333333"
slug*stringURL-friendly community slug.
Example: "my-product-community"
display_name*stringDisplay name.
Example: "My Product Community"
description*stringOptional human-readable description.
Example: null
settings*objectPer-community settings: every key the service reads, with its default when it was never set. Unrecognized keys you stored are returned unchanged but not consumed.
Example: {"max_comment_depth":3}
status*objectLifecycle status.
Example: "active"
created_by*stringAccount UUID of the creator.
Example: "aaaaaaaa-0000-0000-0000-000000000001"
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"
Example
Request
POST https://social.productcraft.co/v1/workspaces/{workspace_id}/communities
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"app_id": "33333333-3333-3333-3333-333333333333",
"slug": "my-product-community",
"display_name": "My Product Community",
"description": "Where our customers post stories and threads.",
"settings": {}
}Response
{
"id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
"workspace_id": "11111111-1111-1111-1111-111111111111",
"app_id": "33333333-3333-3333-3333-333333333333",
"slug": "my-product-community",
"display_name": "My Product Community",
"description": null,
"settings": {
"max_comment_depth": 3
},
"status": "active",
"created_by": "aaaaaaaa-0000-0000-0000-000000000001",
"created_at": "2026-05-01T12:00:00.000Z",
"updated_at": "2026-05-01T12:00:00.000Z"
}