Submit a text moderation batch

Submit 1 to 99 texts in one request. Each item is checked on its own, exactly as /moderate/text checks one text, and gets its own decision under the key you gave it. One batch request counts as one request against your rate limit; each item is billed as one text moderation. Each item is also an ordinary text job, so GET /job/{job_id} reads it. When every item has a final decision or has failed, one webhook carries all the decisions. The batch is accepted whole or refused whole: an empty batch (BATCH_EMPTY), more than 99 items (BATCH_TOO_LARGE), a repeated key (DUPLICATE_ITEM_KEY), a text over 20,000 characters (TEXT_TOO_LONG) or any other invalid item (INVALID_REQUEST) refuses the request with 400, and nothing is charged.

POSThttps://api.omnifence.ai/api/v1/moderate/text/batch

Requires the moderate:text scope. Requests without this scope receive a 403 FORBIDDEN response. See authentication.

A batch holds 1 to 99 items. Each text is limited to 20,000 characters, and each key must be unique in the batch. An invalid batch is refused with 400 before any job is created or billed. See batch text moderation.

One batch request counts as one request against your rate limit. Each item is billed as one text moderation job.

Request#

Headers#

Name	Type	Required	Description
`Authorization`	string	Yes	Your API key as a Bearer token: `Bearer YOUR_API_KEY`.

Body (application/json)#

Field	Type	Required	Description
`items`	array of object	Yes	The texts to check, 1 to 99. Each item is checked on its own and gets its own decision.
`items[].key`	string	Yes	Your name for this item, unique in the batch, for example `backstory`. The decision for the item carries the same key. Length min `1`, max `64`.
`items[].text`	string	Yes	The text to check. At most 20,000 characters, as for `/moderate/text`. Length min `1`, max `20000`.
`webhook_url`	string (uri)	No	HTTPS URL that receives one webhook when every item has a final decision or has failed. Falls back to your registered webhook. Items send no webhook of their own.

Example bodyJSON

{
  "items": [
    {
      "key": "string",
      "text": "string"
    }
  ],
  "webhook_url": "https://example.com"
}

Example request#

cURLShell

curl -X POST https://api.omnifence.ai/api/v1/moderate/text/batch \
  -H "Authorization: Bearer $OMNIFENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "key": "name", "text": "Captain Mira" },
      { "key": "backstory", "text": "A pilot who left the fleet." }
    ],
    "webhook_url": "https://your-app.com/webhooks/omnifence"
  }'

Responses#

202 Accepted#

Field	Type	Always present	Description
`batch_id`	string (uuid)	Yes
`status`	string	Yes	One of `processing`.
`items`	array of object	Yes	One entry for each submitted item, in the order you sent them.
`items[].key`	string	Yes
`items[].job_id`	string (uuid)	Yes	The item is an ordinary text job: `GET /job/{job_id}` reads it.

Example responseJSON

{
  "batch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing",
  "items": [
    {
      "key": "string",
      "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ]
}

503 Service Unavailable#

Moderation intake is busy or a dependency is unavailable. Capacity rejections include Retry-After (seconds); retry with backoff and jitter. SUBMISSION_STATUS_UNKNOWN includes a batch_id: read it with GET /moderate/text/batch/{batch_id} before submitting again, because acceptance could not be confirmed.

Field	Type	Always present	Description
`error`	string	Yes
`message`	string	Yes
`statusCode`	integer	Yes	One of `503`.
`batch_id`	string (uuid)	No	Recovery ID when the acceptance outcome is unknown.

Example responseJSON

{
  "error": "string",
  "message": "string",
  "statusCode": 503,
  "batch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}