{
  "openapi": "3.1.0",
  "info": {
    "title": "Audit Log API",
    "version": "1.0.0",
    "description": "Every API and MCP call is recorded with the client, the end user or AI agent it acted for, the operation, the resource, and the authorization outcome. Supports investigations, privacy reviews, and continuous monitoring.\n\nReference design by Iron Brick LLC. Not an official government system; endpoints and data models are adapted to each agency's systems of record during implementation.",
    "contact": {
      "name": "Iron Brick LLC",
      "email": "info@ironbrick.us",
      "url": "https://dev.ironbrick.us"
    }
  },
  "servers": [
    {
      "url": "https://dev.ironbrick.us/sandbox/audit/v1",
      "description": "Iron Brick sandbox (synthetic data; free developer account)"
    },
    {
      "url": "https://{agency-gateway}/audit/v1",
      "description": "Agency deployment (behind the agency API gateway)"
    }
  ],
  "security": [
    {
      "oauth2": [
        "audit:read"
      ]
    }
  ],
  "paths": {
    "/audit-events": {
      "get": {
        "operationId": "queryAuditEvents",
        "summary": "Query audit events",
        "tags": [
          "Audit"
        ],
        "parameters": [
          {
            "name": "actor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "actorType",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "resource",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "outcome",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Pagination cursor from a previous response."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            },
            "description": "Maximum items to return."
          }
        ],
        "responses": {
          "200": {
            "description": "A page of audit events",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AuditEvent"
                      }
                    },
                    "page": {
                      "$ref": "#/components/schemas/Page"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid access token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Caller lacks the required scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/audit-exports": {
      "post": {
        "operationId": "createAuditExport",
        "summary": "Export to SIEM or file",
        "tags": [
          "Audit"
        ],
        "description": "Starts an export of audit events in JSON Lines or CEF for Splunk and other SIEM platforms.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "example": {
                "from": "2026-09-01T00:00:00Z",
                "to": "2026-09-30T23:59:59Z",
                "format": "cef",
                "destination": "splunk-hec"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Export started"
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid access token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Caller lacks the required scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "OAuth 2.0 client credentials for system-to-system calls. Agency deployments federate with the agency identity provider (PIV/CAC-backed for user-delegated access).",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://dev.ironbrick.us/oauth/token",
            "scopes": {
              "audit:read": "Read audit events"
            }
          }
        }
      }
    },
    "headers": {
      "X-Request-Id": {
        "description": "Unique request identifier; include it when contacting support.",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "code",
          "message",
          "requestId"
        ],
        "properties": {
          "code": {
            "type": "string",
            "example": "validation_error"
          },
          "message": {
            "type": "string",
            "example": "status must be one of: received, in_review, decided, closed"
          },
          "requestId": {
            "type": "string",
            "format": "uuid",
            "example": "3f1c9a52-7c1e-4f3e-9d2a-0b8e5f6a1c44"
          },
          "details": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "Page": {
        "type": "object",
        "properties": {
          "nextCursor": {
            "type": "string",
            "nullable": true,
            "example": "eyJvZmZzZXQiOjUwfQ"
          },
          "limit": {
            "type": "integer",
            "example": 50
          }
        }
      },
      "AuditEvent": {
        "type": "object",
        "properties": {
          "auditId": {
            "type": "string",
            "example": "AUD-9930012"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "example": "2026-09-30T14:22:05Z"
          },
          "clientId": {
            "type": "string",
            "example": "partner-portal-prod"
          },
          "actor": {
            "type": "string",
            "description": "End user or agent the call was made for.",
            "example": "adjudicator-0442"
          },
          "actorType": {
            "type": "string",
            "enum": [
              "user",
              "system",
              "ai_agent"
            ],
            "example": "ai_agent"
          },
          "operation": {
            "type": "string",
            "example": "cases.getCase"
          },
          "resource": {
            "type": "string",
            "example": "CASE-2026-004817"
          },
          "outcome": {
            "type": "string",
            "enum": [
              "allowed",
              "denied",
              "error"
            ],
            "example": "allowed"
          },
          "requestId": {
            "type": "string",
            "format": "uuid"
          }
        }
      }
    }
  }
}