{
  "openapi": "3.0.0",
  "info": {
    "title": "Pixel Patrol API",
    "version": "1.0.0",
    "description": "API for submitting media for moderation and checking status.\n\n**Webhooks:**\n\nPixel Patrol can send webhooks to notify your application about moderation events. These webhooks are secured using HMAC-SHA256 signatures.\n\n- **Signature Location:** The signature is sent in the `X-PixelPatrol-Signature` HTTP header for real events (`media.created`, `media.moderated`, etc.). For test events (`webhook.test.ping`) sent via the dashboard button, the signature is included in the JSON body under the `_pixelpatrol_signature` key.\n- **Verification:** You must verify the signature using your site's unique Webhook Secret (found in the Pixel Patrol dashboard under Site -> Webhooks) against the raw request body.\n\n**For detailed instructions and code examples on verifying webhook signatures, please see the [Webhook Verification Guide](/docs/api-integration/webhook-verification).**"
  },
  "servers": [
    {
      "url": "https://api.pixelpatrol.net/functions/v1",
      "description": "Pixel Patrol API"
    }
  ],
  "paths": {
    "/submit-media": {
      "post": {
        "summary": "Submit Media for Moderation",
        "description": "Submits text, image URL, or base64 image content for asynchronous moderation.",
        "tags": ["Media"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "api_key": {
                    "type": "string",
                    "description": "Your Site API Key (required)."
                  },
                  "body": {
                    "type": "string",
                    "description": "Text content (optional, provide content or content_url)."
                  },
                  "content_url": {
                    "type": "string",
                    "format": "url",
                    "description": "URL to image content (optional, provide content or content_url)."
                  },
                  "app_media_id": {
                    "type": "string",
                    "description": "Optional ID from your application for this media item."
                  },
                  "rule_group_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Optional Rule Group ID to use for moderation (defaults to site default)."
                  },
                  "metadata": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Optional additional metadata."
                  }
                },
                "required": ["api_key"]
              },
              "example": {
                "api_key": "site_xxxxxxxxxxxxxxxxxxxx",
                "content_url": "https://example.com/image.jpg",
                "body": "this is the text that I want to moderate",
                "app_media_id": "user-upload-123",
                "metadata": {
                  "gender": "male",
                  "user_id": "abc-987"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Media submitted successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string", "format": "uuid" },
                    "status": { "type": "string", "example": "pending" },
                    "message": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "description": "Invalid request body." },
          "401": { "description": "Invalid API Key." },
          "403": { "description": "Forbidden (e.g., limit exceeded, no active subscription)." },
          "500": { "description": "Internal server error." }
        }
      }
    },
    "/get-media-status": {
      "get": {
        "summary": "Get Media Moderation Status",
        "description": "Retrieves the current moderation status of a submitted media item.",
        "tags": ["Media"],
        "parameters": [
          {
            "name": "api_key",
            "in": "query",
            "required": true,
            "description": "Your Site API Key.",
            "schema": { "type": "string" }
          },
          {
            "name": "media_id",
            "in": "query",
            "required": false,
            "description": "The Pixel Patrol Media ID.",
            "schema": { "type": "string", "format": "uuid" }
          },
          {
            "name": "app_media_id",
            "in": "query",
            "required": false,
            "description": "The ID provided by your application during submission.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved status.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string", "format": "uuid" },
                    "status": { "type": "string", "enum": ["pending", "approved", "rejected", "pending_review"] },
                    "app_media_id": { "type": "string", "nullable": true },
                    "moderated_at": { "type": "string", "format": "date-time", "nullable": true }
                  }
                }
              }
            }
          },
          "400": { "description": "Missing required query parameter (media_id or app_media_id)." },
          "401": { "description": "Invalid API Key." },
          "404": { "description": "Media not found." },
          "500": { "description": "Internal server error." }
        }
      }
    }
  }
}