API referenceMarkdown

API reference

The POST /v1/moderations request, response, limits, and error surface.

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

FieldRequiredNotes
inputYesThe text to classify. Capped at 8,000 UTF-8 bytes after NFC normalization.
preset_idOne ofUUID of a saved preset. Resolves its active version.
presetOne ofFull inline policy content. Never saved or shown in the dashboard.
levelNolight, standard, or heavy. Omitted uses the workspace default. Must be allowed by the key.
on_failureNoerror, allow, flag, or block. Overrides the preset and workspace defaults.
input_overflowNoreject 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
}
  • decision is allow, flag, or block. Your application decides what to do with it.
  • flagged is true for both flag and block.
  • categories contains every evaluated category and its score. It is not the request text.
  • model names the model that produced a non-degraded decision. It can be null when inference failed before any model call.
  • escalated reports whether the second tier was used.
  • cached is true only for a complete private-cache hit. Shared caching is not active in this release.
  • degraded is true only when an explicit decision-shaped on_failure supplied 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-Key is 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 returns 409 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 429 with Retry-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."
  }
}
StatusCodes
400 or 422invalid_request; 400 also invalid_json; 422 also preset_invalid
401unauthenticated
403account_inactive, level_not_allowed
404preset_not_found
408request_timeout
409preset_unusable, idempotency_conflict, idempotency_in_progress
413payload_too_large, input_too_large
415unsupported_media_type
429rate_limited, concurrency_limited, spend_ceiling_exceeded
499request_aborted
503inference_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.