{
  "openapi": "3.1.0",
  "info": {
    "title": "Regulatory Signals API",
    "description": "REST API for logging AI interaction events and accessing compliance monitoring data. Requires an API key issued from your dashboard.",
    "version": "1.0.0",
    "contact": {
      "name": "Regulatory Signals Support",
      "url": "https://www.regulatorysignals.com/contact",
      "email": "support@regulatorysignals.com"
    },
    "license": {
      "name": "Terms of Service",
      "url": "https://www.regulatorysignals.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://www.regulatorysignals.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/api/v1/log": {
      "post": {
        "operationId": "logAiEvent",
        "summary": "Log an AI interaction event",
        "description": "Records a single AI interaction event for compliance monitoring, audit trail, and EU AI Act evidence collection.",
        "tags": ["AI Event Logging"],
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LogEventRequest"
              },
              "example": {
                "eventType": "inference",
                "modelVersion": "claude-sonnet-4-6",
                "intentCategory": "content-generation",
                "inputHash": "a3f1c2e4b5d6...",
                "outputPreview": "Generated a privacy policy summary.",
                "riskScore": 12
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event logged successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LogEventResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Bearer token. Format: `Bearer <your-api-key>`"
      }
    },
    "schemas": {
      "LogEventRequest": {
        "type": "object",
        "required": ["eventType"],
        "properties": {
          "eventType": {
            "type": "string",
            "minLength": 1,
            "maxLength": 50,
            "description": "Category of the AI event being logged.",
            "example": "inference"
          },
          "modelVersion": {
            "type": "string",
            "maxLength": 100,
            "description": "Identifier for the AI model version used.",
            "example": "gpt-4o-2024-05"
          },
          "intentCategory": {
            "type": "string",
            "maxLength": 100,
            "description": "High-level purpose or intent of the interaction.",
            "example": "content-generation"
          },
          "inputHash": {
            "type": "string",
            "maxLength": 64,
            "description": "SHA-256 hex digest of the raw input. Stored for auditability without exposing PII."
          },
          "outputPreview": {
            "type": "string",
            "maxLength": 500,
            "description": "A short, non-sensitive excerpt or summary of the model output."
          },
          "riskScore": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Your application's computed risk score for this interaction."
          }
        }
      },
      "LogEventResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier of the logged event."
          },
          "logged": {
            "type": "boolean",
            "example": true
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable error message."
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "Full API documentation",
    "url": "https://www.regulatorysignals.com/docs/api"
  }
}