{
  "openapi": "3.1.0",
  "info": {
    "title": "CautionLabs Content Moderation API",
    "version": "1.0.0",
    "description": "Send text and get true/false flags across twelve harm categories, plus an overall flagged result.",
    "termsOfService": "https://cautionlabs.com/legal/terms/cloud",
    "contact": { "name": "CautionLabs Support", "email": "support@cautionlabs.com" }
  },
  "externalDocs": { "description": "API reference", "url": "https://cautionlabs.com/docs" },
  "servers": [{ "url": "https://api.cautionlabs.com" }],
  "security": [{ "cloudApiKey": [] }],
  "paths": {
    "/moderation": {
      "post": {
        "operationId": "moderateText",
        "summary": "Moderate text",
        "description": "Checks a text of up to 10,000 characters. One credit pays for each started 3,000 characters.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ModerationRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The moderation result.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ModerationResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "500": { "$ref": "#/components/responses/Error" },
          "503": {
            "description": "model_starting: the model is starting after a quiet period. No credits are charged. Retry after the number of seconds in the Retry-After header.",
            "headers": { "Retry-After": { "schema": { "type": "integer" } } },
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "cloudApiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "A cloud API key from the dashboard. A private (on-premises) key does not work here."
      }
    },
    "responses": {
      "Error": {
        "description": "The request failed.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      }
    },
    "schemas": {
      "ModerationRequest": {
        "type": "object",
        "required": ["text"],
        "properties": {
          "text": { "type": "string", "minLength": 1, "maxLength": 10000 }
        }
      },
      "ModerationResponse": {
        "type": "object",
        "required": ["categories", "flagged"],
        "properties": {
          "categories": {
            "type": "object",
            "required": [
              "toxic",
              "profanity",
              "hate",
              "harassment",
              "self_harm",
              "adult",
              "violence",
              "drugs",
              "weapons",
              "pii",
              "spam",
              "minor"
            ],
            "properties": {
              "toxic": { "type": "boolean" },
              "profanity": { "type": "boolean" },
              "hate": { "type": "boolean" },
              "harassment": { "type": "boolean" },
              "self_harm": { "type": "boolean" },
              "adult": { "type": "boolean" },
              "violence": { "type": "boolean" },
              "drugs": { "type": "boolean" },
              "weapons": { "type": "boolean" },
              "pii": { "type": "boolean" },
              "spam": { "type": "boolean" },
              "minor": { "type": "boolean" }
            }
          },
          "flagged": {
            "type": "boolean",
            "description": "True when any category is flagged."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": ["code", "message"],
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "invalid_request",
              "unauthorized",
              "insufficient_credits",
              "wrong_key_type",
              "internal_error",
              "model_starting"
            ]
          },
          "message": { "type": "string" }
        }
      }
    }
  }
}