Social API reference

Social API · Communities

post/v1/workspaces/{workspace_id}/communitiesAuth

Create 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*string

ProductCraft workspace UUID owning the community.

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

app_idstring · uuid

Optional 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*string

URL-friendly community slug. Lowercase letters, digits, and hyphens (3-64 chars).

Example: "my-product-community"

display_name*string

Display name shown in the console and on responses.

Example: "My Product Community"

descriptionstring

Optional human-readable description (up to 500 chars).

Example: "Where our customers post stories and threads."

settingsobject

Per-community settings blob. Supported keys are typed on CommunitySettingsDto; unrecognized keys are stored verbatim but not consumed.

Response · 201 Community created.

id*string · uuid

Community UUID.

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

workspace_id*string · uuid

Owning workspace UUID.

Example: "11111111-1111-1111-1111-111111111111"

app_id*string · uuid

Auth app UUID this community wraps; `null` for standalone communities.

Example: "33333333-3333-3333-3333-333333333333"

slug*string

URL-friendly community slug.

Example: "my-product-community"

display_name*string

Display name.

Example: "My Product Community"

description*string

Optional human-readable description.

Example: null

settings*object

Per-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*object

Lifecycle status.

Example: "active"

created_by*string

Account UUID of the creator.

Example: "aaaaaaaa-0000-0000-0000-000000000001"

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"

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"
}