Content moderation with the CLI

Prerequisites

You'll need an API key to use the Moderation API. To get one, you'll need to create a project.

Create a project

1. Install the CLI

curl -fsSL https://raw.githubusercontent.com/moderation-api/cli/main/scripts/install.sh | bash

iwr -useb https://raw.githubusercontent.com/moderation-api/cli/main/scripts/install.ps1 | iex

go install github.com/moderation-api/cli/cmd/modapi@latest

You can also download a binary for your platform from the releases page.

2. Set your API key

Grab the API key from your project and set it in the MODAPI_SECRET_KEY environment variable:

export MODAPI_SECRET_KEY="your-project-key"

On your own computer, you can run modapi configure instead. It stores the key in your operating system’s keychain.

3. Submit content

Use modapi content submit to moderate text, images, video, audio, or objects with several fields. Only --content is required.

modapi content submit \
  --content '{"type":"text","text":"Hello world!"}' \
  --content-id message-123 \
  --author-id user-123 \
  --conversation-id room-456 \
  --metadata '{"customField":"value"}'

modapi content submit \
  --content '{"type":"image","url":"https://example.com/image.jpg"}' \
  --content-id image-456 \
  --author-id user-123

modapi content submit \
  --content '{"type":"object","data":{"title":{"type":"text","text":"Post title"},"body":{"type":"text","text":"Post content"},"thumbnail":{"type":"image","url":"https://example.com/thumb.jpg"}}}' \
  --content-id post-789 \
  --author-id user-123

4. Use the result

Use --jq to read one field of the result. For example, get the recommended action (allow, review or reject). Add --raw-output to print the value as plain text:

action=$(modapi content submit \
  --content '{"type":"text","text":"Hello world!"}' \
  --jq '.recommendation.action' --raw-output)

if [ "$action" = "reject" ]; then
  echo "Content rejected"
fi

For the full result as JSON, use --output-format json.

5. Preview a request

Add --dry-run to any command to see the request it would send. The CLI does not send the request, so it does not use your quota:

modapi content submit --content '{"type":"text","text":"Hello world!"}' --dry-run

6. Explore other commands

The CLI has a command for each API endpoint. Some examples:

# List authors
modapi authors list

# Get every page of moderation actions as JSON, one item per line
modapi actions list --all --output-format json

# Get the webhook signing secret
modapi webhook-secret retrieve

# Show all commands, or the flags of one command
modapi --help
modapi content submit --help

If a command fails, it exits with a code that is not 0: 1 for API errors, 2 for usage errors and 3 for authentication errors.

Organization key

Commands for projects and channels (modapi projects and modapi channels) use the management API and need an organization key. To run them while MODAPI_SECRET_KEY holds your project key, pass the organization key with --secret-key:

modapi projects list --secret-key "$MODAPI_ORGANIZATION_KEY"

An organization key can also run the other commands for a project: name it with --project-id.

modapi authors list --secret-key "$MODAPI_ORGANIZATION_KEY" --project-id "$PROJECT_ID"

Dry-run mode: If you want to analyze production data but don't want to block content, enable "dry-run" in your project settings.

With dry-run enabled, the API still analyzes content but it always returns flagged: false - yet content still shows in the review queue. This way you can implement your moderation workflows and start testing your project configuration without actually blocking content.

3. Review flagged content (optional)

If the AI flags the content, it will appear in the Review inbox. Head to the review queue to validate that the content is submitted correctly.

Review queue for reviewing and improving automated moderation

You can use review queues to implement moderation workflows or simply check how the AI is performing.

All Done!

Congratulations! You've run your first moderation checks. Here are a few next steps:

Continue tweaking your project settings and models to find the best moderation outcomes.
Add custom Guidelines to a channel for rules specific to your platform.
Explore advanced features like context-aware moderation.
If you have questions, reach out to our support team.

We love hearing from you—please share how you're using the service and let us know if you have suggestions or need help. Happy moderating!

Documentation

Learn

Migrations

Resources

Content moderation with the CLI

Prerequisites

1. Install the CLI

2. Set your API key

3. Submit content

4. Use the result

5. Preview a request

6. Explore other commands

Organization key

3. Review flagged content (optional)

All Done!

​Prerequisites

​1. Install the CLI

​2. Set your API key

​3. Submit content

​4. Use the result

​5. Preview a request

​6. Explore other commands

​Organization key

​3. Review flagged content (optional)

​All Done!

Prerequisites

1. Install the CLI

2. Set your API key

3. Submit content

4. Use the result

5. Preview a request

6. Explore other commands

Organization key

3. Review flagged content (optional)

All Done!