Developer reference / v1

From text to decision.

Use your customer API key from your server. A successful check costs one request credit. No provider key is exposed.

1. Submit a check

curl https://moderate.lawlesssolutions.us/v1/moderate \
  -H "Authorization: Bearer $MODERATELS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: comment-123-v1' \
  -d '{"text":"Have a wonderful afternoon!"}'

A quick completion returns HTTP 200. Otherwise HTTP 202 includes a job ID and a Location header. Poll that location with the same Bearer key. Check the job and item status before using the result; HTTP 200 on a retrieved job is not a moderation verdict.

2. Read the result

curl https://moderate.lawlesssolutions.us/v1/jobs/mod_YOUR_JOB_ID \
  -H "Authorization: Bearer $MODERATELS_API_KEY"

Each item contains status, result, error, and charged_credits. Only completed items have a usable result. The result contains text_safety, optional response_safety, flagged, action, optional categories, matched rule numbers, and provider usage.

Endpoints

Endpoint	Purpose
POST /v1/moderate	One text, with an optional AI response.
POST /v1/batches	1–10 items. Returns a polling location.
GET /v1/jobs/{id}	Retrieve only your account’s results.
GET /v1/usage	Available and reserved credits; item counts.
GET /v1/policies	List your versioned policies.
PUT /v1/policies/{id}	Save moderation rules.
POST /v1/credits/checkout	Create a hosted checkout when purchases are enabled.

Batch request

{
  "items": [
    {"text": "A community comment."},
    {"text": "A user question.", "response": "An assistant answer."}
  ],
  "policy_id": "default"
}

Policy rules

Send this JSON to PUT /v1/policies/community, then use "policy_id":"community". Rules are frozen when a job is submitted.

{
  "unsafe_action": "review",
  "category_actions": {"Threat": "block"},
  "blocked_terms": ["example prohibited phrase"]
}

Phrase rules match case-insensitive literal substrings. They supplement the model classification; flagged remains the model’s judgment. Category rules apply only to labels actually returned. They cannot override an unavailable result.

Limits and retries

Each item accepts up to 16,000 UTF-8 bytes, combining text and response. The default account limit is 10 new jobs per minute. The pilot shares a small upstream allowance. HTTP 429 or 503 may include Retry-After. Retry submissions with the same Idempotency-Key to avoid duplicate work. A different payload with the same key returns 409.

Failed items consume no customer credits. Pending work reserves one credit per item. Completed results expire after seven days; billing and idempotency metadata remain. See retention details.