{ "openapi": "3.1.1", "info": { "title": "Cirrova Public API", "description": "REST API for programmatic access to Cirrova monitoring and cost data.", "version": "v1" }, "servers": [ { "url": "https://app.cirrova.io/" } ], "paths": { "/api/public/v1/organisation": { "get": { "tags": [ "PublicApi" ], "summary": "Returns the authenticated organisation's name, plan, and tenancy count.", "operationId": "PublicGetOrganisation", "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/tenants": { "get": { "tags": [ "PublicApi" ], "summary": "List tenants accessible to the API key holder.", "operationId": "PublicListTenants", "parameters": [ { "name": "page", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK" } } }, "post": { "tags": [ "PublicApi" ], "summary": "Create a new tenant. Requires org owner.", "operationId": "PublicCreateTenant", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTenancyRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/tenants/{tenantId}": { "get": { "tags": [ "PublicApi" ], "summary": "Get tenant details.", "operationId": "PublicGetTenant", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/tenants/{tenantId}/snapshots": { "get": { "tags": [ "PublicApi" ], "summary": "List snapshot runs for a tenant.", "operationId": "PublicListTenantSnapshots", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK" } } }, "post": { "tags": [ "PublicApi" ], "summary": "Trigger a snapshot collection run. Returns 202 Accepted. Use ?deepHistory=true for a 30-day historical run.", "operationId": "PublicTriggerTenantSnapshot", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "deepHistory", "in": "query", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/tenants/{tenantId}/subscriptions": { "get": { "tags": [ "PublicApi" ], "summary": "List all Azure subscriptions in the tenant.", "operationId": "PublicListTenantSubscriptions", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/tenants/{tenantId}/subscriptions/{subscriptionId}": { "get": { "tags": [ "PublicApi" ], "summary": "Get a subscription by id.", "operationId": "PublicGetTenantSubscription", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/tenants/{tenantId}/resource-groups": { "get": { "tags": [ "PublicApi" ], "summary": "List all resource groups in the tenant. Filter by ?subscriptionId=.", "operationId": "PublicListTenantResourceGroups", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "subscriptionId", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/tenants/{tenantId}/resource-groups/{resourceGroupName}": { "get": { "tags": [ "PublicApi" ], "summary": "Get a resource group by name.", "operationId": "PublicGetTenantResourceGroup", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "resourceGroupName", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/tenants/{tenantId}/resources": { "get": { "tags": [ "PublicApi" ], "summary": "List all resources in the tenant. Filter by subscriptionId, resourceGroupId, armResourceName, resourceType.", "operationId": "PublicListTenantResources", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "subscriptionId", "in": "query", "schema": { "type": "string" } }, { "name": "resourceGroupId", "in": "query", "schema": { "type": "string" } }, { "name": "armResourceName", "in": "query", "schema": { "type": "string" } }, { "name": "resourceType", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/tenants/{tenantId}/resources/{resourceId}": { "get": { "tags": [ "PublicApi" ], "summary": "Get a resource by id.", "operationId": "PublicGetTenantResource", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/anomalies": { "get": { "tags": [ "PublicApi" ], "summary": "List anomalies across all accessible tenancies. Filter by severity, status, dateRaised, tenancyId.", "operationId": "PublicListAnomalies", "parameters": [ { "name": "severity", "in": "query", "schema": { "$ref": "#/components/schemas/AnomalySeverity" } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/AnomalyStatus" } }, { "name": "dateRaised", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "tenancyId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/anomalies/{anomalyId}": { "get": { "tags": [ "PublicApi" ], "summary": "Get anomaly by id.", "operationId": "PublicGetAnomaly", "parameters": [ { "name": "anomalyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } }, "patch": { "tags": [ "PublicApi" ], "summary": "Update anomaly status. Supported values: Acknowledged, Resolved.", "operationId": "PublicUpdateAnomalyStatus", "parameters": [ { "name": "anomalyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchAnomalyRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/insights": { "get": { "tags": [ "PublicApi" ], "summary": "List insights (cost reduction recommendations) across all accessible tenancies.", "operationId": "PublicListInsights", "parameters": [ { "name": "category", "in": "query", "schema": { "$ref": "#/components/schemas/RecommendationCategory" } }, { "name": "severity", "in": "query", "schema": { "$ref": "#/components/schemas/RecommendationSeverity" } }, { "name": "tenancyId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "includeDismissed", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "page", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/insights/{insightId}": { "get": { "tags": [ "PublicApi" ], "summary": "Get insight by id.", "operationId": "PublicGetInsight", "parameters": [ { "name": "insightId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } }, "patch": { "tags": [ "PublicApi" ], "summary": "Update insight status. Actions: NotRelevant, AcceptedRisk, Implemented, FalsePositive, Snoozed (requires snoozeDays).", "operationId": "PublicUpdateInsightStatus", "parameters": [ { "name": "insightId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchInsightRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/reports": { "get": { "tags": [ "PublicApi" ], "summary": "List all report definitions for the org.", "operationId": "PublicListReports", "parameters": [ { "name": "page", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/reports/{reportId}": { "get": { "tags": [ "PublicApi" ], "summary": "Get report definition details.", "operationId": "PublicGetReport", "parameters": [ { "name": "reportId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/reports/{reportId}/runs": { "get": { "tags": [ "PublicApi" ], "summary": "List all executed runs of a report.", "operationId": "PublicListReportRuns", "parameters": [ { "name": "reportId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK" } } }, "post": { "tags": [ "PublicApi" ], "summary": "Execute a report run. Returns 202 Accepted with Location pointing to the run resource.", "operationId": "PublicTriggerReportRun", "parameters": [ { "name": "reportId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/reports/{reportId}/runs/{runId}": { "get": { "tags": [ "PublicApi" ], "summary": "Get report run data.", "operationId": "PublicGetReportRun", "parameters": [ { "name": "reportId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/reports/{reportId}/runs/{runId}/csv": { "get": { "tags": [ "PublicApi" ], "summary": "Download report run as CSV. Redirects to a short-lived SAS URL.", "operationId": "PublicDownloadReportRunCsv", "parameters": [ { "name": "reportId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/reports/{reportId}/runs/{runId}/pdf": { "get": { "tags": [ "PublicApi" ], "summary": "Download report run as PDF.", "operationId": "PublicDownloadReportRunPdf", "parameters": [ { "name": "reportId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/reports/{reportId}/runs/{runId}/xlsx": { "get": { "tags": [ "PublicApi" ], "summary": "Download report run as XLSX.", "operationId": "PublicDownloadReportRunXlsx", "parameters": [ { "name": "reportId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/users": { "get": { "tags": [ "PublicApi" ], "summary": "List all users in the org. Requires org owner.", "operationId": "PublicListUsers", "parameters": [ { "name": "page", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK" } } }, "post": { "tags": [ "PublicApi" ], "summary": "Invite a user to the org. Returns 202 Accepted. Requires org owner.", "operationId": "PublicInviteUser", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitePublicUserRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/users/{userId}": { "get": { "tags": [ "PublicApi" ], "summary": "Get user details. Requires org owner.", "operationId": "PublicGetUser", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } }, "patch": { "tags": [ "PublicApi" ], "summary": "Update a user's display name, owner status, or enabled state. Requires org owner.", "operationId": "PublicUpdateUser", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchPublicUserRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/tenancies/{tenancyId}/users": { "get": { "tags": [ "PublicApi" ], "summary": "List users attached to a specific tenancy. Requires org owner or tenancy admin.", "operationId": "PublicListTenancyUsers", "parameters": [ { "name": "tenancyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/tenants/{tenantId}/events": { "get": { "tags": [ "PublicApi" ], "summary": "List event markers for a tenant.", "operationId": "PublicGetTenantEvents", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "schema": { "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "format": "date-time" } }, { "name": "category", "in": "query", "schema": { "$ref": "#/components/schemas/EventCategory" } }, { "name": "page", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK" } } }, "post": { "tags": [ "PublicApi" ], "summary": "Create an event marker. Primary use case: CI/CD deploy markers. Requires Editor or above.", "operationId": "PublicCreateTenantEvent", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePublicEventRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/tenants/{tenantId}/events/{eventId}": { "get": { "tags": [ "PublicApi" ], "summary": "Get a single event marker.", "operationId": "PublicGetTenantEvent", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } }, "patch": { "tags": [ "PublicApi" ], "summary": "Update an event marker. Requires Editor or above.", "operationId": "PublicUpdateTenantEvent", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchPublicEventRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } }, "delete": { "tags": [ "PublicApi" ], "summary": "Delete an event marker. Creators or Tenant Admins may delete.", "operationId": "PublicDeleteTenantEvent", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "AnomalySeverity": { "enum": [ "High", "Medium", "Low", null ] }, "AnomalyStatus": { "enum": [ "Active", "Acknowledged", "Resolved", null ] }, "CreatePublicEventRequest": { "required": [ "occurredAt", "title", "category" ], "type": "object", "properties": { "occurredAt": { "format": "date-time" }, "title": { "type": "string" }, "category": { "$ref": "#/components/schemas/EventCategory" }, "description": { "type": [ "null", "string" ] }, "tagKey": { "type": [ "null", "string" ] }, "tagValue": { "type": [ "null", "string" ] } } }, "CreateTenancyRequest": { "required": [ "name", "azureTenantId", "credentialType" ], "type": "object", "properties": { "name": { "type": "string" }, "azureTenantId": { "type": "string" }, "credentialType": { "$ref": "#/components/schemas/CredentialType" }, "clientId": { "type": [ "null", "string" ] }, "clientSecret": { "type": [ "null", "string" ] }, "certificateThumbprint": { "type": [ "null", "string" ] } } }, "CredentialType": { "enum": [ "ServicePrincipalSecret", "ServicePrincipalCertificate", "ManagedIdentity" ] }, "EventCategory": { "enum": [ "Deployment", "Launch", "Campaign", "Configuration", "Incident", "Other", null ] }, "InvitePublicUserRequest": { "required": [ "email" ], "type": "object", "properties": { "email": { "type": "string" }, "displayName": { "type": [ "null", "string" ] } } }, "PatchAnomalyRequest": { "required": [ "status" ], "type": "object", "properties": { "status": { "$ref": "#/components/schemas/AnomalyStatus" } } }, "PatchInsightRequest": { "required": [ "action" ], "type": "object", "properties": { "action": { "$ref": "#/components/schemas/RecommendationActionType" }, "snoozeDays": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" } } }, "PatchPublicEventRequest": { "type": "object", "properties": { "title": { "type": [ "null", "string" ] }, "description": { "type": [ "null", "string" ] }, "category": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EventCategory" } ] }, "occurredAt": { }, "tagKey": { "type": [ "null", "string" ] }, "tagValue": { "type": [ "null", "string" ] }, "clearTag": { "type": "boolean", "default": false } } }, "PatchPublicUserRequest": { "type": "object", "properties": { "displayName": { "type": [ "null", "string" ] }, "isDisabled": { "type": [ "null", "boolean" ] }, "isOwner": { "type": [ "null", "boolean" ] } } }, "RecommendationActionType": { "enum": [ "NotRelevant", "AcceptedRisk", "Implemented", "FalsePositive", "Snoozed", "AutoResolved" ] }, "RecommendationCategory": { "enum": [ "OrphanedResource", "StoppedVm", "OverProvisioned", "ScheduleOpportunity", "ReservedInstanceOpportunity", "UnusedResource", "HybridBenefitOpportunity", "ExpiredResource", null ] }, "RecommendationSeverity": { "enum": [ "Critical", "High", "Medium", "Low", null ] } }, "securitySchemes": { "ApiKey": { "type": "apiKey", "description": "API key. Obtain a key from your Cirrova profile settings and pass it in the X-Api-Key header.", "name": "X-Api-Key", "in": "header" } } }, "security": [ { "ApiKey": [ ] } ], "tags": [ { "name": "PublicApi" } ] }