POST /v1/moderations classifies one block of text against a saved preset or an inline policy.
Authentication
Send a Flagline machine key as a bearer token:
POST /v1/moderations
Authorization: Bearer mod_live_...
Content-Type: application/json
Idempotency-Key: optional-client-key
The key must be active, unrevoked, allowed to use the requested level, and attached to a tenant whose billing status is active or trialing. The tenant comes only from the key row. A selected workspace, request field, or client-supplied tenant ID is never authorization.
Request
| Field | Required | Notes |
|---|---|---|
input | Yes | The text to classify. Capped at 8,000 UTF-8 bytes after NFC normalization. |
preset_id | One of | UUID of a saved preset. Resolves its active version. |
preset | One of | Full inline policy content. Never saved or shown in the dashboard. |
level | No | light, standard, or heavy. Omitted uses the workspace default. Must be allowed by the key. |
on_failure | No | error, allow, flag, or block. Overrides the preset and workspace defaults. |
input_overflow | No | reject or truncate. Omitted uses the workspace default. |
preset_id and preset are mutually exclusive, and exactly one is required.
Saved preset
{
"input": "You are useless and should quit.",
"preset_id": "8a5f0f2e-5c9d-4f2a-a1f8-0f8f6f9c1b2a",
"level": "standard"
}
Inline preset
An inline preset is content only. It may not set id, source, version, or enabled. Category thresholds use the engine field names flagThreshold and blockThreshold.
{
"input": "You are useless and should quit.",
"preset": {
"name": "Support replies",
"description": "Rules for a customer support inbox.",
"defaultLevel": "standard",
"categories": [
{
"id": "harassment",
"name": "Harassment",
"description": "Targeted abuse or repeated personal insults.",
"flagThreshold": 0.45,
"blockThreshold": 0.85,
"severity": 7,
"allowExamples": [],
"blockExamples": []
}
]
}
}
Inline policies are limited to 25 categories and validated by the same engine preset schema that runs saved presets. An inline preset is compiled for that request only.
Response
{
"id": "3f30a1d8-0b9c-4a44-9d55-3b2f6f0f0d21",
"decision": "flag",
"flagged": true,
"categories": [{ "category_id": "harassment", "score": 0.61 }],
"level": "standard",
"model": "pinned-model-id",
"escalated": false,
"cached": false,
"degraded": false
}
decisionisallow,flag, orblock. Your application decides what to do with it.flaggedistruefor bothflagandblock.categoriescontains every evaluated category and its score. It is not the request text.modelnames the model that produced a non-degraded decision. It can benullwhen inference failed before any model call.escalatedreports whether the second tier was used.cachedistrueonly for a complete private-cache hit. Shared caching is not active in this release.degradedistrueonly when an explicit decision-shapedon_failuresupplied the verdict after inference was unavailable. A degraded response includes no invented category scores.
The raw input is not stored. The audit stores a domain-separated hash, scores, thresholds, the pinned model, the preset version, and the charge.
Failure behavior
The fallback precedence is:
explicit request on_failure > preset failurePolicy > workspace default > "error"
The default is an error response (503). allow, flag, or block return a degraded 200 instead. A degraded decision is audited and charged, but it is not test evidence for publishing a preset.
Limits and retries
- Body. 512 KiB maximum, streamed and enforced during the read.
- Raw input. 65,536 bytes before the applied cap.
- Applied input. 8,000 UTF-8 bytes of NFC-normalized text.
- Idempotency. An
Idempotency-Keyis scoped to the tenant and key for 24 hours. A completed replay returns the original response and decision ID without charging again. A different explicit request shape returns409 idempotency_conflict. A replay still consumes a rate-limit token. - Rate and concurrency. Per-key hard limits are enforced through the dedicated limits Redis. A refusal returns
429withRetry-After. - Daily spend ceiling. Optional per key. It bounds committed charges in a UTC day, not provider cost from failed inference.
- Deadline. The deployment deadline is 30 seconds. A workspace setting may shorten it. A timeout returns
408.
Errors
Errors use a fixed shape:
{
"error": {
"code": "inference_unavailable",
"message": "The moderation service is temporarily unavailable."
}
}
| Status | Codes |
|---|---|
| 400 or 422 | invalid_request; 400 also invalid_json; 422 also preset_invalid |
| 401 | unauthenticated |
| 403 | account_inactive, level_not_allowed |
| 404 | preset_not_found |
| 408 | request_timeout |
| 409 | preset_unusable, idempotency_conflict, idempotency_in_progress |
| 413 | payload_too_large, input_too_large |
| 415 | unsupported_media_type |
| 429 | rate_limited, concurrency_limited, spend_ceiling_exceeded |
| 499 | request_aborted |
| 503 | inference_unavailable, service_unavailable, commit_outcome_unknown |
Error messages are fixed for each code and never include request text, preset content, provider responses, or SQL details.
API keys
Create keys in the dashboard under API Keys. A key carries:
- A name.
- One or more allowed levels.
- A per-minute rate limit and a concurrency limit.
- An optional daily spend ceiling in USD.
The secret is shown once. Revocation keeps the key's history and stops new requests immediately. This API does not create or change presets.