API reference

The Infrared API is a REST API over HTTPS. Your backend sends JSON and reads JSON, and every request carries an API key. The key belongs to one project, so no request names a project.

curl "https://api.useinfrared.com/v1/moderations?limit=1" \
  -H "Authorization: Bearer $INFRARED_KEY"

const response = await fetch("https://api.useinfrared.com/v1/moderations?limit=1", {
  headers: { Authorization: `Bearer ${process.env.INFRARED_KEY}` },
});

const moderations = await response.json();

import os
import requests

response = requests.get(
    "https://api.useinfrared.com/v1/moderations",
    headers={"Authorization": f"Bearer {os.environ['INFRARED_KEY']}"},
    params={
        "limit": 1,
    },
)

moderations = response.json()

HTTP/1.1 200 OKContent-Type: application/json; charset=utf-8X-Request-Id: req_8f23a234498f4560a0e6e515f5ded444X-RateLimit-Limit: 1500X-RateLimit-Remaining: 1499X-RateLimit-Reset: 1791450240 {"object": "list","data": [{ "object": "moderation", "id": "mod_61V1nbIiKuuJTgeKT1eViM", "status": "completed", "recommendation": "allow" }],"has_more": true,"next_cursor": "WyIyMDI2LTEwLTA4VDA5OjAyOjM2LjU5MloiLCJjNWVmYjFiZi1jZGE1LTRlN2YtOTQwMy01MDM4ODBkMDc4NmEiXQ"}

Every endpoint follows the same rules for keys, errors, lists, retries and limits. The endpoints themselves are listed under Resources, each with its parameters, its object and a request you can copy.

Base URL and versions

Every endpoint lives under one address:

https://api.useinfrared.com/v1

The version is in the path, and /v1 is the only one. No header selects a version.

Webhook events carry a second marker, api_version, a date that names the shape of the payload. It is 2026-09-01 today and appears in every event, in the Infrared-Api-Version header of a delivery and on each endpoint object.

Requests

• JSON in UTF-8. Send a body with Content-Type: application/json. Field names are snake_case.
• A body of 2 MB at most. A larger one answers 413 payload_too_large. Images are sent as URLs, never inline.
• Bodies are strict. A field the endpoint does not know answers 422 validation_error and names the field. Query parameters it does not know are ignored.
• From a server. The API sends no CORS headers, so a browser cannot call it. A key can read and change a project: keep it on your backend.

A body in another character set, or with a Content-Encoding the API cannot read, answers 500 today. Send plain UTF-8.

Responses

A successful response is the resource itself, with no wrapper. Every object says what it is in object and carries its id.

A field with no value is null. A few optional fields are left out when they do not apply, such as test on a moderation made with a live key.

Ids

An id is a prefix, an underscore and 22 letters and digits: mod_61V1nbIiKuuJTgeKT1eViM. The prefix names the type, and an id of one type is refused where another is expected.

Three things are addressed by a name of yours instead: an author by the id you use for them (/v1/authors/user_8841), a template by its slug and an action by its key.

An id that is malformed or unknown answers 404 not_found in a path and 422 validation_error in a body. An id from another project answers 404 too, so ids cannot be probed.

Timestamps

Times are ISO 8601 in UTC with milliseconds, ending in Z: 2026-10-08T09:02:36.592Z. A time you send, such as the created_from filter of a list or the until of a suspension, takes the same form.

Three values are numbers of seconds instead: X-RateLimit-Reset and the t of a webhook signature count from the Unix epoch, and Retry-After is a wait.

Request ids

Every response carries an X-Request-Id header, and every error repeats it as error.request_id. Quote it when you ask for help with a request.

Send your own id in the same header and Infrared uses it, so one id follows a request through your logs and ours. It can be 1 to 64 characters from letters, digits, ., _ and -. Any other value is replaced by a generated one, without an error.

Resources

Next

• AuthenticationSend an API key as a bearer token on every request. The key names the project, its scopes decide which endpoints it may call, and a bad key answers 401.
• ErrorsEvery error has one JSON shape. Branch on its code, show its details and quote its request id. The table lists each code the API returns and when.
• PaginationA list returns one page and says whether more follow. Send the cursor of one page to get the next, and stop when has_more is false.
• Rate limitsEach API key may send a set number of requests a minute, by plan. Every response says where the key stands, and a 429 says how long to wait.