Going live

A first request proves the call works. Production needs a few more decisions: what your product does with each answer, what it does when there is no answer, and who reads the review queue. Work down this page once before real users depend on the result.

Keys and access

• Use a live key in production and a test key everywhere else. A test key runs the same pipeline and uses no checks, but its moderations still reach the review queue and your webhooks.
• Keep keys on your server. A key can read and change a project. Nothing in the API is meant to be called from a browser or a mobile app.
• Give a key only the scopes it needs. The upload flow needs moderate. Add read if it polls for results, since a key with moderate alone cannot fetch a moderation. See API keys.
• Rotate by replacing. Create the new key, deploy it, then revoke the old one. A revoked key stops working at once.

The request

• Name a published template, or set the project's default template, so your own rules run. A request that names none falls back to the basic check.
• Send author_id and content_id with every request. The first gives each author a history your rules can use; the second lets you find a moderation by your own id. See Authors, content ids and metadata.
• Send an Idempotency-Key on every moderation you create, so a retry after a timeout cannot screen and charge the same content twice. See Idempotency.

Answers that arrive later

• Images are asynchronous. A request with an image answers 202 with status: "screening", and the result follows. Either add a webhook endpoint and wait for moderation.completed, or poll the moderation. See Sync and async.
• Verify every webhook with the endpoint's secret before trusting it, and answer within the timeout. See Verify signatures.
• Handle an event more than once. A delivery is retried after a 5xx, a timeout or a network error, so the same event can arrive twice. A 4xx other than 408 and 429 is final and is not retried. See Deliveries, retries and replay.

When something goes wrong

Decide each of these in code before it happens in production.

Statuses and failures lists every case, and Errors every code.

Rollout

• Start in dry run. Turn it on for the project and send real traffic: everything is scored and the review queue fills, while your product keeps publishing as before. A dry run still uses checks. See Dry run and re-moderation.
• Read a week of results in the Live console before enforcing anything. Thresholds and rules that looked right on five samples rarely survive five thousand.
• Simulate before you publish a rule change. A simulation replays the last seven days of decisions against the draft and counts what would move.
• Then enforce. Turn dry run off and let your code act on recommendation.

The people

• Invite the moderators who will work the queue, with the Moderator role on the project. See Members and roles.
• Decide who answers within what time. A template can set how long an item may wait before the queue shows it as overdue. See Review queue.
• Wire the decisions back. A moderator's allow or reject reaches your product as a webhook; nothing is published or removed until your backend acts on it. See Event types.

The data

• Set the retention for the project, within what the plan allows, and send store: false for content that must not be kept. See Data retention and privacy.

Next

• Test modeA test key runs the whole pipeline and uses no checks. It is not a sandbox: its moderations still reach the review queue and your webhooks.
• WebhooksInfrared posts a signed event to your endpoint when a moderation finishes, a queue item is decided or an author changes. Add an endpoint and receive it.
• Statuses and errorsThe five statuses a moderation can have and every error the moderation endpoints return, with the HTTP status, the code and what to do next.
• Review queueContent your rules send to review waits in the queue until a person, or your own code, allows it, rejects it or runs another action on it.