Content

Send content to Stream and get a keep, flag, or remove decision. There are two endpoints. Both use the same policies and rules.

Which should I use?

Use Custom Check when your own model already classified the content and you want that result on the dashboard.

Examples below use the server-side SDKs. See the setup guides for Node, Python, Go, Java, PHP, Ruby, or .NET.

Check

Submit text, image URLs, and/or video URLs. Get back one recommended_action (keep, flag, or remove) and a review-queue item you can show on a custom dashboard.

1. Create a policy with engines and actions
2. Call check with your entity ids and config_key
3. Apply recommended_action in your product
4. Review flagged items in the dashboard or via the review queue API

API Usage

$response = $client->moderation()->check(new CheckRequest(
    entityCreatorID: 'entity_creator_id',
    entityID: 'entity_id',
    entityType: 'entity_type',
    moderationPayload: new ModerationPayload(
        texts: ['this is bullshit', 'f*ck you as***le'],
        images: ['example.com/test.jpg'],
    ),
    configKey: 'config_key',
    options: (object)['force_sync' => true],
));

Request Params

Response

Comment context in the review queue

When the entity is a comment, moderators decide faster if they can see what it was posted on and the conversation before it. Send that context in moderation_payload.custom and the dashboard's review queue shows it next to the flagged comment:

• A content card: what the comment was posted on (type, id, title, tags, subtitle, description, link, thumbnail)
• The thread: the top-level comment, the latest earlier replies and the moderated comment, highlighted with its action (Flagged, Removed, Shadow blocked, Blocked)

The format works for any product: a video, a news article, a marketplace listing. The dashboard recognizes it by shape, not by entity_type: a numeric schemaVersion marks it. Without one, custom shows as a plain list of keys and values.

await client.moderation.check({
  entity_type: "comment",
  entity_id: "a_r7",
  entity_creator_id: "driver_dan",
  moderation_payload: {
    texts: ["Cyclists can all go back where they came from"],
    custom: {
      schemaVersion: 1,
      depth: 1,
      content: {
        id: "news-48213",
        type: "article",
        title: "City council approves new bike lanes downtown",
        subtitle: "Local news",
        tags: [
          { key: "section", label: "Section", values: ["Transport"] },
          {
            key: "topics",
            label: "Topics",
            values: ["City council", "Cycling"],
          },
        ],
        description: "The plan adds 12 km of protected lanes over two years...",
        url: "https://example.com/news/bike-lanes",
        imageUrl: "https://example.com/news/bike-lanes.jpg",
      },
      thread: {
        topLevel: {
          id: "a_top",
          user: { id: "cyclist_jen", name: "Jen" },
          text: "Finally. I have been waiting for this for years.",
          createdAt: "2026-10-06T08:12:00Z",
        },
        earlierReplyCount: 7,
        earlierReplies: [
          {
            id: "a_r6",
            user: { id: "driver_dan", name: "Dan" },
            text: "Good luck finding parking now.",
            createdAt: "2026-10-06T08:40:00Z",
          },
        ],
      },
    },
  },
  config_key: "config_key",
});

The moderated comment itself is not part of custom: its text comes from texts and its author from entity_creator_id. Keys inside custom are camelCase.

Every field except schemaVersion is optional, and unknown keys are ignored. A malformed tags value drops only the tags, never the rest of the context.

Analyze

Submit named text fields and get a keep / flag / remove decision per label. Use it when you need a verdict per field instead of one action for the whole entity.

Server-side only. Call analyze the same way as check for named texts. At least one text field or image is required.

Raw image bytes are not in the SDK. Send them with an HTTP multipart/form-data request: one JSON payload part plus image:<label> file parts. That is the only way to attach bytes today.

Modes

Stateful vs stateless. Send entity_type, entity_id, and entity_creator_id together to persist a review-queue row (when content is flagged) and evaluate rules. Omit all three for a stateless call: verdicts only, no queue, no webhooks. config_key is required when stateless. Partial entity fields return 400.

entity_type is yours (listing, external:call). Types that start with stream: are reserved. You may add a subtype for routing (external:call:keyframe); webhooks echo the canonical type (external:call).

Sync vs async. Default is sync: verdicts in the HTTP body. Set async_response: true (stateful only) to get status: "pending" and receive moderation.text_analysis.complete / moderation.image_analysis.complete webhooks instead. Do not send async_response: true without entity fields.

Calling Analyze

$response = $client->moderation()->analyze(new AnalyzeRequest(
    entityCreatorID: 'user_42',
    entityID: 'listing_42',
    entityType: 'listing',
    configKey: 'catalog-v1',
    contentIds: ['caption' => 'cap_42'],
    texts: ['caption' => 'Vintage watch, mint condition'],
));

Image bytes (HTTP only)

client.moderation.analyze sends the JSON fields above. It cannot attach files. To send raw image bytes, POST multipart/form-data yourself (max 10 images, 250 KB each by default, 20 MB for the whole request):

curl -X POST "https://chat.stream-io-api.com/api/v2/moderation/analyze?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt" \
  -F 'payload={"entity_type":"listing","entity_id":"listing_42","entity_creator_id":"user_42","config_key":"catalog-v1","texts":{"caption":"Vintage watch, mint condition"},"content_ids":{"caption":"cap_42","main_photo":"img_42_main"}};type=application/json' \
  -F "image:main_photo=@frame.jpg;type=image/jpeg"

Analyze request

Images: HTTP only. Each file part is named image:<label>. Max 10 images, 250 KB each by default, 20 MB for the whole request. The SDK analyze method does not accept file parts.

Analyze response

Successful calls return 201.

Each text or image field:

{
  "status": "complete",
  "texts": {
    "caption": {
      "id": "cap_42",
      "action": "flag",
      "classifications": [{ "name": "INSULT", "severity": "high" }],
      "severity": "high",
      "language": "en"
    }
  },
  "images": {
    "main_photo": {
      "id": "img_42_main",
      "action": "keep"
    }
  }
}

If some fields fail, status is partial (still 201). Retry only the labels with error. If nothing could be screened, the API returns 503 with a standard error envelope, not this body. Bad input is 400. A missing policy is 422.

Async pending body:

{ "status": "pending", "duration": "112.84ms" }

Wait for Analyze webhook events. A provider error stays on *.complete as field error. moderation.analysis.failed means Stream could not finish the listed content_ids after the pending ack. Treat those ids as unscreened.

Custom Check

Custom Check enables you to submit your own AI moderation results of a chat message/custom uploaded content for review by moderators on the Dashboard.

Add Custom Flags to a Chat Message

Custom Flags can be added to a Chat message. This enables you to submit your own AI moderation results of a chat message for review by moderators on the Dashboard.

$client->moderation()->customCheck(new CustomCheckRequest(
    entityType: 'stream:chat:v1:message',
    entityID: $messageId,
    entityCreatorID: 'user_id',
    flags: [
        new CustomCheckFlag(type: 'custom_check_image', reason: 'Image was NSFW', labels: ['NSFW']),
        new CustomCheckFlag(type: 'custom_check_text', reason: 'Text was harmful', labels: ['harmful']),
        new CustomCheckFlag(type: 'custom_check_video', reason: 'Video contains copyright material', labels: ['copyright-violation']),
    ],
));

Add Custom Check Flags to the Custom Content

The Custom Check endpoint enables you to submit your own AI moderation results for the custom content for review by moderators on the Dashboard.

$client->moderation()->customCheck(new CustomCheckRequest(
    entityType: 'entity_type',
    entityID: 'entity_id',
    entityCreatorID: 'entity_creator_id',
    moderationPayload: new ModerationPayload(texts: ['offensive']),
    flags: [
        new CustomCheckFlag(
            type: 'custom_check_text',
            reason: 'Text was offensive',
            custom: (object)['explaination' => 'custom is a nullable field allowing you to attach a custom object to the flag for your specific use cases or requirements'],
        ),
    ],
));

Request Params

Response

Related APIs

• Policies to configure engines and actions
• Rules for aggregation and automated actions
• Review Queue to inspect flagged items
• Flag, Mute & Ban
• Webhooks
• Appeals
• Logs & Analytics