Create a wordlist

POST/v1/wordlistsKey scope write

Creates an empty wordlist. Add terms with POST /v1/wordlists/{id}/terms; the list scores nothing until a template enables its policy, wordlist/<slug>, in the dashboard.

Needs a key with the write scope. Authentication

curl https://api.useinfrared.com/v1/wordlists \
  -H "Authorization: Bearer $INFRARED_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Restricted items",
    "mode": "block",
    "match_preset": "similar"
  }'

const response = await fetch("https://api.useinfrared.com/v1/wordlists", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INFRARED_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Restricted items",
    mode: "block",
    match_preset: "similar",
  }),
});

const data = await response.json();

import os
import requests

response = requests.post(
    "https://api.useinfrared.com/v1/wordlists",
    headers={"Authorization": f"Bearer {os.environ['INFRARED_KEY']}"},
    json={
        "name": "Restricted items",
        "mode": "block",
        "match_preset": "similar",
    },
)

data = response.json()

201 CreatedResponse

{
  "object": "wordlist",
  "id": "wl_5KcJIqikl2tXcuKJHvpzgO",
  "project_id": "prj_0TBAgHGtdMketrbltGFHuk",
  "slug": "restricted-items",
  "policy": "wordlist/restricted-items",
  "name": "Restricted items",
  "description": null,
  "mode": "block",
  "match_preset": "similar",
  "language": null,
  "enabled": true,
  "entries_count": 0,
  "created_at": "2026-10-08T09:29:26.558Z",
  "updated_at": "2026-10-08T09:29:26.558Z"
}

Request body

namestringRequired

A name for the list, 1 to 200 characters.

slugstring

The slug used in the policy key wordlist/<slug>: 2 to 80 lowercase letters, digits and single hyphens. Default: derived from the name, with a number added when it is taken. It cannot be changed later.

descriptionstring

A note on what the list is for, up to 2,000 characters.

modeenum

What a match means. block (default): a matched term is a violation and scores 0.85, plus 0.05 for each further match, up to 1. require: the violation is that no term matched, which scores 1. collect: matches are reported and the score stays 0; a match still fires the policy's trigger and counts as 0.85 towards severity unless the template enables the wordlist in observe mode.

One ofblockrequirecollect

match_presetenum

How close a word must be to a single-word term to match, as a similarity from 0 to 1 (1 minus the edit distance divided by the length of the longer word): exact 1.0, same_word 0.9 (default), similar 0.75, nearest 0.6. Text and terms are normalised first, so case, lookalike characters and digit-for-letter substitutions do not matter. A term with a space is matched as an exact phrase whatever the preset.

One ofexactsame_wordsimilarnearest

languagestring

A language code of up to 8 characters, for your own reference. It does not change matching.

enabledboolean

Whether the list is matched. A disabled list scores 0 on the templates that enable it. Default true.

Returns

The new wordlist, with status 201.

201 CreatedA wordlist object

Errors

403: plan_limit
The organisation's plan includes no wordlists, or the project already has as many as the plan allows.
409: slug_taken
The project already has a wordlist with this slug.
422: validation_error
name is missing, empty or too long, slug is not a valid slug, mode or match_preset is not one of the listed values, or the body has an unknown key.

Every endpoint can also answer the errors any request can meet: a missing key, a rate limit, a malformed body. Errors

Something missing or unclear on this page? Write to support@useinfrared.com.