{
  "openapi": "3.0.3",
  "info": {
    "title": "Petra Security API",
    "description": "The Petra Security API provides programmatic access to security data and functionality within your Petra portal.",
    "version": "1.0.0",
    "contact": {
      "name": "Petra Security Support",
      "email": "support@petrasecurity.com"
    }
  },
  "servers": [
    {
      "url": "https://api.petrasecurity.com",
      "description": "Production server"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/usage": {
      "get": {
        "summary": "Get tenant usage",
        "description": "Retrieve tenant usage stats, including billable date range and number of licensed users.",
        "operationId": "getUsage",
        "parameters": [
          {
            "name": "asOf",
            "in": "query",
            "required": false,
            "description": "Date in ISO format (YYYY-MM-DD) to get usage data for. Defaults to current date if not provided.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests - Rate limit exceeded for this route",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/v1/usage-xlsx": {
      "get": {
        "summary": "Download usage spreadsheet",
        "description": "Download a tenant usage report as an Excel (.xlsx) spreadsheet. This endpoint uses a Multi-MSP API Key for authentication rather than a standard Org API Key.",
        "operationId": "getUsageXlsx",
        "parameters": [
          {
            "name": "month",
            "in": "query",
            "required": false,
            "description": "Month in YYYY-MM format (e.g. 2026-03) to generate the usage report for. Defaults to the current month if not provided.",
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Excel spreadsheet containing tenant usage data",
            "content": {
              "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing Multi-MSP API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests - Rate limit exceeded for this route",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/v1/billable-users": {
      "get": {
        "summary": "Get billable users",
        "description": "Retrieve the list of billable users for a specific Petra tenant. A user is considered billable if they have non-empty assignedLicenseSkuIds and not deleted.",
        "operationId": "getBillableUsers",
        "parameters": [
          {
            "name": "tenantId",
            "in": "query",
            "required": true,
            "description": "The Petra tenant ID.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillableUsersResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - Tenant does not belong to your organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests - Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/v1/tenants": {
      "get": {
        "summary": "Get tenants",
        "description": "List the Petra tenants in your organization.",
        "operationId": "getTenants",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetTenantsResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "UsageResponse": {},
      "ErrorResponse": {},
      "BillableUsersResponse": {},
      "GetTenantsResponse": {}
    }
  }
}