{"openapi":"3.1.0","info":{"title":"ban.wtf Moderation APIs","version":"1.0.0","description":"High-precision, credit-based Image and Text Moderation API Gateway. Provides sub-50ms text safety scoring, zero-day raid filtering, phishing/scam detection, adult content/NSFW image classification, and face age estimation.","contact":{"name":"ban.wtf Support & Community","url":"https://apis.ban.wtf/docs"}},"servers":[{"url":"https://apis.ban.wtf","description":"Primary ban.wtf Gateway Server"}],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"paths":{"/api/v1/moderate/text":{"post":{"summary":"Moderate Discord / Chat Text","description":"Evaluates a single message for phishing, scam links, toxicity, raid behavior, and recommends moderation action (ban, timeout, warn, none).","operationId":"moderateText","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TextModerationRequest"}}}},"responses":{"200":{"description":"Message evaluated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TextModerationResponse"}}}},"401":{"description":"Missing or invalid secret API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient account credit balance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error (e.g. empty 'content').","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/moderate/text/batch":{"post":{"summary":"Batch Moderate Messages (Up to 50)","description":"Concurrently evaluates up to 50 chat messages in a single atomic HTTP request.","operationId":"moderateTextBatch","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchTextModerationRequest"}}}},"responses":{"200":{"description":"Batch evaluated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchTextModerationResponse"}}}},"401":{"description":"Missing or invalid secret API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient credits for the total batch size.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Batch size limit exceeded or item missing 'content'.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/moderate/image":{"post":{"summary":"Moderate Image (NSFW, Anime, Age Estimation)","description":"Classifies explicit nudity, anime/drawn nudity, and performs face detection age estimation. Accepts public URL, base64 payload, or multipart/form-data upload.","operationId":"moderateImage","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageModerationJsonRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ImageModerationFormDataRequest"}}}},"responses":{"200":{"description":"Image processed and classified successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageModerationResponse"}}}},"401":{"description":"Missing or invalid secret API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient credit balance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"No valid image provided or unprocessable file format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/pricing":{"get":{"summary":"Get Live Per-Request Credit Pricing","description":"Returns current system pricing rates for image and text moderation requests.","operationId":"getPricing","security":[],"responses":{"200":{"description":"Current pricing rates.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricingResponse"}}}}}}},"/api/v1/moderate/health":{"get":{"summary":"Gateway & Microservice Health Status","description":"Checks connection status to upstream moderation microservices.","operationId":"getHealth","security":[],"responses":{"200":{"description":"Health status details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/api/v1/inference":{"post":{"summary":"General-Purpose AI Decision Inference & Custom Instructions","description":"Runs general-purpose AI decision inference on arbitrary input contexts using custom instructions, shorthand choice arrays, typed decision schemas, or prompts. Aliased under POST /v1/inference, POST /v1/custom, and POST /api/inference.","operationId":"executeInference","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomInferenceRequest"}}}},"responses":{"200":{"description":"Inference executed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomInferenceResponse"}}}},"401":{"description":"Missing or invalid secret API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient account credit balance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/judges/{id}/inference":{"post":{"summary":"Execute Inference via Specific Judge","description":"Executes custom inference inheriting the specified Judge's instructions, parameters, and auto-logs data to the Judge's dataset if storeContent is enabled.","operationId":"executeJudgeInference","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The Judge unique ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomInferenceRequest"}}}},"responses":{"200":{"description":"Judge evaluated input successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomInferenceResponse"}}}}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"bw_live_*","description":"Supply your API key in the format: Bearer bw_live_..."},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Supply your API key in the x-api-key header."}},"schemas":{"TextModerationRequest":{"type":"object","required":["content"],"properties":{"content":{"type":"string","description":"The message text to evaluate.","example":"FREE NITRO: Claim your Discord Nitro gift immediately at https://discrod-nitro.ru/claim @everyone"},"author":{"type":"string","description":"Username, discriminator, or Discord snowflake ID.","default":"user#0001","example":"spambot#1337"},"channel":{"type":"string","description":"Channel name or channel ID.","default":"#general","example":"#general"},"account_age_days":{"type":"integer","description":"Age of Discord account in days (used for raid detection).","default":30,"example":1},"mentions_count":{"type":"integer","description":"Count of user/role mentions in message.","default":0,"example":1},"has_attachments":{"type":"boolean","description":"Whether the message contains attachments/files.","default":false,"example":false},"mode":{"type":"string","enum":["hybrid","native"],"default":"hybrid","description":"Moderation engine pipeline."}}},"TextModerationResponse":{"type":"object","properties":{"id":{"type":"string","example":"mod_7f2b90d1ec4a3901"},"action":{"type":"string","enum":["ban","timeout","warn","none"],"example":"ban"},"threat_score":{"type":"number","example":2.4512},"is_phishing_or_scam":{"type":"number","example":0.9821},"requires_mod_review":{"type":"number","example":0.9145},"action_probabilities":{"type":"object","properties":{"ban":{"type":"number","example":0.9612},"timeout":{"type":"number","example":0.0245},"warn":{"type":"number","example":0.0101},"none":{"type":"number","example":0.0042}}},"routing_model":{"type":"string","example":"diffusion_router"},"latency_ms":{"type":"number","example":14.82},"mode":{"type":"string","example":"hybrid"},"credits_deducted":{"type":"number","example":1},"remaining_credits":{"type":"number","example":149}}},"BatchTextModerationRequest":{"type":"object","required":["messages"],"properties":{"messages":{"type":"array","minItems":1,"maxItems":50,"items":{"$ref":"#/components/schemas/TextModerationRequest"}},"mode":{"type":"string","enum":["hybrid","native"],"default":"hybrid"}}},"BatchTextModerationResponse":{"type":"object","properties":{"batch_size":{"type":"integer","example":2},"total_latency_ms":{"type":"number","example":38.45},"results":{"type":"array","items":{"type":"object","properties":{"content":{"type":"string"},"action":{"type":"string","enum":["ban","timeout","warn","none"]},"threat_score":{"type":"number"},"is_phishing_or_scam":{"type":"number"},"requires_mod_review":{"type":"number"},"action_probabilities":{"type":"object"}}}},"credits_deducted":{"type":"number","example":2},"remaining_credits":{"type":"number","example":147}}},"ImageModerationJsonRequest":{"type":"object","properties":{"image_url":{"type":"string","format":"uri","description":"Public HTTP/HTTPS URL of image to download and classify.","example":"https://images.unsplash.com/photo-1534528741775-53994a69daeb"},"image_base64":{"type":"string","description":"Base64-encoded image string or data URI."}}},"ImageModerationFormDataRequest":{"type":"object","properties":{"image":{"type":"string","format":"binary","description":"Raw image binary (JPEG, PNG, WebP)."}}},"ImageModerationResponse":{"type":"object","properties":{"status":{"type":"string","example":"success"},"request_id":{"type":"string","example":"req_img_1726918293"},"credits_deducted":{"type":"number","example":5},"remaining_credits":{"type":"number","example":140},"data":{"type":"object","properties":{"is_flagged":{"type":"boolean","example":false},"summary":{"type":"string","example":"Image passed safety filters."},"categories":{"type":"object","properties":{"nudity":{"type":"object","properties":{"score":{"type":"number","example":0.0051},"flagged":{"type":"boolean","example":false},"labels":{"type":"array","items":{"type":"string"}}}},"drawn_nudity":{"type":"object","properties":{"score":{"type":"number","example":0.0019},"flagged":{"type":"boolean","example":false},"labels":{"type":"array","items":{"type":"string"}}}},"age_estimation":{"type":"object","properties":{"estimated_age":{"type":"integer","example":34},"age_range":{"type":"string","example":"29 to 39"},"is_minor":{"type":"boolean","example":false},"confidence":{"type":"number","example":0.75},"face_detected":{"type":"boolean","example":true}}}}},"classifications":{"type":"array","items":{"type":"object","properties":{"className":{"type":"string"},"probability":{"type":"number"}}}},"meta":{"type":"object","properties":{"source":{"type":"string"},"latency_ms":{"type":"number"},"processed_at":{"type":"string","format":"date-time"},"model_backend":{"type":"string"}}}}}}},"PricingResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"pricing":{"type":"object","properties":{"imageCreditCost":{"type":"number","example":5},"textCreditCost":{"type":"number","example":1}}}}},"HealthResponse":{"type":"object","properties":{"gateway_status":{"type":"string","example":"healthy"},"service":{"type":"string","example":"banwtf-gateway-v1"},"timestamp":{"type":"string","format":"date-time"},"services":{"type":"object","properties":{"text_moderation":{"type":"object","properties":{"url":{"type":"string"},"healthy":{"type":"boolean"}}},"image_moderation":{"type":"object","properties":{"url":{"type":"string"},"healthy":{"type":"boolean"}}}}}}},"CustomInferenceRequest":{"type":"object","properties":{"state":{"description":"The input context to evaluate (string, structured dictionary, or list).","example":{"customer_id":"corp_9981","tier":"enterprise","ticket_subject":"Production database latency spike"}},"content":{"type":"string","description":"Convenience alias for 'state' if passing text."},"instructions":{"description":"Custom evaluation criteria, question schema, shorthand choice array, or prompt.","example":{"sentiment":["positive","neutral","negative"]}},"backend":{"type":"string","enum":["auto","local","openrouter"],"default":"auto"},"model":{"type":"string","default":"auto","example":"english"},"mode":{"type":"string","enum":["native","hybrid"],"default":"native"},"parameters":{"type":"object","description":"Arbitrary inference parameters dictionary."},"judge_id":{"type":"string","description":"Optional Judge ID to inherit instructions, parameters, and auto-record dataset samples."}}},"CustomInferenceResponse":{"type":"object","properties":{"id":{"type":"string","example":"inf_7f2b90d1ec4a3901"},"status":{"type":"string","example":"success"},"backend":{"type":"string","example":"local"},"model":{"type":"string","example":"english"},"latency_ms":{"type":"number","example":18.42},"answers":{"type":"object","description":"Dictionary of evaluated answers corresponding to instruction keys."},"routing":{"type":"object","properties":{"model":{"type":"string","example":"english"},"reason":{"type":"string","example":"English Latin text"}}},"inference_parameters":{"type":"object"},"usage":{"type":"object","properties":{"input_tokens":{"type":"integer","example":64},"output_tokens":{"type":"integer","example":0}}},"credits_deducted":{"type":"number","example":1},"remaining_credits":{"type":"number","example":149},"judge_id":{"type":"string"},"logged":{"type":"boolean"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","example":"Unauthorized. Missing or invalid secret key."},"code":{"type":"string","example":"UNAUTHORIZED"}}}}}}