Social API reference

Social API · Lists

post/v1/communities/{community_id}/listsAuth

Create a new list. Default visibility `private`. List creation has no natural key (an owner can hold many same-named lists), so pass an `Idempotency-Key` header to make retries safe.

Path parameters

community_id*string

Social community UUID.

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

actor_idstring · uuid

The acting actor, who owns the new list. Send it, or the deprecated `owner_id`; one of the two is required.

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

owner_idstring · uuid

Deprecated alias of `actor_id`; send `actor_id`.

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

name*string

Display name (1..200).

Example: "Tech news"

descriptionstring

Optional description (0..2000).

visibilityenum (2)

Default `private`.

Example: "public"

Response · 201 List created.

id*string · uuid

List UUID.

Example: "11111111-0000-0000-0000-000000000001"

community_id*string · uuid

Owning community UUID.

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

owner_id*string · uuid

List owner — social actor UUID.

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

name*string

List display name.

Example: "Tech news"

description*string

Optional description.

Example: "Curated tech accounts I follow."

visibility*object

public = discoverable; private = owner-only.

Example: "public"

member_count*number

Current member count.

Example: 12

created_at*string · date-time

ISO timestamp.

Example: "2026-05-01T12:00:00.000Z"

updated_at*string · date-time

ISO timestamp.

Example: "2026-05-01T12:00:00.000Z"

Example

Request

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

{
  "actor_id": "aaaaaaaa-0000-0000-0000-000000000001",
  "owner_id": "aaaaaaaa-0000-0000-0000-000000000001",
  "name": "Tech news",
  "description": "string",
  "visibility": "public"
}

Response

{
  "id": "11111111-0000-0000-0000-000000000001",
  "community_id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
  "owner_id": "aaaaaaaa-0000-0000-0000-000000000001",
  "name": "Tech news",
  "description": "Curated tech accounts I follow.",
  "visibility": "public",
  "member_count": 12,
  "created_at": "2026-05-01T12:00:00.000Z",
  "updated_at": "2026-05-01T12:00:00.000Z"
}