How Infrared works

Every call to POST /v1/moderations goes through the same stages, whether it carries one comment or a listing with ten photos. Knowing them tells you why a response reads the way it does, what a request costs and where to look when a result surprises you.

The sample below is one field of a listing, sent with your id for the listing and for the person who wrote it, to a template called listing. Templates are part of Starter and up. Without template the same stages run on the built-in basic check, on every plan.

curl https://api.useinfrared.com/v1/moderations \
  -H "Authorization: Bearer $INFRARED_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "listing",
    "type": "text",
    "field": "description",
    "input": "Solid oak, minor marks on one leg. Order direct at https://shop.example.com/oak or call +44 7700 900123",
    "content_id": "listing_18342",
    "author_id": "user_42"
  }'

const response = await fetch("https://api.useinfrared.com/v1/moderations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INFRARED_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    template: "listing",
    type: "text",
    field: "description",
    input: "Solid oak, minor marks on one leg. Order direct at https://shop.example.com/oak or call +44 7700 900123",
    content_id: "listing_18342",
    author_id: "user_42",
  }),
});

const moderation = await response.json();

import os
import requests

response = requests.post(
    "https://api.useinfrared.com/v1/moderations",
    headers={"Authorization": f"Bearer {os.environ['INFRARED_KEY']}"},
    json={
        "template": "listing",
        "type": "text",
        "field": "description",
        "input": "Solid oak, minor marks on one leg. Order direct at https://shop.example.com/oak or call +44 7700 900123",
        "content_id": "listing_18342",
        "author_id": "user_42",
    },
)

moderation = response.json()

The request came back FLAGGED with the recommendation review. Moderate text shows the response; the sections below say what each stage did to get there.

Admission

The API key names the project. The request is counted against the key's rate limit, its body is checked against the schema, and the template is chosen: the one the request names, else the project's default template, else the basic check.

A request that stops here is an HTTP error and leaves nothing behind: 401 for the key, 429 for the rate limit, 422 for the body, 403, 404 or 409 for the template. Statuses and errors lists each one.

Validation

The submission is checked against the template's fields: required values, lengths, formats, the number of files. No model is called and no check is used.

A submission that fails is not an HTTP error. The API answers 200 with a moderation whose status is invalid and whose recommendation is reject, and validation_errors holds one entry per problem.

Screening

Each text is normalised first. Invisible characters are removed, Unicode forms are unified and lookalike letters are folded back to the alphabet of their word, so Gοοgle written with Greek letters is read as Google. The language is detected on the way.

Then the policies the template enables score the content. They come in two kinds:

• Pattern and list policies need no model: personal data, links and contact details, lookalike characters, your wordlists, duplicates and a lexicon of swear words.
• Model policies are scored together. One call per text covers every model-backed policy at once. One call per image scores the picture and reads the text in it. One call per submission judges the template's AI instructions and your guidelines across all fields.

Identical content on the same template version reuses its scores for six hours. The response says so with usage.cached, and the decision is still made again, because the author or your rules may have changed.

A policy that does not answer does not fail the request. The moderation ends with status: "partial" and the decision is made on the policies that did answer.

Decision

Scores become a verdict and a recommendation in a fixed order. Triggers set flagged. The highest weighted score sets severity. Your content rules are checked top to bottom and the first match decides. When no rule matches, severity triage turns the severity into allow, review or reject.

The decision reads only the scores, the template version, the author and the request, so the same input always gives the same result. reasons in the response records the path it took. How a decision is made follows one moderation through every step.

After the answer

Once the decision is stored, the rest follows from it:

• The checks the moderation used are taken from the organisation's monthly checks, then from its extra checks.
• When the request carried author_id, that author's history is updated, and their trust level with it. A test key and a dry run leave it alone.
• A review recommendation puts the item in the review queue.
• A moderation.completed event goes to your webhook endpoints.
• The moderation appears in the Live console.

Infrared never publishes or removes anything in your product. Your backend acts on the recommendation.

What uses a check

A check is the unit your plan counts. One moderation uses at least one, and the cost is known before any model runs.

So a text costs one check and a single image costs two: one for the object and one for the picture. usage.checks in every response is what that moderation used. Checks covers the monthly allowance and extra checks.

Text waits, images do not

Text is screened while the request waits and the response is the finished moderation. A request that carries an image answers 202 with status: "screening", and the result arrives by webhook or by polling. Sync and async shows both, and how to choose.

Next

• Moderate textSend a comment, a review, a message or one field of a form as text. The verdict comes back in the same response, with a score for every policy.
• How a decision is madeTriggers set the verdict, severity ranks the content, your content rules decide first and triage decides the rest. reasons records the path taken.
• Sync and asyncText is answered in the same response and images are queued. Choose with mode, then read a queued result from a webhook event or by polling.
• Checks and usageA check is the unit every plan counts. See what one moderation costs, when the monthly allowance resets and how to read your usage over the API.