Content

Send text, images, video, or audio to Stream, and Stream checks it against your policy and returns keep, flag, or remove. If your own model already classified the content, send its results instead so moderators can review them in the review queue.

Which API should I use?

Four endpoints accept content. Pick the one that matches what you want back.

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

Stream polls (in Chat and Feeds) don't need an API call: their text is moderated automatically with a polls policy. See Polls.

Check

Submit text, image URLs, video, and audio. 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

CheckResponse response = client.moderation()
    .check(CheckRequest.builder()
        .entityType("entity_type")
        .entityID("entity_id")
        .entityCreatorID("entity_creator_id")
        .moderationPayload(ModerationPayload.builder()
            .texts(List.of("this is bullshit", "f*ck you as***le"))
            .images(List.of("example.com/test.jpg"))
            .build())
        .configKey("config_key")
        .build())
    .execute()
    .getData();

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.

This section covers what moderators see. To let the AI Text (LLM) engine read the same data when it decides on the comment, list the keys in the policy's llm_config; see Context from custom data.

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

AnalyzeResponse response = client.moderation()
    .analyze(AnalyzeRequest.builder()
        .entityType("listing")
        .entityID("listing_42")
        .entityCreatorID("user_42")
        .configKey("catalog-v1")
        .contentIds(Map.of("caption", "cap_42"))
        .texts(Map.of("caption", "Vintage watch, mint condition"))
        .build())
    .execute()
    .getData();

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 lets you submit results from your own AI model, for a Stream Chat message or your own content, so moderators can review them in 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(CustomCheckRequest.builder()
        .entityType("stream:chat:v1:message")
        .entityID(messageId)
        .entityCreatorID("user_id")
        .flags(List.of(
            CustomCheckFlag.builder().type("custom_check_image").reason("Image was NSFW").labels(List.of("NSFW")).build(),
            CustomCheckFlag.builder().type("custom_check_text").reason("Text was harmful").labels(List.of("harmful")).build(),
            CustomCheckFlag.builder().type("custom_check_video").reason("Video contains copyright material").labels(List.of("copyright-violation")).build()
        ))
        .build())
    .execute();

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(CustomCheckRequest.builder()
        .entityType("entity_type")
        .entityID("entity_id")
        .entityCreatorID("entity_creator_id")
        .moderationPayload(ModerationPayload.builder()
            .texts(List.of("offensive"))
            .build())
        .flags(List.of(
            CustomCheckFlag.builder()
                .type("custom_check_text")
                .reason("Text was offensive")
                .custom(Map.of("explaination", "custom is a nullable field allowing you to attach a custom object to the flag for your specific use cases or requirements"))
                .build()
        ))
        .build())
    .execute();

Request Params

Response

Polls

Stream moderates the text of polls as users write it: the question, the description, the options, options suggested by other users, and free-text answers. Set up a polls policy and poll writes that carry text are checked before they are stored, with no extra API calls from your app.

What gets moderated

Votes on an option carry no text and are not moderated. An update that leaves every text unchanged (for example, closing the poll) is not checked either. A partial update is checked on the texts that will actually be stored.

Each review queue item is filed under the user who made the write: the poll's creator for a create, the user who made an update, the suggesting user for a suggested option, and the voter for an answer. One user has one open item per poll. A later write by that same user updates the item and replaces its payload, including poll_operation. A different user gets a separate item.

Set up a polls policy

1. Navigate to the Stream Dashboard.
2. Go to Moderation → Policies and create a policy with the Polls type.
3. Leave the name as default to create polls:default, which applies to every poll write in the app. A named policy (polls:<name>) applies only where your server passes its key (see Use a different policy from your server).
4. Add the engines you want: AI text, LLM text, blocklists, regex filters and allowlists. A polls policy does not include image, video, audio or flooding.

Without a polls policy, poll writes are not moderated.

Actions

A polls policy maps each rule to one of two actions:

shadow, mask and mask_flag are treated as flag: the write is stored and a review item is opened. bounce, bounce_flag and bounce_remove reject the write the same way remove does, but a bounce does not open a review item. Any other action leaves the write stored.

Only that remove verdict rejects the write. If the check cannot be completed, the write is stored.

Handling a removed write

A removed write fails with HTTP status 400 and error code 73, so your app can tell the user their poll, option or answer was not accepted:

{
  "code": 73,
  "message": "poll moderation failed: content blocked",
  "StatusCode": 400
}

For server-side requests, the error's details also names what matched: action, text_harms (AI and LLM labels) and blocklists_matched. Client-side requests never receive those details.

Users with bypass_moderation set are never checked. When a polls policy applies, each text is limited to 10,000 characters. A longer text is rejected with an input error and is not checked.

Use a different policy from your server

Server-side requests can pass config_key (and config_team) on any poll write to use a named policy instead of polls:default, for example polls:kids-mode. A config_key that does not exist is rejected. The write is not checked against polls:default instead. Client-side requests cannot choose a policy: the field is ignored, so users cannot opt themselves out of polls:default.

Review poll content

Poll items appear in the review queue like any other content. The dashboard shows the live poll, marks the flagged question, description, option or answer, and shows a removed write on its own, because that text was never stored. A poll attached to a chat message is shown with that message. A poll on a feed, or one that was never posted, is shown by itself.

Each poll moderation check records what the write was and, for option writes, which option, under moderation_payload.custom:

moderation_payload.text_ordered_keys labels each entry of moderation_payload.texts as name, description, option or answer.

Actions on poll items

All three deletes are permanent: poll content cannot be restored. Moderators can also mark poll items reviewed, ban the user who wrote the content, or escalate the item.

delete_poll_option and delete_poll_answer refuse when the stored content no longer holds the text that was checked. A removed edit leaves the original option or answer in place, and that original is not deleted. An answer also cannot be deleted once its poll is closed, or when the poll is not on a chat message.

See Actions for how to submit them.