Management API

The management API lets you set up projects and channels from your own code instead of the dashboard. Use it when you run moderation for many products or customers and set up the same configuration again and again. You call it with an organization key. An organization key manages projects and channels across your organization, and can call every other endpoint for a project you name. See Call project endpoints and Authentication. The management API is available on every plan.

Prerequisites

The Admin or Owner role in your organization. Only these roles can create organization keys.

Project limit

Your plan sets how many projects your organization can have: self-serve plans include 2, Enterprise plans 25. Your limit shows in Settings → Usage. Creating or duplicating a project beyond it returns 403 with the code plan_limit_exceeded. Delete a project you no longer need, or contact support@moderationapi.com for more.

Create an organization key

Open API keys

In the dashboard, go to Settings → API keys and click Create key.

Choose its access

Name: a label so you can recognize the key, for example the tool that uses it.
Permissions: pick None, Read, or Write for projects and for channels. Write includes read.
Projects: leave empty to reach every project, or pick the projects the key can reach.
Expires: Never, 30 days, 90 days, or 365 days.

Copy the key

Copy the key and store it in a secret manager. You can’t see it again after you close the dialog.

Organization keys start with sk_org_, so you and secret scanners can tell them apart from project keys.

Permissions

Each endpoint needs one permission on the key:

Permission	Endpoints
`projects:read`	List projects, get a project
`projects:write`	Create, update, duplicate, and delete a project, and create an API key for a project
`channels:read`	List channels, get a channel
`channels:write`	Create, update, duplicate, and delete a channel

An organization key can also call Get account details, so you can check that the key works.

Call project endpoints

An organization key can call the endpoints of any project it reaches: submit content, list authors, work a review queue, and so on. Name the project in the Project-Id header, by its ID or by its name. In the SDKs and the CLI this is the projectId parameter. If your organization has one project, you can leave it out.

curl https://api.moderationapi.com/v1/authors \
  -H "Authorization: Bearer $MODAPI_ORGANIZATION_KEY" \
  -H "Project-Id: $PROJECT_ID"

Reading needs projects:read on the key, and changing anything (submitting content included) needs projects:write. A project key always acts on its own project: naming another project with it returns 403. A name matches regardless of case. When more than one project the key reaches has that name, the request returns 400 with project_name_ambiguous and lists the matching projects: name the project by its ID instead.

Keys limited to some projects

A key limited to some projects only sees those projects and their channels. Other projects return 404 Not Found. A limited key can’t create or duplicate projects, because the new project would fall outside its limit. Use a key that reaches every project for that.

Example: set up a new project

Create a project. The response includes the new project’s secretKey, which you use to moderate content in that project. The other project endpoints don’t return it. You can also find it in the dashboard under Project → Configure → API keys.

curl -X POST https://api.moderationapi.com/v1/projects \
  -H "Authorization: Bearer $MODERATION_ORG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Marketplace",
    "domain": "acme.example"
  }'

Every new project comes with one channel, a review queue, and a secret key. When you give a domain or context, the project suggests policies for the platform. Add a channel for another surface of your product:

curl -X POST https://api.moderationapi.com/v1/projects/PROJECT_ID/channels \
  -H "Authorization: Bearer $MODERATION_ORG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Reviews",
    "key": "reviews",
    "contentType": "review"
  }'

Then moderate content with the project’s secret key, and pass the channel’s key as channel:

curl -X POST https://api.moderationapi.com/v1/moderate \
  -H "Authorization: Bearer $PROJECT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": { "type": "text", "text": "Great seller, fast shipping!" },
    "channel": "reviews"
  }'

Copy a setup

To reuse a configuration you already tuned, duplicate it instead of building it again:

Duplicate a project copies its settings, every channel with its policies, rules and wordlists, its moderation actions, and its review queues. The copy gets its own secret key. Webhooks, integrations, API keys, and content aren’t copied.
Duplicate a channel copies a channel inside its project with every setting, policy, rule, and wordlist. Use it to try a change next to the original. Integrations aren’t copied.

The channel endpoints change channel settings such as content type, flagging mode, and media settings. To change a channel’s policies and rules, use the dashboard, or duplicate a channel that already has them.

Roll a key

To replace a key without downtime, open the key’s menu in Settings → API keys and click Roll key. The new key has the same access and lifetime as the old one. Choose when the old key stops working: Now, 1 hour, 24 hours, or 7 days. The old key never outlives its own expiry date. To revoke a key at once, click Delete.

Activity and audit

Each key shows when it was last used. Every change made with an organization key shows in Settings → Activity, with the key that made it.

Rate limits

The management API allows 60 requests per minute per organization, separate from your moderation rate limit. When you create many projects in a script, handle 429 responses and retry after the time in the Retry-After header.

Errors

Status	`code`	Reason
`401`	`missing_api_key`, `invalid_api_key`	The key is missing, invalid, or expired.
`403`	`organization_key_required`	The key is a project key.
`403`	`missing_key_permission`	The key doesn’t have the permission the endpoint needs.
`403`	`project_not_reachable`	The key is limited to other projects.
`403`	`plan_limit_exceeded`	Creating the project would go over your plan’s project limit.
`400`	`project_id_required`	A project endpoint was called without `Project-Id`, and the organization has more than one project.
`400`	`project_name_ambiguous`	More than one project the key reaches has the name in `Project-Id`. Use the project’s ID.
`404`	`project_not_found`, `channel_not_found`	The project or channel doesn’t exist, or it’s outside the key’s project limit.
`429`	`rate_limit_exceeded`	Too many requests. See Rate limits.

See Errors for the response format and all codes.

API

Account

Moderate

Authors

Actions

Wordlist

Review Queue

Projects

Channels

Webhooks

Analytics

Feedback

Prerequisites

Project limit

Create an organization key

Permissions

Call project endpoints

Keys limited to some projects

Example: set up a new project

Copy a setup

Roll a key

Activity and audit

Rate limits

Errors

​Prerequisites

​Project limit

​Create an organization key

​Permissions

​Call project endpoints

​Keys limited to some projects

​Example: set up a new project

​Copy a setup

​Roll a key

​Activity and audit

​Rate limits

​Errors

Prerequisites

Project limit

Create an organization key

Permissions

Call project endpoints

Keys limited to some projects

Example: set up a new project

Copy a setup

Roll a key

Activity and audit

Rate limits

Errors