Social API reference

Social API · Flags

post/v1/communities/{community_id}/flagsAuth

File a moderation report against a post or comment. Idempotent per (reporter, target) while open.

Path parameters

community_id*string

Social community UUID. Must belong to the PAK's workspace.

Headers

Idempotency-Keystring

Opaque client-generated string (1-256 chars, `[A-Za-z0-9._:-]`) that makes a retry safe: within 24 h a repeat with the same key and body returns the original response with `Idempotent-Replay: true` instead of running again. Same key with a different body is `409 IDEMPOTENCY_KEY_REUSE`.

Request body

actor_idstring · uuid

The acting actor, who is reporting the content. Send it, or the deprecated `reporter_actor_id`; one of the two is required.

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

reporter_actor_idstring · uuid

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

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

target_kind*enum (4)

What kind of object is being flagged (task 017 adds actor + direct_message). A direct_message flag requires the reporter to be a participant in the conversation.

Example: "post"

target_id*string · uuid

UUID of the target (post / comment / actor / message id per target_kind).

Example: "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"

reasonstring

Optional free-form reason (up to 1000 chars).

Example: "Spam — same link posted 6 times in 5 minutes."

Response · 201 Flag created (or de-duplicated to existing open flag). `auto_hidden` reports whether the auto-hide threshold tripped.

flag*object

The flag row (existing open flag on de-duplicated retry).

created*boolean

`true` when this call inserted a new flag; `false` when de-duplicated to an existing open flag from the same reporter on the same target.

Example: true

auto_hidden*boolean

`true` when this flag pushed the target over the community's `auto_hide_flag_threshold` and the target was auto-hidden as a side effect.

Example: false

Example

Request

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

{
  "actor_id": "aaaaaaaa-0000-0000-0000-000000000001",
  "reporter_actor_id": "aaaaaaaa-0000-0000-0000-000000000001",
  "target_kind": "post",
  "target_id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
  "reason": "Spam — same link posted 6 times in 5 minutes."
}

Response

{
  "flag": {},
  "created": true,
  "auto_hidden": false
}