{ "components": { "parameters": { "correlationId": { "description": "The object ID of the correlation identifier for the specified record.", "in": "path", "name": "correlationId", "required": true, "schema": { "examples": [ "1d71e0fe-6e4a-464d-a690-80addf3bda55" ], "format": "uuid", "maxLength": 36, "minLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "examples": { "valid correlation Id": { "summary": "Example valid correlation ID", "description": "An example of a valid correlation ID in type UUID string.", "value": "1d71e0fe-6e4a-464d-a690-80addf3bda55" } } }, "tenantId": { "description": "The object ID of the tenant to operate against.", "in": "path", "name": "tenantId", "required": true, "schema": { "examples": [ "b2fd105a-2594-437e-b934-1a62a51c28b4" ], "format": "uuid", "maxLength": 36, "minLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "examples": { "valid tenant Id": { "summary": "Example valid tenant ID", "description": "An example of a valid tenant ID in type UUID string.", "value": "1d71e0fe-6e4a-464d-a690-80addf3bda55" } } }, "channelName": { "description": "Name of the deploy channel to operate against.", "in": "path", "name": "channelName", "required": true, "schema": { "examples": [ "beta" ], "type": "string" }, "examples": { "valid channel name": { "summary": "Example valid channel name", "description": "An example string of a valid channel name.", "value": "stable" } } }, "channelRing": { "description": "Integer number representing ring to operate against.", "in": "path", "name": "number", "required": true, "schema": { "examples": [ 1 ], "type": "integer", "minimum": 0 }, "examples": { "valid channel ring": { "summary": "Example valid channel ring", "description": "An example integer that represents a valid channel ring.", "value": 1 }, "minimum channel ring": { "summary": "Example minimum channel ring", "description": "An example integer that represents the minimum valid channel ring.", "value": 0 }, "invalid channel ring": { "summary": "Example invalid channel ring", "description": "An example integer that represents an invalid channel ring, which is negative.", "value": -1 } } }, "version": { "description": "Version of the application package.", "in": "path", "name": "version", "required": true, "schema": { "examples": [ "1.12.5" ], "type": "string" }, "examples": { "Valid version number": { "summary": "Example valid version number", "description": "An example string represents a valid semantic version number.", "value": "1.2.3" } } }, "parentId": { "description": "The object ID of the parent value to operate against.", "in": "query", "name": "parentId", "required": false, "schema": { "examples": [ "3b241101-e2bb-4255-8caf-4136c566a962" ], "format": "uuid", "maxLength": 36, "minLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "examples": { "Valid parent ID": { "summary": "Example valid parent ID", "description": "An example UUID string that represents a valid parent object ID.", "value": "3b241101-e2bb-4255-8caf-4136c566a962" } } }, "dateStart": { "description": "Date string to narrow records selection to those created on or after that date.", "in": "query", "name": "dateStart", "required": false, "schema": { "examples": [ "2025-01-01T00:00:00Z" ], "format": "date-time", "type": "string" }, "examples": { "Valid start date": { "summary": "Example valid start date", "description": "An example ISO8601 date string that represents a valid start date in a query.", "value": "2025-01-01T00:00:00Z" } } }, "dateEnd": { "description": "Date string to narrow records selection to those created before or on that date.", "in": "query", "name": "dateEnd", "required": false, "schema": { "examples": [ "2025-02-05T23:59:59Z" ], "format": "date-time", "type": "string" }, "examples": { "Valid end date": { "summary": "Example valid end date", "description": "An example ISO8601 date string that represents a valid end date in a query.", "value": "2025-02-05T23:59:59Z" } } } }, "responses": { "400": { "description": "Invalid input!" }, "401": { "description": "Principal is not authorized to access this endpoint. Check to make sure the Bearer token is valid and present!" }, "403": { "description": "Principal does not contain the correct scopes (permissions) for the API call that was made, or was made from the wrong tenant. If the permissions were granted, ensure that the access token was requested with the correct scopes." }, "404": { "description": "The requested object was not found." }, "503": { "description": "App is starting still. Feature is not available. Please try again later." }, "525": { "description": "Infrastructure not deployed. Please deploy the infrastructure before using this endpoint." } }, "schemas": { "Core.HealthReport": { "description": "Health report that indicates if a service is down or not that the data gateway relies on.", "properties": { "authClient": { "description": "Flag that indicates if the client side authentication validation is working or not.", "examples": [ false ], "type": "boolean" }, "authServer": { "description": "Flag that indicates if the server side authentication is working or not.", "examples": [ true ], "type": "boolean" }, "bulkStorage": { "description": "Flag that indicates if the bulk storage system is down (`false`) or not (`true`). False indicate the service is not working, true indicates the service is working.", "examples": [ true ], "type": "boolean" }, "database": { "description": "Flag that indicates if the ORM (Database) system is down (`false`) or not (`true`). False indicate the service is not working, true indicates the service is working.", "examples": [ false ], "type": "boolean" } }, "required": [ "authClient", "authServer", "bulkStorage", "database" ], "title": "Core System - Health Report", "type": "object", "examples": [ { "authClient": false, "authServer": true, "bulkStorage": true, "database": false } ] }, "Chat.OpenAIChatMessage": { "title": "Chat - Message Record", "description": "Object representing entity supplied to the AI agent or a response from the AI Agent", "examples": [ { "role": "assistant", "content": "What are the available IDs?", "tool_calls": [ { "id": "call_abc123", "type": "function", "function": { "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", "name": "getCorrelationIDs" } } ] }, { "name": "John Doe", "role": "user", "content": [ { "text": "What are the available IDs?", "type": "text" } ], "tool_call_id": "call_abc123", "tool_calls": [ { "id": "call_abc123", "type": "function", "function": { "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", "name": "getCorrelationIDs" } } ] } ], "type": "object", "properties": { "content": { "oneOf": [ { "type": "string", "description": "The contents of the message" }, { "type": "array", "description": "The contents of the message", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "The text content" }, "type": { "type": "string", "description": "The type of the content part" } }, "required": [ "text", "type" ] }, "examples": [ [ { "text": "What are the available IDs?", "type": "text" } ] ] } ] }, "role": { "type": "string", "description": "The role of the messages author", "examples": [ "assistant" ] }, "name": { "type": "string", "description": "An optional name for the participant", "examples": [ "John Doe" ] }, "tool_calls": { "type": "array", "description": "The tool calls generated by the model, such as function calls", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the tool call", "examples": [ "call_abc121" ] }, "function": { "type": "object", "description": "The function that the model called", "properties": { "arguments": { "type": "string", "description": "The arguments to call the function with", "examples": [ "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}" ] }, "name": { "type": "string", "description": "The name of the function to call", "examples": [ "getCorrelationIDs" ] } }, "examples": [ { "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", "name": "getCorrelationIDs" } ] }, "type": { "type": "string", "description": "The type of the tool. Currently, only `function` is supported", "examples": [ "function" ] } }, "examples": [ { "id": "call_abc121", "function": { "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", "name": "getCorrelationIDs" }, "type": "function" } ] } }, "tool_call_id": { "type": "string", "description": "Tool call that this message is responding to", "examples": [ "call_abc123" ] } }, "required": [ "content", "role" ] }, "LicenseReport.CorrelationRecord": { "description": "Metadata that describes the execution session (run) that is used to tie/relate all of the license report together.", "examples": [ { "auditTenantAccount": "priv-user@example.com", "correlationId": "9d838115-0868-45d4-b8a5-98adc1af7e42", "reportTenantAccount": "ent-user@example.com", "tenantId": "7e536189-b2dd-4c8b-98b1-9b174777883f", "createdAt": "2024-08-01T21:13:12.821Z", "updatedAt": "2024-08-01T21:13:12.821Z" } ], "properties": { "auditTenantAccount": { "description": "The user account used to retrieve the license information in the tenant being audited.", "examples": [ "admin-user@example.com" ], "format": "email", "type": "string" }, "correlationId": { "description": "The ID of the execution session (run) that is used to tie/relate all of the data together.", "examples": [ "88da2253-758f-4135-9d37-64448c8b65c1" ], "format": "uuid", "type": "string", "pattern": "^\\w+-\\w+-\\w+-\\w+-\\w+$" }, "reportTenantAccount": { "description": "User account used to store/report the license report to the SHI Lab cloud service.", "examples": [ "generic-user@example.com" ], "format": "email", "type": "string" }, "tenantId": { "description": "Unique ID of customer's Microsoft tenant that the license report is for.", "examples": [ "0e1fe83f-a33f-4250-8546-225b8d45ae01" ], "format": "uuid", "type": "string", "pattern": "^\\w+-\\w+-\\w+-\\w+-\\w+$" }, "createdAt": { "description": "Timestamp of when the report was created.", "examples": [ "2024-08-01T21:12:22.148Z" ], "format": "date-time", "type": "string" }, "updatedAt": { "description": "Timestamp of when the report was last updated.", "examples": [ "2024-08-01T21:12:22.148Z" ], "format": "date-time", "type": "string" } }, "required": [ "auditTenantAccount" ], "title": "License Report - Correlation Record", "type": "object" }, "LicenseReport.LicenseData": { "type": "object", "properties": { "assignedLicense": { "additionalProperties": { "oneOf": [ { "type": "integer", "examples": [ 0 ] }, { "type": "null" } ] }, "description": "License assignment on the specified principal.", "type": "object", "examples": [ { "eec0eb4f-6444-4f95-aba0-50c24d67f998": 0 } ] }, "assignedService": { "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/LicenseReport.FeatureBreakdown" }, { "type": "integer", "format": "int32", "examples": [ 0 ] }, { "type": "null" } ] }, "description": "Service configuration assignment. This is used to record the set of principals that are \"benefiting\" from the service, regardless of license status.", "type": "object", "examples": [ { "eec0eb4f-6444-4f95-aba0-50c24d67f998": 0, "4b0d28f2-c1ce-48ae-a7d2-1caaa7825891": null }, { "eec0eb4f-6444-4f95-aba0-50c24d67f998": { "Conditional Access": false, "Access Review": true, "Entitlement Management": false, "Identity Protection": true } } ] }, "consumedService": { "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/LicenseReport.FeatureBreakdown" }, { "type": "integer", "format": "int32", "examples": [ 0 ] }, { "type": "null" } ] }, "description": "Usage telemetry retrieved for the service to indicate if the specific principal is consuming the service or not, regardless of license status.", "type": "object", "examples": [ { "eec0eb4f-6444-4f95-aba0-50c24d67f998": { "Conditional Access": true, "Access Review": false, "Entitlement Management": false, "Identity Protection": true } }, { "eec0eb4f-6444-4f95-aba0-50c24d67f998": 0, "4b0d28f2-c1ce-48ae-a7d2-1caaa7825891": null } ] } }, "required": [ "assignedLicense", "assignedService", "consumedService" ], "description": "Collection of principals that have had their in-use licenses and assigned licenses. Where the key is the principal ID and the value is the insights.", "examples": [ { "assignedLicense": { "eec0eb4f-6444-4f95-aba0-50c24d67f998": 0, "41781fb2-bc02-4b7c-bd55-b576c07bb09d": 1, "7159f980-6f83-4b67-bf41-e172b3ae1352": 2 }, "assignedService": { "eec0eb4f-6444-4f95-aba0-50c24d67f998": { "Conditional Access": false, "Access Review": true, "Entitlement Management": false, "Identity Protection": true }, "41781fb2-bc02-4b7c-bd55-b576c07bb09d": { "Conditional Access": true, "Dynamic Group": false, "Group Naming": true, "On-Prem SSPR": false, "Group Expiration": true, "Provisioning Engine": true, "Enterprise State Roaming": false }, "6511755b-c27d-4c66-a59e-b835e6b54e7f": null }, "consumedService": { "eec0eb4f-6444-4f95-aba0-50c24d67f998": { "Conditional Access": true, "Access Review": false, "Entitlement Management": false, "Identity Protection": true }, "41781fb2-bc02-4b7c-bd55-b576c07bb09d": { "Conditional Access": true, "Dynamic Group": false, "Group Naming": true, "On-Prem SSPR": false, "Group Expiration": true, "Provisioning Engine": true, "Enterprise State Roaming": false }, "4b0d28f2-c1ce-48ae-a7d2-1caaa7825891": null, "c90f1a25-e6cd-4163-ac6c-ca7616c585a9": null } } ], "title": "License Report - License Data" }, "LicenseReport.FeatureBreakdown": { "additionalProperties": { "type": "boolean", "examples": [ true ] }, "description": "List of features that are configured for the specific service plan's service configuration for the related principal.\nThe key is the name of the feature that is being described.\nThe value is the state of the feature configuration, `true` is in scope and `false` meaning not in scope.", "examples": [ { "Conditional Access": true, "Access Reviews": true, "Dynamic Groups": false, "On-Prem Password Rest": true, "On-Prem Password Protection": false } ], "title": "License Report - Feature Breakdown", "type": "object" }, "LicenseReport": { "description": "Completely calculated license report structure that is the result of a complete run.", "examples": [ { "availableLicense": { "e17b13ee-9749-488b-9289-d31a8fde045d": 123, "2d995b6a-d4aa-4d8d-a03c-372ecb66509d": 456, "cbf6ee7c-c3c1-44a6-9f18-020c65536470": 789 }, "correlation": { "auditTenantAccount": "admin-user@example.com", "correlationId": "88da2253-758f-4135-9d37-64448c8b65c1", "reportTenantAccount": "generic-user@example.com", "tenantId": "0e1fe83f-a33f-4250-8546-225b8d45ae01" }, "licenseData": { "250844e1-a7ab-4f21-8e3f-58f51b5983a3": { "assignedLicense": { "e17b13ee-9749-488b-9289-d31a8fde045d": 0 }, "assignedService": { "cbf6ee7c-c3c1-44a6-9f18-020c65536470": 0, "c7bcba35-199c-41e5-8c8d-6d4e4aad8964": null }, "consumedService": { "fe98c41a-d931-4f6f-a5bc-750ba7144a77": null, "0474bdf1-ee76-4aff-a65c-6f82e5e1d5a6": { "Something Here": true, "Other Obscure feature": false } } } } } ], "type": "object", "properties": { "availableLicense": { "additionalProperties": { "examples": [ 1234 ], "type": "integer" }, "description": "Breakdown of the purchased licenses/service plans available in the tenant being audited for this run. Where the key is the ID of the service plan and the value is how many licenses are available/purchase for it.", "examples": [ { "eec0eb4f-6444-4f95-aba0-50c24d67f998": 1234, "41781fb2-bc02-4b7c-bd55-b576c07bb09d": 123 } ], "title": "License Report - Available Licenses", "type": "object" }, "correlation": { "$ref": "#/components/schemas/LicenseReport.CorrelationRecord" }, "licenseData": { "additionalProperties": { "$ref": "#/components/schemas/LicenseReport.LicenseData" } } }, "required": [ "availableLicense", "correlation", "licenseData" ], "title": "License Report - Complete Object" }, "LicenseEntitlement.Shield": { "description": "Record that describes the purchased licenses for a specific tenant. More than one of these can be active at a single time.", "properties": { "correlationId": { "description": "Used to correlate the license entitlements with other records.", "examples": [ "e097a3f5-9599-44a2-8923-fd3276c83ae1" ], "format": "uuid", "maxLength": 36, "minLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", "readOnly": true, "type": "string" }, "enterpriseDeviceCount": { "description": "Count of Enterprise Devices that are allowed to be managed.", "examples": [ 5 ], "format": "int32", "type": "integer" }, "enterpriseInterfaceCount": { "description": "Count of Enterprise Interfaces that are allowed to be managed.", "examples": [ 6 ], "format": "int32", "type": "integer" }, "enterpriseIntermediaryCount": { "description": "Count of Enterprise Intermediaries that are allowed to be managed.", "examples": [ 7 ], "format": "int32", "type": "integer" }, "enterpriseUserCount": { "description": "Count of Enterprise Users that are allowed to be managed.", "examples": [ 8 ], "format": "int32", "type": "integer" }, "notValidAfter": { "description": "Date that the entitlement expires at.", "examples": [ "2024-07-30T17:35:24.044Z" ], "format": "date-time", "type": "string" }, "notValidBefore": { "description": "Date that the entitlement becomes active at.", "examples": [ "2024-07-30T17:37:15.300Z" ], "format": "date-time", "type": "string" }, "privilegedDeviceCount": { "description": "Count of Privileged Devices (PAW) that are allowed to be managed.", "examples": [ 9 ], "format": "int32", "type": "integer" }, "privilegedInterfaceCount": { "description": "Count of Privileged Interfaces that are allowed to be managed.", "examples": [ 10 ], "format": "int32", "type": "integer" }, "privilegedIntermediaryCount": { "description": "Count of Privileged Intermediaries that are allowed to be managed.", "examples": [ 11 ], "format": "int32", "type": "integer" }, "privilegedUserCount": { "description": "Count of Privileged Users that are allowed to be managed.", "examples": [ 12 ], "format": "int32", "type": "integer" }, "purchaseId": { "description": "This could be any value used to correlate the purchase operation to this entitlement record.", "examples": [ "Bob's your uncle." ], "type": "string" }, "specializedDeviceCount": { "description": "Count of Specialized Devices that are allowed to be managed.", "examples": [ 13 ], "format": "int32", "type": "integer" }, "specializedInterfaceCount": { "description": "Count of Specialized Interfaces that are allowed to be managed.", "examples": [ 14 ], "format": "int32", "type": "integer" }, "specializedIntermediaryCount": { "description": "Count of Specialized Intermediaries that are allowed to be managed.", "examples": [ 15 ], "format": "int32", "type": "integer" }, "specializedUserCount": { "description": "Count of Specialized Users that are allowed to be managed.", "examples": [ 15 ], "format": "int32", "type": "integer" }, "tenantId": { "description": "Tenant that this license entitlement is valid for.", "examples": [ "a2a1698d-a3e0-42d3-96a4-47eb3e8f7dd1" ], "format": "uuid", "maxLength": 36, "minLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", "readOnly": true, "type": "string" } }, "required": [ "enterpriseDeviceCount", "enterpriseInterfaceCount", "enterpriseIntermediaryCount", "enterpriseUserCount", "notValidAfter", "notValidBefore", "privilegedDeviceCount", "privilegedInterfaceCount", "privilegedIntermediaryCount", "privilegedUserCount", "specializedDeviceCount", "specializedInterfaceCount", "specializedIntermediaryCount", "specializedUserCount", "tenantId" ], "title": "License Entitlement - SHIELD Record", "type": "object", "examples": [ { "correlationId": "e097a3f5-9599-44a2-8923-fd3276c83ae1", "enterpriseDeviceCount": 5, "enterpriseInterfaceCount": 6, "enterpriseIntermediaryCount": 7, "enterpriseUserCount": 8, "notValidAfter": "2024-07-30T17:35:24.044Z", "notValidBefore": "2024-07-30T17:37:15.300Z", "privilegedDeviceCount": 9, "privilegedInterfaceCount": 10, "privilegedIntermediaryCount": 11, "privilegedUserCount": 12, "purchaseId": "any arbitrary string as purchaseId", "specializedDeviceCount": 13, "specializedInterfaceCount": 14, "specializedIntermediaryCount": 15, "specializedUserCount": 15, "tenantId": "a2a1698d-a3e0-42d3-96a4-47eb3e8f7dd1" } ] }, "LicenseEntitlement.Shield.Count": { "properties": { "enterpriseDeviceCount": { "description": "Count of Enterprise Devices that are allowed to be managed.", "examples": [ 5 ], "format": "int32", "type": "integer" }, "enterpriseInterfaceCount": { "description": "Count of Enterprise Interfaces that are allowed to be managed.", "examples": [ 3 ], "format": "int32", "type": "integer" }, "enterpriseIntermediaryCount": { "description": "Count of Enterprise Intermediaries that are allowed to be managed.", "examples": [ 7 ], "format": "int32", "type": "integer" }, "enterpriseUserCount": { "description": "Count of Enterprise Users that are allowed to be managed.", "examples": [ 8 ], "format": "int32", "type": "integer" }, "privilegedDeviceCount": { "description": "Count of Privileged Devices (PAW) that are allowed to be managed.", "examples": [ 9 ], "format": "int32", "type": "integer" }, "privilegedInterfaceCount": { "description": "Count of Privileged Interfaces that are allowed to be managed.", "examples": [ 10 ], "format": "int32", "type": "integer" }, "privilegedIntermediaryCount": { "description": "Count of Privileged Intermediaries that are allowed to be managed.", "examples": [ 11 ], "format": "int32", "type": "integer" }, "privilegedUserCount": { "description": "Count of Privileged Users that are allowed to be managed.", "examples": [ 12 ], "format": "int32", "type": "integer" }, "specializedDeviceCount": { "description": "Count of Specialized Devices that are allowed to be managed.", "examples": [ 13 ], "format": "int32", "type": "integer" }, "specializedInterfaceCount": { "description": "Count of Specialized Interfaces that are allowed to be managed.", "examples": [ 14 ], "format": "int32", "type": "integer" }, "specializedIntermediaryCount": { "description": "Count of Specialized Intermediaries that are allowed to be managed.", "examples": [ 15 ], "format": "int32", "type": "integer" }, "specializedUserCount": { "description": "Count of Specialized Users that are allowed to be managed.", "examples": [ 15 ], "format": "int32", "type": "integer" } }, "required": [ "enterpriseDeviceCount", "enterpriseInterfaceCount", "enterpriseIntermediaryCount", "enterpriseUserCount", "privilegedDeviceCount", "privilegedInterfaceCount", "privilegedIntermediaryCount", "privilegedUserCount", "specializedDeviceCount", "specializedInterfaceCount", "specializedIntermediaryCount", "specializedUserCount" ], "title": "License Entitlement - Active SHIELD Count", "type": "object", "examples": [ { "enterpriseDeviceCount": 5, "enterpriseInterfaceCount": 3, "enterpriseIntermediaryCount": 7, "enterpriseUserCount": 8, "privilegedDeviceCount": 9, "privilegedInterfaceCount": 10, "privilegedIntermediaryCount": 11, "privilegedUserCount": 12, "specializedDeviceCount": 13, "specializedInterfaceCount": 14, "specializedIntermediaryCount": 15, "specializedUserCount": 15 } ] }, "Telemetry.Shield": { "properties": { "correlationId": { "description": "Primary key for the table, used to correlate multiple telemetry records together.", "format": "uuid", "type": "string", "examples": [ "1d71e0fe-6e4a-464d-a690-80addf3bda55" ] }, "enterpriseDeviceCount": { "description": "Count of Enterprise Devices that are deployed in the CX environment.", "type": "integer", "minimum": 0, "examples": [ 0 ] }, "enterpriseInterfaceCount": { "description": "Number of active Enterprise interfaces.", "type": "integer", "minimum": 0, "examples": [ 0 ] }, "enterpriseIntermediaryCount": { "description": "Number of active Enterprise intermediaries.", "type": "integer", "minimum": 0, "examples": [ 0 ] }, "enterpriseUserCount": { "description": "Count of Enterprise Users that are deployed in the CX environment.", "type": "integer", "minimum": 0, "examples": [ 0 ] }, "monthlyActiveEntUsers": { "description": "Number of active managed Enterprise users.", "type": "integer", "minimum": 0, "examples": [ 0 ] }, "monthlyActivePrivUsers": { "description": "Number of active managed privileged users.", "type": "integer", "minimum": 0, "examples": [ 0 ] }, "monthlyActiveSpecUsers": { "description": "Number of active managed Specialized users.", "type": "integer", "minimum": 0, "examples": [ 0 ] }, "privilegedDeviceCount": { "description": "Count of Privileged Devices (PAW) that are deployed in the CX environment.", "type": "integer", "minimum": 0, "examples": [ 0 ] }, "privilegedInterfaceCount": { "description": "Number of active Privileged interfaces.", "type": "integer", "minimum": 0, "examples": [ 0 ] }, "privilegedIntermediaryCount": { "description": "Number of active Privileged intermediaries.", "type": "integer", "minimum": 0, "examples": [ 0 ] }, "privilegedUserCount": { "description": "Count of Privileged Users that are deployed in the CX environment.", "type": "integer", "minimum": 0, "examples": [ 0 ] }, "shieldArchitectureVersion": { "description": "Version number of the architecture that is deployed.", "examples": [ "27" ], "type": "string", "minLength": 1 }, "shieldCoreVersion": { "description": "Version number of the product that the product is running.", "examples": [ "2.5.6" ], "type": "string" }, "specializedDeviceCount": { "description": "Count of Specialized Devices that are deployed in the CX environment.", "type": "integer", "minimum": 0 }, "specializedInterfaceCount": { "description": "Number of active Specialized interfaces.", "type": "integer", "minimum": 0 }, "specializedIntermediaryCount": { "description": "Number of active Specialized intermediaries.", "type": "integer", "minimum": 0 }, "specializedUserCount": { "description": "Count of Specialized Users that are deployed in the CX environment.", "type": "integer", "minimum": 0 }, "tenantId": { "description": "Tenant ID for the CX in question.", "examples": [ "5ae80362-6fe8-4ab1-9b6d-8dfa99d91657" ], "type": "string" }, "createdAt": { "description": "Timestamp on when the record was created. This is auto managed by sequelize.", "examples": [ "2024-08-02T23:48:50.231Z" ], "format": "date-time", "type": "string" }, "updatedAt": { "description": "Timestamp on when the record was last updated. This is auto managed by sequelize.", "examples": [ "2024-08-02T23:48:50.231Z" ], "format": "date-time", "type": "string" } }, "required": [ "enterpriseDeviceCount", "enterpriseInterfaceCount", "enterpriseIntermediaryCount", "enterpriseUserCount", "monthlyActiveEntUsers", "monthlyActivePrivUsers", "monthlyActiveSpecUsers", "privilegedDeviceCount", "privilegedInterfaceCount", "privilegedIntermediaryCount", "privilegedUserCount", "shieldArchitectureVersion", "shieldCoreVersion", "specializedDeviceCount", "specializedInterfaceCount", "specializedIntermediaryCount", "specializedUserCount" ], "title": "Application Telemetry - SHIELD", "type": "object", "examples": [ { "correlationId": "1d71e0fe-6e4a-464d-a690-80addf3bda55", "enterpriseDeviceCount": 0, "enterpriseInterfaceCount": 0, "enterpriseIntermediaryCount": 0, "enterpriseUserCount": 0, "monthlyActiveEntUsers": 0, "monthlyActivePrivUsers": 0, "monthlyActiveSpecUsers": 0, "privilegedDeviceCount": 0, "privilegedInterfaceCount": 0, "privilegedIntermediaryCount": 0, "privilegedUserCount": 0, "shieldArchitectureVersion": "27", "shieldCoreVersion": "2.5.6", "specializedDeviceCount": 3, "specializedInterfaceCount": 2, "specializedIntermediaryCount": 1, "specializedUserCount": 0, "tenantId": "5ae80362-6fe8-4ab1-9b6d-8dfa99d91657", "createdAt": "2024-08-02T23:48:50.231Z", "updatedAt": "2024-08-02T23:48:50.231Z" } ] }, "Update.Shield.Check": { "description": "Object returning the value of the version of the latest application package available.", "properties": { "updateVersion": { "description": "Latest found version of the application package.", "examples": [ "1.12.5" ], "type": "string" } }, "required": [ "updateVersion" ], "title": "Update SHIELD Check - latest application package version", "type": "object", "examples": [ { "updateVersion": "1.12.5" } ] }, "Update.Shield.Channel": { "description": "Channel configuration for the SHIELD update service.", "properties": { "latest": { "description": "Version number of the latest update available to the chanel.", "examples": [ "1.12.5" ], "type": "string" }, "name": { "description": "(Unique) Name of the update channel that this configuration belongs to.", "examples": [ "stable" ], "type": "string" }, "previous": { "description": "Version number of the number that is being replaced via ring deployment, available to all rings at the minimum.", "examples": [ "1.12.4" ], "type": "string" } }, "required": [ "latest", "name", "previous" ], "title": "SHIELD Update - Channel", "type": "object", "examples": [ { "latest": "1.12.5", "name": "stable", "previous": "1.12.4" } ] }, "Update.Shield.Channel.Ring": { "description": "Object containing channel ring configuration.", "properties": { "latest": { "description": "Flag that indicates if the ring should be operating off of the latest version number provided by the channel (`true`) or the previous (`false`).", "examples": [ true ], "type": "boolean" }, "number": { "description": "Ring number that this configuration belongs to.", "examples": [ 1 ], "type": "integer", "minimum": 0 } }, "required": [ "latest", "number" ], "title": "Update SHIELD Channel Ring - configuration entry", "type": "object", "examples": [ { "latest": true, "number": 1 } ] }, "Update.Shield.Tenant": { "description": "Object containing tenant update configuration.", "properties": { "alphaEnabled": { "description": "Flag that indicates if the current tenant is allowed to request alpha builds (`true`) or not (`false`).", "examples": [ false ], "type": "boolean" }, "channel": { "description": "Name of the deploy channel.", "examples": [ "stable" ], "type": "string" }, "ring": { "description": "Ring number that the client is a member of for the current chanel.", "examples": [ 1 ], "type": "integer" }, "tenantId": { "description": "Tenant ID that the configuration belongs to.", "examples": [ "a2a1698d-a3e0-42d3-96a4-47eb3e8f7dd1" ], "format": "uuid", "maxLength": 36, "minLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": [ "alphaEnabled", "channel", "ring", "tenantId" ], "title": "Update SHIELD Tenant - configuration entry", "type": "object", "examples": [ { "alphaEnabled": false, "channel": "stable", "ring": 1, "tenantId": "1d71e0fe-6e4a-464d-a690-80addf3bda55" } ] }, "TenantDetails": { "title": "Tenant Details Record", "description": "Information about a single tenant record", "properties": { "tenantId": { "description": "The object ID of the tenant record", "examples": [ "1c4d2f3b-2e4b-4a5b-8c6d-7e8f9a0b1c2d" ], "format": "uuid", "maxLength": 36, "minLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "tenantDisplayName": { "description": "Human readable name for the tenant record", "examples": [ "Contoso - Prod" ], "type": "string" }, "parentId": { "description": "The object ID of the tenant that is considered a parent to this record", "examples": [ "22354a3f-2e21-4bd2-8327-dc842cfa80c8" ], "format": "uuid", "maxLength": 36, "minLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "authorizedPrincipalList": { "description": "List of object IDs that are allowed to access this record and related data.", "type": "array", "items": { "format": "uuid", "maxLength": 36, "minLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string", "examples": [ "fd9a6a53-594d-41aa-950a-b21ff41d4688" ] }, "examples": [ [ "fd9a6a53-594d-41aa-950a-b21ff41d4688", "54fc12cd-403d-4c48-be12-86b807e958d3" ] ] } }, "type": "object", "required": [ "tenantId", "tenantDisplayName", "parentId", "authorizedPrincipalList" ], "examples": [ { "tenantId": "1c4d2f3b-2e4b-4a5b-8c6d-7e8f9a0b1c2d", "tenantDisplayName": "Contoso - Prod", "parentId": "22354a3f-2e21-4bd2-8327-dc842cfa80c8", "authorizedPrincipalList": [ "fd9a6a53-594d-41aa-950a-b21ff41d4688", "54fc12cd-403d-4c48-be12-86b807e958d3" ] } ] } }, "securitySchemes": { "EntraID": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The Access Token from Entra ID. Please note required scopes (permissions) in each endpoint." } } }, "externalDocs": { "description": "Official Documentation", "url": "https://docs.shilab.com" }, "info": { "contact": { "email": "elliot_huffman@shi.com", "name": "SHI - Lab" }, "description": "Collects data from the various SHI Lab products and makes it available in a standardized way.", "title": "SHI Data Gateway", "version": "2.3.1" }, "openapi": "3.1.1", "paths": { "/Api/Core/Health": { "get": { "description": "Check the health of the various components of the data gateway and report back. Useful for automated health probing.", "operationId": "/Api/ServiceHealth/Get", "responses": { "201": { "description": "Service is operational!" }, "500": { "description": "Service has a failure described with following report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Core.HealthReport" }, "examples": { "Auth system failure": { "summary": "Example health report - Auth failure", "description": "An example health report returned indicates the authentication components are not working.", "value": { "authClient": false, "authServer": false, "bulkStorage": true, "database": true } }, "Storage system failure": { "summary": "Example health report - Storage failure", "description": "An example health report returned indicates the storage components are not working.", "value": { "authClient": true, "authServer": true, "bulkStorage": false, "database": false } } } } } } }, "tags": [ "Core System" ], "security": [], "summary": "Health of the Service for Probing" } }, "/Api/LicenseReport": { "post": { "description": "Store the results of a license analytics run.\n\nThis endpoint requires the `LicenseReport.ReadWrite`, or `LicenseReport.ReadWrite.All` scope (permission).", "operationId": "/Api/LicenseReport/Post", "requestBody": { "content": { "application/json": { "examples": { "License Report": { "description": "Sample, truncated report from an example customer environment. The request body is the License Report that to be stored.", "summary": "Example License Report Request", "value": { "availableLicense": { "3d282045-ec7f-4813-88e2-29b74ee609f7": 123456, "5888a922-9f5b-45fd-bd5f-de3283d6a79e": 99999999, "a4b2e176-d63d-4081-9e21-226e2ac624b9": 5, "547404d4-8734-415f-a7ca-e9c1ffb95e48": 25, "d76878d6-1495-4243-a334-a82bb9818cd0": 500 }, "correlation": { "auditTenantAccount": "somebodyThatI@UsedToKnow.com" }, "licenseData": { "250844e1-a7ab-4f21-8e3f-58f51b5983a3": { "assignedLicense": { "5888a922-9f5b-45fd-bd5f-de3283d6a79e": null, "3d282045-ec7f-4813-88e2-29b74ee609f7": null }, "assignedService": { "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, "d76878d6-1495-4243-a334-a82bb9818cd0": null }, "consumedService": { "e0d101e8-6f1e-40a9-a66f-cad4112c9a59": null, "c63b7a2d-6573-4c37-9ca8-e12b954d3198": { "Something Here": true, "Other Obscure feature": false } } }, "04e88835-771a-482b-9d6f-ba06c32cbb67": { "assignedLicense": { "3d282045-ec7f-4813-88e2-29b74ee609f7": null }, "assignedService": { "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, "d76878d6-1495-4243-a334-a82bb9818cd0": null }, "consumedService": { "9d3603de-b378-4c4a-adcc-ee133cbef914": null, "e9a4e3d3-ebe0-405a-a8f4-35a04c4dba1f": { "Something Here": true, "Other Obscure feature": false } } } } } }, "Ignorant License Report Request": { "description": "Clueless dev trying to automate this application without reading the docs. RTFM!", "summary": "Ignorant License Report Request", "value": {} } }, "schema": { "$ref": "#/components/schemas/LicenseReport" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "License Report": { "description": "Sample, truncated report from an example customer environment. This will return the same report as the request input.", "summary": "Example of license report stored.", "value": { "availableLicense": { "3d282045-ec7f-4813-88e2-29b74ee609f7": 123456, "5888a922-9f5b-45fd-bd5f-de3283d6a79e": 99999999, "a4b2e176-d63d-4081-9e21-226e2ac624b9": 5, "547404d4-8734-415f-a7ca-e9c1ffb95e48": 25, "d76878d6-1495-4243-a334-a82bb9818cd0": 500 }, "correlation": { "auditTenantAccount": "somebodyThatI@example.com", "correlationId": "6d7c9271-9e68-4bdf-9ae3-f90c4213f74b", "reportTenantAccount": "usedToKnow@example.com", "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db" }, "licenseData": { "250844e1-a7ab-4f21-8e3f-58f51b5983a3": { "assignedLicense": { "5888a922-9f5b-45fd-bd5f-de3283d6a79e": null, "3d282045-ec7f-4813-88e2-29b74ee609f7": null }, "assignedService": { "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, "d76878d6-1495-4243-a334-a82bb9818cd0": null }, "consumedService": { "e0d101e8-6f1e-40a9-a66f-cad4112c9a59": null, "c63b7a2d-6573-4c37-9ca8-e12b954d3198": { "Something Here": true, "Other Obscure feature": false } } }, "04e88835-771a-482b-9d6f-ba06c32cbb67": { "assignedLicense": { "3d282045-ec7f-4813-88e2-29b74ee609f7": null }, "assignedService": { "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, "d76878d6-1495-4243-a334-a82bb9818cd0": null }, "consumedService": { "9d3603de-b378-4c4a-adcc-ee133cbef914": null, "e9a4e3d3-ebe0-405a-a8f4-35a04c4dba1f": { "Something Here": true, "Other Obscure feature": false } } } } } } }, "schema": { "$ref": "#/components/schemas/LicenseReport" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } }, "tags": [ "License Analytics" ], "summary": "Store License Analytics Data" } }, "/Api/LicenseReport/Correlation": { "get": { "description": "Retrieves the list of correlation records for the authenticated tenant. Can use filters targeting creation date to limit results. Correlation records store the metadata for a specific license report.\n\nThis endpoint requires the `LicenseReport.Read`, `LicenseReport.Read.All`, `LicenseReport.ReadWrite`, or `LicenseReport.ReadWrite.All` scope (permission).", "operationId": "/Api/LicenseReport/Correlation/Get", "parameters": [ { "$ref": "#/components/parameters/dateStart" }, { "$ref": "#/components/parameters/dateEnd" } ], "responses": { "200": { "content": { "application/json": { "examples": { "Example Correlation Records": { "description": "Sample list of correlation records for the current authenticated tenant.", "summary": "Available Correlation Records", "value": [ { "auditTenantAccount": "somebodyThatI@example.com", "correlationId": "6d7c9271-9e68-4bdf-9ae3-f90c4213f74b", "reportTenantAccount": "usedToKnow@example.com", "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", "createdAt": "2024-08-01T21:14:45.026Z", "updatedAt": "2024-08-01T21:14:45.026Z" }, { "auditTenantAccount": "somebodyThatI@example.com", "correlationId": "d8095827-a313-40e1-b086-f72636de0edf", "reportTenantAccount": "usedToKnow@example.com", "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", "createdAt": "2024-07-25T21:14:45.026Z", "updatedAt": "2024-07-25T21:14:45.026Z" } ] } }, "schema": { "type": "array", "minItems": 0, "items": { "$ref": "#/components/schemas/LicenseReport.CorrelationRecord" }, "examples": [ [ { "auditTenantAccount": "somebodyThatI@example.com", "correlationId": "6d7c9271-9e68-4bdf-9ae3-f90c4213f74b", "reportTenantAccount": "usedToKnow@example.com", "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", "createdAt": "2024-08-01T21:14:45.026Z", "updatedAt": "2024-08-01T21:14:45.026Z" }, { "auditTenantAccount": "somebodyThatI@example.com", "correlationId": "d8095827-a313-40e1-b086-f72636de0edf", "reportTenantAccount": "usedToKnow@example.com", "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", "createdAt": "2024-07-25T21:14:45.026Z", "updatedAt": "2024-07-25T21:14:45.026Z" } ] ] } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } }, "tags": [ "License Analytics" ], "summary": "Retrieve the List of Correlation Records" } }, "/Api/LicenseReport/Correlation/Tenant/{tenantId}": { "get": { "description": "Retrieves the list of correlation records for the specified tenant. Can use filters targeting creation date to limit results. Correlation records store the metadata for a specific license report.\n\nThis endpoint requires the `LicenseReport.Read.All`, or `LicenseReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", "operationId": "/Api/LicenseReport/Correlation/Tenant/:tenantId/Get", "parameters": [ { "$ref": "#/components/parameters/tenantId" }, { "$ref": "#/components/parameters/dateStart" }, { "$ref": "#/components/parameters/dateEnd" } ], "responses": { "200": { "content": { "application/json": { "examples": { "Example Correlation Records": { "description": "Sample list of correlation records for the specified tenant.", "summary": "Available Correlation Records", "value": [ { "auditTenantAccount": "somebodyThatI@example.com", "correlationId": "6d7c9271-9e68-4bdf-9ae3-f90c4213f74b", "reportTenantAccount": "usedToKnow@example.com", "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", "createdAt": "2024-08-01T21:14:45.026Z", "updatedAt": "2024-08-01T21:14:45.026Z" }, { "auditTenantAccount": "somebodyThatI@example.com", "correlationId": "d8095827-a313-40e1-b086-f72636de0edf", "reportTenantAccount": "usedToKnow@example.com", "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", "createdAt": "2024-07-25T21:14:45.026Z", "updatedAt": "2024-07-25T21:14:45.026Z" } ] } }, "schema": { "type": "array", "minItems": 0, "items": { "$ref": "#/components/schemas/LicenseReport.CorrelationRecord" }, "examples": [ [ { "auditTenantAccount": "somebodyThatI@example.com", "correlationId": "6d7c9271-9e68-4bdf-9ae3-f90c4213f74b", "reportTenantAccount": "usedToKnow@example.com", "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", "createdAt": "2024-08-01T21:14:45.026Z", "updatedAt": "2024-08-01T21:14:45.026Z" }, { "auditTenantAccount": "somebodyThatI@example.com", "correlationId": "d8095827-a313-40e1-b086-f72636de0edf", "reportTenantAccount": "usedToKnow@example.com", "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db", "createdAt": "2024-07-25T21:14:45.026Z", "updatedAt": "2024-07-25T21:14:45.026Z" } ] ] } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } }, "tags": [ "License Analytics" ], "summary": "Retrieve the List of Correlation Records for Specified Tenant" } }, "/Api/LicenseReport/Correlation/{correlationId}/Data": { "get": { "description": "Retrieves the full license report for the specified correlation ID in the authenticated tenant. The license report contains all of the license usage and compliance information with the required correlation data.\n\nThis endpoint requires the `LicenseReport.Read`, `LicenseReport.Read.All`, `LicenseReport.ReadWrite`, or `LicenseReport.ReadWrite.All` scope (permission).", "operationId": "/Api/LicenseReport/Correlation/:correlationId/Data/Get", "parameters": [ { "$ref": "#/components/parameters/correlationId" } ], "responses": { "200": { "content": { "application/json": { "examples": { "Example License Report": { "description": "Sample, truncated license report from an example customer environment for a correlation record of the current authenticated tenant.", "summary": "Example License Report", "value": { "availableLicense": { "3d282045-ec7f-4813-88e2-29b74ee609f7": 123456, "5888a922-9f5b-45fd-bd5f-de3283d6a79e": 99999999, "a4b2e176-d63d-4081-9e21-226e2ac624b9": 5, "547404d4-8734-415f-a7ca-e9c1ffb95e48": 25, "d76878d6-1495-4243-a334-a82bb9818cd0": 500 }, "correlation": { "auditTenantAccount": "somebodyThatI@example.com", "correlationId": "6d7c9271-9e68-4bdf-9ae3-f90c4213f74b", "reportTenantAccount": "usedToKnow@example.com", "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db" }, "licenseData": { "250844e1-a7ab-4f21-8e3f-58f51b5983a3": { "assignedLicense": { "5888a922-9f5b-45fd-bd5f-de3283d6a79e": null, "3d282045-ec7f-4813-88e2-29b74ee609f7": null }, "assignedService": { "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, "d76878d6-1495-4243-a334-a82bb9818cd0": null }, "consumedService": { "e0d101e8-6f1e-40a9-a66f-cad4112c9a59": null, "c63b7a2d-6573-4c37-9ca8-e12b954d3198": { "Something Here": true, "Other Obscure feature": false } } }, "04e88835-771a-482b-9d6f-ba06c32cbb67": { "assignedLicense": { "3d282045-ec7f-4813-88e2-29b74ee609f7": null }, "assignedService": { "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, "d76878d6-1495-4243-a334-a82bb9818cd0": null }, "consumedService": { "9d3603de-b378-4c4a-adcc-ee133cbef914": null, "e9a4e3d3-ebe0-405a-a8f4-35a04c4dba1f": { "Something Here": true, "Other Obscure feature": false } } } } } } }, "schema": { "$ref": "#/components/schemas/LicenseReport" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } }, "tags": [ "License Analytics" ], "summary": "Retrieve the Specified License Report" }, "delete": { "description": "Deletes the full license report for the specified correlation ID.\n\nThis endpoint requires the `LicenseReport.ReadWrite`, or `LicenseReport.ReadWrite.All` scope (permission).", "operationId": "/Api/LicenseReport/Correlation/:correlationId/Data/delete", "parameters": [ { "$ref": "#/components/parameters/correlationId" } ], "responses": { "201": { "description": "Deleted successfully" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } }, "tags": [ "License Analytics" ], "summary": "Delete the Specified License Report for the currently authenticated tenant." } }, "/Api/LicenseReport/Correlation/{correlationId}/Tenant/{tenantId}/Data": { "get": { "description": "Retrieves the full license report for the specified correlation ID and tenant. The license report contains all of the license usage and compliance information with the required correlation data.\n\nThis endpoint requires the `LicenseReport.Read.All`, or `LicenseReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", "operationId": "/Api/LicenseReport/Correlation/:correlationId/Tenant/:tenantId/Data/Get", "parameters": [ { "$ref": "#/components/parameters/correlationId" }, { "$ref": "#/components/parameters/tenantId" } ], "responses": { "200": { "content": { "application/json": { "examples": { "License Report": { "description": "Sample, truncated report from an example customer environment for a correlation record of the specified tenant.", "summary": "Example License Report", "value": { "availableLicense": { "3d282045-ec7f-4813-88e2-29b74ee609f7": 123456, "5888a922-9f5b-45fd-bd5f-de3283d6a79e": 99999999, "a4b2e176-d63d-4081-9e21-226e2ac624b9": 5, "547404d4-8734-415f-a7ca-e9c1ffb95e48": 25, "d76878d6-1495-4243-a334-a82bb9818cd0": 500 }, "correlation": { "auditTenantAccount": "somebodyThatI@example.com", "correlationId": "6d7c9271-9e68-4bdf-9ae3-f90c4213f74b", "reportTenantAccount": "usedToKnow@example.com", "tenantId": "3d6e7b7e-8d9a-4eb0-8753-67829b3934db" }, "licenseData": { "250844e1-a7ab-4f21-8e3f-58f51b5983a3": { "assignedLicense": { "5888a922-9f5b-45fd-bd5f-de3283d6a79e": null, "3d282045-ec7f-4813-88e2-29b74ee609f7": null }, "assignedService": { "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, "d76878d6-1495-4243-a334-a82bb9818cd0": null }, "consumedService": { "e0d101e8-6f1e-40a9-a66f-cad4112c9a59": null, "c63b7a2d-6573-4c37-9ca8-e12b954d3198": { "Something Here": true, "Other Obscure feature": false } } }, "04e88835-771a-482b-9d6f-ba06c32cbb67": { "assignedLicense": { "3d282045-ec7f-4813-88e2-29b74ee609f7": null }, "assignedService": { "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, "d76878d6-1495-4243-a334-a82bb9818cd0": null }, "consumedService": { "9d3603de-b378-4c4a-adcc-ee133cbef914": null, "e9a4e3d3-ebe0-405a-a8f4-35a04c4dba1f": { "Something Here": true, "Other Obscure feature": false } } } } } } }, "schema": { "$ref": "#/components/schemas/LicenseReport" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } }, "tags": [ "License Analytics" ], "summary": "Retrieve the Specified License Report for Specified Tenant" }, "delete": { "description": "Deletes the full license report for the specified correlation ID and tenant.\n\nThis endpoint requires the `LicenseReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", "operationId": "/Api/LicenseReport/Correlation/:correlationId/Tenant/:tenantId/Data/delete", "parameters": [ { "$ref": "#/components/parameters/correlationId" }, { "$ref": "#/components/parameters/tenantId" } ], "responses": { "201": { "description": "Deleted successfully" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } }, "tags": [ "License Analytics" ], "summary": "Delete the Specified License Report for Specified Tenant" } }, "/Api/Chat/LicenseGpt": { "post": { "summary": "Inquire License Data from AI Agent", "description": "Enables a conversation mode with AI agent to request details of the available license reports for the currently authenticated tenant.\n\nThis endpoint requires the `LicenseReport.Read`, `LicenseReport.ReadWrite`, `LicenseReport.Read.All`, or `LicenseReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", "operationId": "/Api/Chat/LicenseGpt/Post", "requestBody": { "content": { "application/json": { "schema": { "description": "Collection of conversation parts provided by user to be ingested by the agent", "type": "array", "items": { "$ref": "#/components/schemas/Chat.OpenAIChatMessage" } }, "examples": { "Tool call": { "summary": "Example tool call request", "description": "An example request that represent a message initiated by the chat assistant to call a tool function for the currently authenticated tenant.", "value": { "role": "assistant", "content": "What are the available IDs?", "tool_calls": [ { "id": "call_abc123", "type": "function", "function": { "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", "name": "getCorrelationIDs" } } ] } } } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "examples": [ { "messageList": [ { "role": "user", "content": "Hello" }, { "role": "assistant", "content": "Hello, how can I assist you today?" }, { "role": "user", "content": "Can you show me what correlation records I have?" }, { "role": "assistant", "content": "What are the available IDs?", "tool_calls": [ { "id": "call_abc123", "type": "function", "function": { "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", "name": "getCorrelationIDs" } } ] }, { "role": "tool", "content": "{\"825a9d7e-0b62-4392-b8ef-ab6951a46ebd\":\"2025-07-03T18:39:50.828Z\",\"744c0878-3a82-48a7-b239-a1d4b9298a69\":\"2025-07-07T21:01:20.995Z\"}", "tool_call_id": "call_abc123" }, { "role": "assistant", "content": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" } ], "responseText": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" } ], "type": "object", "properties": { "messageList": { "type": "array", "description": "List of message objects in current conversation", "items": { "$ref": "#/components/schemas/Chat.OpenAIChatMessage" }, "examples": [ [ { "role": "user", "content": "Hello" }, { "role": "assistant", "content": "Hello, how can I assist you today?" }, { "role": "user", "content": "Can you show me what correlation records I have?" }, { "role": "assistant", "content": "What are the available IDs?", "tool_calls": [ { "id": "call_abc123", "type": "function", "function": { "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", "name": "getCorrelationIDs" } } ] }, { "role": "tool", "content": "{\"825a9d7e-0b62-4392-b8ef-ab6951a46ebd\":\"2025-07-03T18:39:50.828Z\",\"744c0878-3a82-48a7-b239-a1d4b9298a69\":\"2025-07-07T21:01:20.995Z\"}", "tool_call_id": "call_abc123" }, { "role": "assistant", "content": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" } ] ] }, "responseText": { "type": "string", "description": "Most recent response text", "examples": [ "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" ] } }, "required": [ "messageList", "responseText" ] }, "examples": { "Chat response": { "summary": "Example chat response with context", "description": "An example chat response that includes context of current chat session with the request appended for the currently authenticated tenant.", "value": { "messageList": [ { "role": "user", "content": "Hello" }, { "role": "assistant", "content": "Hello, how can I assist you today?" }, { "role": "user", "content": "Can you show me what correlation records I have?" }, { "role": "assistant", "content": "What are the available IDs?", "tool_calls": [ { "id": "call_abc123", "type": "function", "function": { "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", "name": "getCorrelationIDs" } } ] }, { "role": "tool", "content": "{\"825a9d7e-0b62-4392-b8ef-ab6951a46ebd\":\"2025-07-03T18:39:50.828Z\",\"744c0878-3a82-48a7-b239-a1d4b9298a69\":\"2025-07-07T21:01:20.995Z\"}", "tool_call_id": "call_abc123" }, { "role": "assistant", "content": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" } ], "responseText": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" } } } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/400" } }, "tags": [ "Chat" ] } }, "/Api/Chat/LicenseGpt/Tenant/{tenantId}": { "post": { "summary": "Inquire License Data from AI Agent", "description": "Enables a conversation mode with AI agent to request details of the available license reports for the specified tenant.\n\nThis endpoint requires the `LicenseReport.Read.All`, or `LicenseReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", "operationId": "/Api/Chat/LicenseGpt/Tenant/:tenantId/Post", "parameters": [ { "$ref": "#/components/parameters/tenantId" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Collection of conversation parts provided by user to be ingested by the agent", "type": "array", "items": { "$ref": "#/components/schemas/Chat.OpenAIChatMessage" }, "examples": [ [ { "role": "assistant", "content": "What are the available IDs?", "tool_calls": [ { "id": "call_abc123", "type": "function", "function": { "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", "name": "getCorrelationIDs" } } ] } ] ] }, "examples": { "Chat request": { "summary": "Example chat request", "description": "An example request that represent a message initiated by the chat assistant to call a tool function for the specified tenant.", "value": [ { "role": "assistant", "content": "What are the available IDs?", "tool_calls": [ { "id": "call_abc123", "type": "function", "function": { "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", "name": "getCorrelationIDs" } } ] } ] } } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "examples": [ { "messageList": [ { "role": "user", "content": "Hello" }, { "role": "assistant", "content": "Hello, how can I assist you today?" }, { "role": "user", "content": "Can you show me what correlation records I have?" }, { "role": "assistant", "content": "What are the available IDs?", "tool_calls": [ { "id": "call_abc123", "type": "function", "function": { "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", "name": "getCorrelationIDs" } } ] }, { "role": "tool", "content": "{\"825a9d7e-0b62-4392-b8ef-ab6951a46ebd\":\"2025-07-03T18:39:50.828Z\",\"744c0878-3a82-48a7-b239-a1d4b9298a69\":\"2025-07-07T21:01:20.995Z\"}", "tool_call_id": "call_abc123" }, { "role": "assistant", "content": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" } ], "responseText": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" } ], "type": "object", "properties": { "messageList": { "type": "array", "description": "List of message objects in current conversation", "items": { "$ref": "#/components/schemas/Chat.OpenAIChatMessage" }, "examples": [ [ { "role": "user", "content": "Hello" }, { "role": "assistant", "content": "Hello, how can I assist you today?" }, { "role": "user", "content": "Can you show me what correlation records I have?" }, { "role": "assistant", "content": "What are the available IDs?", "tool_calls": [ { "id": "call_abc123", "type": "function", "function": { "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", "name": "getCorrelationIDs" } } ] }, { "role": "tool", "content": "{\"825a9d7e-0b62-4392-b8ef-ab6951a46ebd\":\"2025-07-03T18:39:50.828Z\",\"744c0878-3a82-48a7-b239-a1d4b9298a69\":\"2025-07-07T21:01:20.995Z\"}", "tool_call_id": "call_abc123" }, { "role": "assistant", "content": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" } ] ] }, "responseText": { "type": "string", "description": "Most recent response text", "examples": [ "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" ] } }, "required": [ "messageList", "responseText" ] }, "examples": { "Chat response": { "summary": "Example chat response", "description": "An example chat response that includes context of current chat session with the request appended for the specified tenant.", "value": { "messageList": [ { "role": "user", "content": "Hello" }, { "role": "assistant", "content": "Hello, how can I assist you today?" }, { "role": "user", "content": "Can you show me what correlation records I have?" }, { "role": "assistant", "content": "What are the available IDs?", "tool_calls": [ { "id": "call_abc123", "type": "function", "function": { "arguments": "{\"startDate\":\"2025-07-01\",\"endDate\":\"2025-07-10\"}", "name": "getCorrelationIDs" } } ] }, { "role": "tool", "content": "{\"825a9d7e-0b62-4392-b8ef-ab6951a46ebd\":\"2025-07-03T18:39:50.828Z\",\"744c0878-3a82-48a7-b239-a1d4b9298a69\":\"2025-07-07T21:01:20.995Z\"}", "tool_call_id": "call_abc123" }, { "role": "assistant", "content": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" } ], "responseText": "You have correlation records for the following dates:\n- July 3, 2025\n- July 7, 2025\n\nWould you like to see details from any of these correlation records?" } } } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/400" } }, "tags": [ "Chat" ] } }, "/Api/Entitlement/Shield": { "post": { "description": "Creates a new license entitlement (activation) for SHIELD.\n\nThis endpoint requires the `LicenseEntitlement.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", "operationId": "/Api/Entitlement/Shield/Post", "requestBody": { "content": { "application/json": { "examples": { "Specialized Purchase": { "description": "Add-on purchase for the specified customer for some additional specialized licenses.", "summary": "Specialized Purchase", "value": { "enterpriseDeviceCount": 0, "enterpriseInterfaceCount": 0, "enterpriseIntermediaryCount": 0, "enterpriseUserCount": 0, "notValidAfter": "2024-07-30T18:09:05.970Z", "notValidBefore": "1970-01-01T00:00:00.000Z", "privilegedDeviceCount": 0, "privilegedInterfaceCount": 0, "privilegedIntermediaryCount": 0, "privilegedUserCount": 0, "purchaseId": "ABC123", "specializedDeviceCount": 50, "specializedInterfaceCount": 3, "specializedIntermediaryCount": 1, "specializedUserCount": 50, "tenantId": "4b00fb78-d291-4dbd-8c0a-c93ae20bffd1" } }, "Initial Purchase": { "description": "Complete suite of components purchased for the specified customer.", "summary": "Initial Purchase", "value": { "enterpriseDeviceCount": 7000, "enterpriseInterfaceCount": 500, "enterpriseIntermediaryCount": 10, "enterpriseUserCount": 7000, "notValidAfter": "2024-07-30T18:12:23.049Z", "notValidBefore": "1970-01-01T00:00:00.000Z", "privilegedDeviceCount": 200, "privilegedInterfaceCount": 50, "privilegedIntermediaryCount": 3, "privilegedUserCount": 200, "purchaseId": "654DEF", "specializedDeviceCount": 1000, "specializedInterfaceCount": 11, "specializedIntermediaryCount": 2, "specializedUserCount": 1000, "tenantId": "58ffb93f-5098-4630-bfc4-eeb4664208b4" } }, "Ignorant Entitlement Creation Request": { "description": "Clueless dev trying to automate this application without reading the docs. RTFM!", "summary": "Ignorant Entitlement Creation Request", "value": {} } }, "schema": { "$ref": "#/components/schemas/LicenseEntitlement.Shield" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Small MSP": { "description": "Example license entitlement for a small MSP.", "summary": "Local MSP", "value": { "correlationId": "60594489-6022-4ddb-8aa5-288c8d356cf2", "enterpriseDeviceCount": 25, "enterpriseInterfaceCount": 25, "enterpriseIntermediaryCount": 25, "enterpriseUserCount": 25, "notValidAfter": "2024-07-30T17:56:00.704Z", "notValidBefore": "1970-01-01T00:00:00.000Z", "privilegedDeviceCount": 10, "privilegedInterfaceCount": 10, "privilegedIntermediaryCount": 2, "privilegedUserCount": 10, "purchaseId": "Bob's your mother's brother.", "specializedDeviceCount": 5, "specializedInterfaceCount": 5, "specializedIntermediaryCount": 0, "specializedUserCount": 5, "tenantId": "1948adeb-797f-466b-962d-cc708a69d08d" } }, "Enterprise": { "description": "Example license entitlement for an enterprise sized company.", "summary": "Enterprise", "value": { "correlationId": "46569e8d-eeaa-42f4-b954-05a998108eee", "enterpriseDeviceCount": 50000, "enterpriseInterfaceCount": 50000, "enterpriseIntermediaryCount": 100, "enterpriseUserCount": 50000, "notValidAfter": "2024-07-30T17:58:54.619Z", "notValidBefore": "1970-01-01T00:00:00.000Z", "privilegedDeviceCount": 300, "privilegedInterfaceCount": 100, "privilegedIntermediaryCount": 50, "privilegedUserCount": 300, "purchaseId": "Bob's your mother's brother.", "specializedDeviceCount": 1000, "specializedInterfaceCount": 5, "specializedIntermediaryCount": 10, "specializedUserCount": 1000, "tenantId": "bf78263c-6cec-44bc-9893-024dde25a486" } } }, "schema": { "$ref": "#/components/schemas/LicenseEntitlement.Shield" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } }, "tags": [ "License Entitlement" ], "summary": "Creates a new License Entitlement for SHIELD." } }, "/Api/Entitlement/Shield/Active": { "get": { "description": "Retrieves the count of licenses that are available to the authenticated tenant. No scopes (permissions) required.", "operationId": "/Api/Entitlement/Shield/Active/Get", "responses": { "200": { "content": { "application/json": { "examples": { "Small MSP": { "description": "Example active license count for a small MSP for the currently authenticated tenant.", "summary": "Local MSP", "value": { "enterpriseDeviceCount": 54, "enterpriseInterfaceCount": 46, "enterpriseIntermediaryCount": 2, "enterpriseUserCount": 54, "privilegedDeviceCount": 12, "privilegedInterfaceCount": 52, "privilegedIntermediaryCount": 4, "privilegedUserCount": 12, "specializedDeviceCount": 20, "specializedInterfaceCount": 15, "specializedIntermediaryCount": 0, "specializedUserCount": 20 } }, "No Licenses": { "description": "Example license count for a company that doesn't have any licenses for the currently authenticated tenant..", "summary": "No License", "value": { "enterpriseDeviceCount": 0, "enterpriseInterfaceCount": 0, "enterpriseIntermediaryCount": 0, "enterpriseUserCount": 0, "privilegedDeviceCount": 0, "privilegedInterfaceCount": 0, "privilegedIntermediaryCount": 0, "privilegedUserCount": 0, "specializedDeviceCount": 0, "specializedInterfaceCount": 0, "specializedIntermediaryCount": 0, "specializedUserCount": 0 } }, "Enterprise": { "description": "Example active license count for an enterprise sized company for the currently authenticated tenant..", "summary": "Enterprise", "value": { "enterpriseDeviceCount": 60000, "enterpriseInterfaceCount": 500, "enterpriseIntermediaryCount": 20, "enterpriseUserCount": 60000, "privilegedDeviceCount": 200, "privilegedInterfaceCount": 450, "privilegedIntermediaryCount": 15, "privilegedUserCount": 200, "specializedDeviceCount": 1000, "specializedInterfaceCount": 50, "specializedIntermediaryCount": 2, "specializedUserCount": 1000 } } }, "schema": { "$ref": "#/components/schemas/LicenseEntitlement.Shield.Count" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/401" } }, "tags": [ "License Entitlement" ], "summary": "List of Available Licenses" } }, "/Api/Entitlement/Shield/Tenant/{tenantId}": { "get": { "description": "Retrieves the list of license entitlements that are assigned to the specified tenant.\n\nThis endpoint requires the `LicenseEntitlement.Read.All`, or `LicenseEntitlement.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", "operationId": "/Api/Entitlement/Shield/Tenant/:tenantId/Get", "parameters": [ { "$ref": "#/components/parameters/tenantId" } ], "summary": "List of Entitlement Records for Specified Tenant", "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "minItems": 0, "items": { "$ref": "#/components/schemas/LicenseEntitlement.Shield" }, "examples": [ [ { "correlationId": "e097a3f5-9599-44a2-8923-fd3276c83ae1", "enterpriseDeviceCount": 5, "enterpriseInterfaceCount": 6, "enterpriseIntermediaryCount": 7, "enterpriseUserCount": 8, "notValidAfter": "2024-07-30T17:35:24.044Z", "notValidBefore": "2024-07-30T17:37:15.300Z", "privilegedDeviceCount": 9, "privilegedInterfaceCount": 10, "privilegedIntermediaryCount": 11, "privilegedUserCount": 12, "purchaseId": "any arbitrary string as purchaseId", "specializedDeviceCount": 13, "specializedInterfaceCount": 14, "specializedIntermediaryCount": 15, "specializedUserCount": 15, "tenantId": "a2a1698d-a3e0-42d3-96a4-47eb3e8f7dd1" } ] ] }, "examples": { "Example Purchase": { "summary": "Example entitlement purchase", "description": "An example SHIELD entitlement for the specified tenant.", "value": [ { "correlationId": "e097a3f5-9599-44a2-8923-fd3276c83ae1", "enterpriseDeviceCount": 5, "enterpriseInterfaceCount": 6, "enterpriseIntermediaryCount": 7, "enterpriseUserCount": 8, "notValidAfter": "2024-07-30T17:35:24.044Z", "notValidBefore": "2024-07-30T17:37:15.300Z", "privilegedDeviceCount": 9, "privilegedInterfaceCount": 10, "privilegedIntermediaryCount": 11, "privilegedUserCount": 12, "purchaseId": "any arbitrary string as purchaseId", "specializedDeviceCount": 13, "specializedInterfaceCount": 14, "specializedIntermediaryCount": 15, "specializedUserCount": 15, "tenantId": "a2a1698d-a3e0-42d3-96a4-47eb3e8f7dd1" } ] } } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } }, "tags": [ "License Entitlement" ] } }, "/Api/Entitlement/Shield/Tenant/{tenantId}/Correlation/{correlationId}": { "delete": { "description": "Deletes the requested SHIELD license entitlement record.\n\nThis endpoint requires the `LicenseEntitlement.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", "operationId": "/Api/Entitlement/Shield/Tenant/:tenantId/Correlation/:correlationId/Delete", "parameters": [ { "$ref": "#/components/parameters/tenantId" }, { "$ref": "#/components/parameters/correlationId" } ], "summary": "Delete Specified License Entitlement", "responses": { "201": { "description": "Deleted Successfully" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } }, "tags": [ "License Entitlement" ] } }, "/Api/Telemetry/Shield": { "post": { "description": "Submits the telemetry report for SHIELD.\n\nThis endpoint requires the `Telemetry.Shield.ReadWrite`, or `Telemetry.Shield.ReadWrite.All` scope (permission).", "operationId": "/Api/Telemetry/Shield/Post", "requestBody": { "content": { "application/json": { "examples": { "Monthly Report": { "description": "Example monthly telemetry report for an enterprise organization.", "summary": "Monthly Report", "value": { "enterpriseDeviceCount": 64221, "enterpriseInterfaceCount": 523, "enterpriseIntermediaryCount": 44, "enterpriseUserCount": 642219, "monthlyActiveEntUsers": 0, "monthlyActivePrivUsers": 0, "monthlyActiveSpecUsers": 0, "privilegedDeviceCount": 50, "privilegedInterfaceCount": 2000, "privilegedIntermediaryCount": 25, "privilegedUserCount": 50, "shieldArchitectureVersion": "2", "shieldCoreVersion": "3.0.0", "specializedDeviceCount": 0, "specializedInterfaceCount": 612, "specializedIntermediaryCount": 2, "specializedUserCount": 5238 } } }, "schema": { "$ref": "#/components/schemas/Telemetry.Shield" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Monthly Report": { "description": "An example of latest monthly telemetry report for an enterprise organization after the latest telemetry input.", "summary": "Updated Monthly Report", "value": { "correlationId": "6fe3cd30-931c-439a-b759-1e7f3a73622e", "enterpriseDeviceCount": 64221, "enterpriseInterfaceCount": 523, "enterpriseIntermediaryCount": 44, "enterpriseUserCount": 642219, "monthlyActiveEntUsers": 0, "monthlyActivePrivUsers": 0, "monthlyActiveSpecUsers": 0, "privilegedDeviceCount": 50, "privilegedInterfaceCount": 2000, "privilegedIntermediaryCount": 25, "privilegedUserCount": 50, "shieldArchitectureVersion": "2", "shieldCoreVersion": "3.0.0", "specializedDeviceCount": 0, "specializedInterfaceCount": 612, "specializedIntermediaryCount": 2, "specializedUserCount": 5238, "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", "createdAt": "2024-08-05T15:25:55.525Z", "updatedAt": "2024-08-05T15:25:55.525Z" } } }, "schema": { "$ref": "#/components/schemas/Telemetry.Shield" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } }, "tags": [ "Telemetry" ], "summary": "Collects SHIELD Telemetry" }, "get": { "description": "Retrieves the telemetry records that have been reported for the authenticated tenant. Data is not guaranteed to be retrieved in any specific order.\n\nThis endpoint requires the `Telemetry.Shield.Read`, `Telemetry.Shield.Read.All`, `Telemetry.Shield.ReadWrite`, or `Telemetry.Shield.ReadWrite.All` scope (permission).", "operationId": "/Api/Telemetry/Shield/Get", "responses": { "200": { "content": { "application/json": { "examples": { "List of Reports": { "description": "List of all available SHIELD telemetry reports for the current authenticated tenant.", "summary": "List of SHIELD telemetry reports", "value": [ { "correlationId": "6fe3cd30-931c-439a-b759-1e7f3a73622e", "enterpriseDeviceCount": 64221, "enterpriseInterfaceCount": 523, "enterpriseIntermediaryCount": 44, "enterpriseUserCount": 642219, "monthlyActiveEntUsers": 0, "monthlyActivePrivUsers": 0, "monthlyActiveSpecUsers": 0, "privilegedDeviceCount": 50, "privilegedInterfaceCount": 2000, "privilegedIntermediaryCount": 25, "privilegedUserCount": 50, "shieldArchitectureVersion": "2", "shieldCoreVersion": "3.0.0", "specializedDeviceCount": 0, "specializedInterfaceCount": 612, "specializedIntermediaryCount": 2, "specializedUserCount": 5238, "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", "createdAt": "2024-08-05T15:25:55.525Z", "updatedAt": "2024-08-05T15:25:55.525Z" }, { "correlationId": "a57d03c6-8218-4738-b860-ac158e257e27", "enterpriseDeviceCount": 63221, "enterpriseInterfaceCount": 523, "enterpriseIntermediaryCount": 44, "enterpriseUserCount": 632219, "monthlyActiveEntUsers": 0, "monthlyActivePrivUsers": 0, "monthlyActiveSpecUsers": 0, "privilegedDeviceCount": 50, "privilegedInterfaceCount": 2000, "privilegedIntermediaryCount": 25, "privilegedUserCount": 50, "shieldArchitectureVersion": "2", "shieldCoreVersion": "3.0.0", "specializedDeviceCount": 0, "specializedInterfaceCount": 612, "specializedIntermediaryCount": 2, "specializedUserCount": 5238, "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", "createdAt": "2024-07-05T15:25:55.525Z", "updatedAt": "2024-07-05T15:25:55.525Z" } ] } }, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Telemetry.Shield" }, "minItems": 0, "examples": [ [ { "correlationId": "6fe3cd30-931c-439a-b759-1e7f3a73622e", "enterpriseDeviceCount": 64221, "enterpriseInterfaceCount": 523, "enterpriseIntermediaryCount": 44, "enterpriseUserCount": 642219, "monthlyActiveEntUsers": 0, "monthlyActivePrivUsers": 0, "monthlyActiveSpecUsers": 0, "privilegedDeviceCount": 50, "privilegedInterfaceCount": 2000, "privilegedIntermediaryCount": 25, "privilegedUserCount": 50, "shieldArchitectureVersion": "2", "shieldCoreVersion": "3.0.0", "specializedDeviceCount": 0, "specializedInterfaceCount": 612, "specializedIntermediaryCount": 2, "specializedUserCount": 5238, "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", "createdAt": "2024-08-05T15:25:55.525Z", "updatedAt": "2024-08-05T15:25:55.525Z" }, { "correlationId": "a57d03c6-8218-4738-b860-ac158e257e27", "enterpriseDeviceCount": 63221, "enterpriseInterfaceCount": 523, "enterpriseIntermediaryCount": 44, "enterpriseUserCount": 632219, "monthlyActiveEntUsers": 0, "monthlyActivePrivUsers": 0, "monthlyActiveSpecUsers": 0, "privilegedDeviceCount": 50, "privilegedInterfaceCount": 2000, "privilegedIntermediaryCount": 25, "privilegedUserCount": 50, "shieldArchitectureVersion": "2", "shieldCoreVersion": "3.0.0", "specializedDeviceCount": 0, "specializedInterfaceCount": 612, "specializedIntermediaryCount": 2, "specializedUserCount": 5238, "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", "createdAt": "2024-07-05T15:25:55.525Z", "updatedAt": "2024-07-05T15:25:55.525Z" } ] ] } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } }, "summary": "Lists Reported Telemetry", "tags": [ "Telemetry" ] } }, "/Api/Telemetry/Shield/Tenant/{tenantId}": { "get": { "description": "Retrieves the telemetry records that have been reported for the specified tenant. Data is not guaranteed to be retrieved in any specific order.\n\nThis endpoint requires the `Telemetry.Shield.Read.All`, or `Telemetry.Shield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", "operationId": "/Api/Telemetry/Shield/Tenant/:tenantId/Get", "parameters": [ { "$ref": "#/components/parameters/tenantId" } ], "responses": { "200": { "content": { "application/json": { "examples": { "List of Reports": { "description": "List of all available SHIELD telemetry reports for the specified tenant.", "summary": "List of SHIELD telemetry reports", "value": [ { "correlationId": "6fe3cd30-931c-439a-b759-1e7f3a73622e", "enterpriseDeviceCount": 64221, "enterpriseInterfaceCount": 523, "enterpriseIntermediaryCount": 44, "enterpriseUserCount": 642219, "monthlyActiveEntUsers": 0, "monthlyActivePrivUsers": 0, "monthlyActiveSpecUsers": 0, "privilegedDeviceCount": 50, "privilegedInterfaceCount": 2000, "privilegedIntermediaryCount": 25, "privilegedUserCount": 50, "shieldArchitectureVersion": "2", "shieldCoreVersion": "3.0.0", "specializedDeviceCount": 0, "specializedInterfaceCount": 612, "specializedIntermediaryCount": 2, "specializedUserCount": 5238, "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", "createdAt": "2024-08-05T15:25:55.525Z", "updatedAt": "2024-08-05T15:25:55.525Z" }, { "correlationId": "a57d03c6-8218-4738-b860-ac158e257e27", "enterpriseDeviceCount": 63221, "enterpriseInterfaceCount": 523, "enterpriseIntermediaryCount": 44, "enterpriseUserCount": 632219, "monthlyActiveEntUsers": 0, "monthlyActivePrivUsers": 0, "monthlyActiveSpecUsers": 0, "privilegedDeviceCount": 50, "privilegedInterfaceCount": 2000, "privilegedIntermediaryCount": 25, "privilegedUserCount": 50, "shieldArchitectureVersion": "2", "shieldCoreVersion": "3.0.0", "specializedDeviceCount": 0, "specializedInterfaceCount": 612, "specializedIntermediaryCount": 2, "specializedUserCount": 5238, "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", "createdAt": "2024-07-05T15:25:55.525Z", "updatedAt": "2024-07-05T15:25:55.525Z" } ] } }, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Telemetry.Shield" }, "minItems": 0, "examples": [ [ { "correlationId": "6fe3cd30-931c-439a-b759-1e7f3a73622e", "enterpriseDeviceCount": 64221, "enterpriseInterfaceCount": 523, "enterpriseIntermediaryCount": 44, "enterpriseUserCount": 642219, "monthlyActiveEntUsers": 0, "monthlyActivePrivUsers": 0, "monthlyActiveSpecUsers": 0, "privilegedDeviceCount": 50, "privilegedInterfaceCount": 2000, "privilegedIntermediaryCount": 25, "privilegedUserCount": 50, "shieldArchitectureVersion": "2", "shieldCoreVersion": "3.0.0", "specializedDeviceCount": 0, "specializedInterfaceCount": 612, "specializedIntermediaryCount": 2, "specializedUserCount": 5238, "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", "createdAt": "2024-08-05T15:25:55.525Z", "updatedAt": "2024-08-05T15:25:55.525Z" }, { "correlationId": "a57d03c6-8218-4738-b860-ac158e257e27", "enterpriseDeviceCount": 63221, "enterpriseInterfaceCount": 523, "enterpriseIntermediaryCount": 44, "enterpriseUserCount": 632219, "monthlyActiveEntUsers": 0, "monthlyActivePrivUsers": 0, "monthlyActiveSpecUsers": 0, "privilegedDeviceCount": 50, "privilegedInterfaceCount": 2000, "privilegedIntermediaryCount": 25, "privilegedUserCount": 50, "shieldArchitectureVersion": "2", "shieldCoreVersion": "3.0.0", "specializedDeviceCount": 0, "specializedInterfaceCount": 612, "specializedIntermediaryCount": 2, "specializedUserCount": 5238, "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", "createdAt": "2024-07-05T15:25:55.525Z", "updatedAt": "2024-07-05T15:25:55.525Z" } ] ] } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } }, "summary": "Retrieves Telemetry for Specified Tenant", "tags": [ "Telemetry" ] } }, "/Api/Telemetry/Shield/Tenant/{tenantId}/Correlation/{correlationId}": { "delete": { "description": "Deletes the specified telemetry record for the specified tenant.\n\nThis endpoint requires the `Telemetry.Shield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", "operationId": "/Api/Telemetry/Shield/Tenant/:tenantId/Correlation/:correlationId/Delete", "parameters": [ { "$ref": "#/components/parameters/tenantId" }, { "$ref": "#/components/parameters/correlationId" } ], "responses": { "201": { "description": "Deleted Successfully" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } }, "summary": "Delete Specified Telemetry Record", "tags": [ "Telemetry" ] } }, "/Api/Update/Shield/Channel": { "get": { "description": "Retrieves all of the channel configurations that are present in the update service.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", "operationId": "/Api/Update/Shield/Channel/Get", "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Update.Shield.Channel" }, "examples": [ [ { "latest": "1.12.5", "name": "stable", "previous": "1.12.4" } ] ] }, "examples": { "Channel configuration": { "summary": "Example all channel configs", "description": "An example showing the all channel configurations.", "value": [ { "latest": "1.12.5", "name": "stable", "previous": "1.12.4" }, { "latest": "1.12.7", "name": "alpha", "previous": "1.12.6" }, { "latest": "1.12.6", "name": "beta", "previous": "1.12.5" } ] } } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, "summary": "Retrieves All Channel Configurations", "tags": [ "SHIELD - Update" ] } }, "/Api/Update/Shield/Channel/{channelName}": { "get": { "description": "Retrieves configuration for the specific channel from the update service.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", "operationId": "/Api/Update/Shield/Channel/:channelName/Get", "parameters": [ { "$ref": "#/components/parameters/channelName" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Update.Shield.Channel" }, "examples": { "Stable channel config": { "summary": "Example stable channel config", "description": "An example showing the stable update channel configuration.", "value": { "latest": "1.12.5", "name": "stable", "previous": "1.12.4" } }, "Alpha channel config": { "summary": "Example alpha channel config", "description": "An example showing the alpha update channel configuration.", "value": { "latest": "1.12.7", "name": "alpha", "previous": "1.12.6" } } } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, "summary": "Retrieves Specific Channel Configuration", "tags": [ "SHIELD - Update" ] }, "patch": { "description": "Updates (or adds when missing) the specified channel configuration.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", "operationId": "/Api/Update/Shield/Channel/:channelName/Patch", "parameters": [ { "$ref": "#/components/parameters/channelName" } ], "requestBody": { "content": { "application/json": { "examples": { "Channel Configuration Details": { "description": "Example channel configuration object that will add/update for specified channel.", "summary": "Channel Configuration", "value": { "latest": "1.12.5", "previous": "1.12.4" } } }, "schema": { "type": "object", "properties": { "latest": { "description": "Version number of the latest update available to the chanel.", "examples": [ "1.12.5" ], "type": "string" }, "previous": { "description": "Version number of the number that is being replaced via ring deployment, available to all rings at the minimum.", "examples": [ "1.12.14" ], "type": "string" } }, "examples": [ { "latest": "1.12.5", "previous": "1.12.4" } ] } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Channel Configuration Details": { "description": "Example object returned on creation or update.", "summary": "Channel Configuration", "value": { "latest": "1.12.5", "name": "stable", "previous": "1.12.4" } } }, "schema": { "$ref": "#/components/schemas/Update.Shield.Channel" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, "summary": "Upserts Channel Configuration", "tags": [ "SHIELD - Update" ] }, "delete": { "description": "Deletes the specified channel configuration and associated rings.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", "operationId": "/Api/Update/Shield/Channel/:channelName/Delete", "parameters": [ { "$ref": "#/components/parameters/channelName" } ], "responses": { "204": { "description": "Deleted Successfully" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, "summary": "Deletes the Specified Channel", "tags": [ "SHIELD - Update" ] } }, "/Api/Update/Shield/Channel/{channelName}/Ring": { "get": { "description": "Retrieves all of the ring configurations for a channel that are present in the update service.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", "operationId": "/Api/Update/Shield/Channel/:channelName/Ring/Get", "parameters": [ { "$ref": "#/components/parameters/channelName" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Update.Shield.Channel.Ring" }, "examples": [ [ { "latest": true, "number": 1 } ] ] }, "examples": { "All ring config": { "summary": "Example all ring configs", "description": "An example showing the configurations of all rings of the specified channel.", "value": [ { "latest": true, "number": 1 }, { "latest": false, "number": 0 } ] } } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, "summary": "Retrieves All Ring Configurations", "tags": [ "SHIELD - Update" ] } }, "/Api/Update/Shield/Channel/{channelName}/Ring/{number}": { "get": { "description": "Retrieves configuration for the specific channel ring from the update service.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", "operationId": "/Api/Update/Shield/Channel/:channelName/Ring/:number/Get", "parameters": [ { "$ref": "#/components/parameters/channelName" }, { "$ref": "#/components/parameters/channelRing" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Update.Shield.Channel.Ring" }, "examples": { "Sample ring config": { "summary": "Example ring configuration", "description": "An example ring configuration for the specified channel and ring.", "value": { "latest": true, "number": 1 } } } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, "summary": "Retrieves Specific Channel Ring Configuration", "tags": [ "SHIELD - Update" ] }, "patch": { "description": "Updates (or adds when missing) channel ring configuration.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", "operationId": "/Api/Update/Shield/Channel/:channelName/Ring/:number/Patch", "parameters": [ { "$ref": "#/components/parameters/channelName" }, { "$ref": "#/components/parameters/channelRing" } ], "requestBody": { "content": { "application/json": { "examples": { "Channel Ring Configuration Details": { "description": "Example channel ring configuration object.", "summary": "Channel Ring Configuration", "value": { "latest": true } } }, "schema": { "type": "object", "properties": { "latest": { "description": "Flag that indicates if the ring should be operating off of the latest version number provided by the channel (`true`) or the previous (`false`).", "examples": [ true ], "type": "boolean" } }, "examples": [ { "latest": false } ] } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Channel Ring Configuration Details": { "description": "Example object returned on creation or update.", "summary": "Channel Ring Configuration", "value": { "latest": true, "number": 1 } } }, "schema": { "$ref": "#/components/schemas/Update.Shield.Channel.Ring" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, "summary": "Modifies Specific Channel Ring Configuration", "tags": [ "SHIELD - Update" ] }, "delete": { "description": "Deletes configuration of the specific channel ring.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", "operationId": "/Api/Update/Shield/Channel/:channelName/Ring/:number/Delete", "parameters": [ { "$ref": "#/components/parameters/channelName" }, { "$ref": "#/components/parameters/channelRing" } ], "responses": { "204": { "description": "Deleted Successfully" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, "summary": "Deletes Specific Channel Ring Configuration", "tags": [ "SHIELD - Update" ] } }, "/Api/Update/Shield/Channel/{channelName}/Version/{version}": { "post": { "description": "Uploads new version of the update package for SHIELD in a specific channel.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", "operationId": "/Api/Update/Shield/Channel/:channelName/Version/:version/Post", "parameters": [ { "$ref": "#/components/parameters/channelName" }, { "$ref": "#/components/parameters/version" } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "204": { "description": "OK" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, "summary": "Uploads New Application Package", "tags": [ "SHIELD - Update" ] } }, "/Api/Update/Shield/Check": { "get": { "description": "Retrieves the latest available version of the package for the running application. Version depends on the channel associated with the current tenant, or channel mentioned in the request, or default channel value. Applicable channel would be calculated on the server for each request.", "operationId": "/Api/Update/Shield/Check/Get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Update.Shield.Check" }, "examples": { "Latest package version": { "summary": "Example latest application version", "description": "An example showing the latest SHIELD package available.", "value": { "updateVersion": "1.12.5" } } } } }, "description": "OK" }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, "summary": "Retrieves Latest Application Version Number", "tags": [ "SHIELD - Update" ] } }, "/Api/Update/Shield/Check/Channel/{channelName}": { "get": { "description": "Retrieves the latest available version of the package for the running application for the specific channel.", "operationId": "/Api/Update/Shield/Check/Channel/:channelName/Get", "parameters": [ { "$ref": "#/components/parameters/channelName" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Update.Shield.Check" }, "examples": { "Latest package version": { "summary": "Example latest application version", "description": "An example showing the latest SHIELD package available for the specified channel.", "value": { "updateVersion": "1.12.5" } } } } }, "description": "OK" }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, "summary": "Retrieves Application Version Number For Specific Channel", "tags": [ "SHIELD - Update" ] } }, "/Api/Update/Shield/Download": { "get": { "description": "Sends a stream of the ZIP archive content to be saved that represents requested application update package.", "operationId": "/Api/Update/Shield/Download/Get", "responses": { "200": { "description": "OK", "content": { "application/zip": { "schema": { "type": "string", "format": "binary", "examples": [ "UEsDBBQAAAAIAAeLbU0AAAAAAAAAAAAAAAAJAAQATm90ZS50eHRVVAkAA1V2YV... (truncated)" ] }, "examples": { "base64-inline": { "summary": "Base64-encoded ZIP)", "description": "Base64 encoding of a small ZIP (truncated) to simulate a update package binary string for the channel specified.", "value": "UEsDBBQAAAAIAAeLbU0AAAAAAAAAAAAAAAAJAAQATm90ZS50eHRVVAkAA1V2YV... (truncated)" } } } } }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, "summary": "Streams File Content To Download", "tags": [ "SHIELD - Update" ] } }, "/Api/Update/Shield/Download/Channel/{channelName}": { "get": { "description": "Sends a stream of the ZIP archive content to be saved that represents requested application update package for the specific channel.", "operationId": "/Api/Update/Shield/Download/Channel/:channelName/Get", "parameters": [ { "$ref": "#/components/parameters/channelName" } ], "responses": { "200": { "description": "OK", "content": { "application/zip": { "schema": { "type": "string", "format": "binary", "examples": [ "UEsDBBQAAAAIAAeLbU0AAAAAAAAAAAAAAAAJAAQATm90ZS50eHRVVAkAA1V2YV... (truncated)" ] }, "examples": { "base64-inline": { "summary": "Base64-encoded ZIP", "description": "Base64 encoding of a small ZIP (truncated) to simulate a update package binary string for the channel specified.", "value": "UEsDBBQAAAAIAAeLbU0AAAAAAAAAAAAAAAAJAAQATm90ZS50eHRVVAkAA1V2YV... (truncated)" } } } } }, "403": { "$ref": "#/components/responses/403" }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, "summary": "Streams File Content From Specific Channel To Download", "tags": [ "SHIELD - Update" ] } }, "/Api/Update/Shield/Tenant": { "get": { "description": "Retrieves all tenant configurations present in the update service.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", "operationId": "/Api/Update/Shield/Tenant/Get", "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Update.Shield.Tenant" }, "examples": [ [ { "alphaEnabled": false, "channel": "stable", "ring": 1, "tenantId": "1d71e0fe-6e4a-464d-a690-80addf3bda55" } ] ] }, "examples": { "All tenant list": { "summary": "Example all tenant list", "description": "A example truncated list of all tenant configurations that present in the update service.", "value": [ { "alphaEnabled": false, "channel": "stable", "ring": 1, "tenantId": "1d71e0fe-6e4a-464d-a690-80addf3bda55" } ] } } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, "summary": "Retrieves All Tenant Configurations", "tags": [ "SHIELD - Update" ] } }, "/Api/Update/Shield/Tenant/{tenantId}": { "get": { "description": "Retrieves configuration for the specific tenant from the update service.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", "operationId": "/Api/Update/Shield/Tenant/:tenantId/Get", "parameters": [ { "$ref": "#/components/parameters/tenantId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Update.Shield.Tenant" }, "examples": { "Tenant config": { "summary": "Example tenant config", "description": "A example configurations that present in the update service of the specified tenant.", "value": { "alphaEnabled": false, "channel": "stable", "ring": 1, "tenantId": "1d71e0fe-6e4a-464d-a690-80addf3bda55" } } } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, "summary": "Retrieves Specific Tenant Configuration", "tags": [ "SHIELD - Update" ] }, "patch": { "description": "Updates (or adds when missing) tenant configuration.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", "operationId": "/Api/Update/Shield/Tenant/:tenantId/Patch", "parameters": [ { "$ref": "#/components/parameters/tenantId" } ], "requestBody": { "content": { "application/json": { "examples": { "Tenant Configuration Details": { "description": "Example tenant configuration object.", "summary": "Tenant Configuration", "value": { "alphaEnabled": false, "channel": "stable", "ring": 1 } } }, "schema": { "type": "object", "properties": { "alphaEnabled": { "description": "Flag that indicates if the current tenant is allowed to request alpha builds (`true`) or not (`false`).", "examples": [ false ], "type": "boolean" }, "channel": { "description": "Name of the deploy channel.", "examples": [ "stable" ], "type": "string" }, "ring": { "description": "Ring number that the client is a member of for the current chanel.", "examples": [ 1 ], "type": "integer" } }, "examples": [ { "alphaEnabled": false, "channel": "stable", "ring": 1 } ] } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Tenant Configuration Details": { "description": "Example object returned on creation or update with tenantId set.", "summary": "Tenant Configuration", "value": { "alphaEnabled": false, "channel": "stable", "ring": 1, "tenantId": "a2a1698d-a3e0-42d3-96a4-47eb3e8f7dd1" } } }, "schema": { "$ref": "#/components/schemas/Update.Shield.Tenant" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, "summary": "Upserts Specific Tenant Configuration", "tags": [ "SHIELD - Update" ] }, "delete": { "description": "Deletes configuration for the specific tenant.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", "operationId": "/Api/Update/Shield/Tenant/:tenantId/Delete", "parameters": [ { "$ref": "#/components/parameters/tenantId" } ], "responses": { "204": { "description": "Deleted Successfully" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, "summary": "Deletes Specific Tenant Configuration", "tags": [ "SHIELD - Update" ] } }, "/Api/Tenant": { "get": { "description": "Retrieves the list of tenant records. Can use filter by parent ID limit the results. This endpoint requires the `Tenant.Read.All` or `Tenant.ReadWrite.All` scopes (permissions).", "operationId": "/Api/Tenant/Get", "parameters": [ { "$ref": "#/components/parameters/parentId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "minItems": 0, "items": { "$ref": "#/components/schemas/TenantDetails" }, "examples": [ [ { "tenantId": "7e8f9a0b-1c2d-3e4b-5a6c-7d8e9f0a1b2c", "displayName": "Contoso - R&D", "parentId": "f3ed1efc-4e62-46b8-bf2a-6b59ca9784e5", "authorizedPrincipalList": [] } ] ] }, "examples": { "Example List Of Multiple Tenant Records": { "description": "Sample list of multiple tenant records in the database", "summary": "Multiple Tenant Records", "value": [ { "tenantId": "5d6e7f8a-9b0c-1d2e-3f4a-5b6c7d8e9f0a", "displayName": "Contoso - Legal", "parentId": "f3ed1efc-4e62-46b8-bf2a-6b59ca9784e5", "authorizedPrincipalList": [ "59673771-3b4f-4518-9187-aee8a51c8c07", "47c42971-2dea-4553-a788-d29a42e3e867" ] }, { "tenantId": "7e8f9a0b-1c2d-3e4b-5a6c-7d8e9f0a1b2c", "displayName": "Contoso - R&D", "parentId": "f3ed1efc-4e62-46b8-bf2a-6b59ca9784e5", "authorizedPrincipalList": [ "7e9ce415-32b2-4e7a-a920-d4dbaae022e3" ] } ] }, "Example List Of Single Tenant Record": { "description": "Example list of single tenant records which no user is authorized yet.", "summary": "Single Tenant Records", "value": [ { "tenantId": "7e8f9a0b-1c2d-3e4b-5a6c-7d8e9f0a1b2c", "displayName": "Contoso - R&D", "parentId": "f3ed1efc-4e62-46b8-bf2a-6b59ca9784e5", "authorizedPrincipalList": [] } ] } } } }, "description": "OK" }, "404": { "$ref": "#/components/responses/404" }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, "summary": "Retrieves List of Tenant Records", "tags": [ "Tenant Records" ] } }, "/Api/Tenant/{tenantId}": { "get": { "description": "Retrieves details of a specific tenant record. This endpoint requires the `Tenant.Read.All` or `Tenant.ReadWrite.All` scopes (permissions).", "operationId": "/Api/Tenant/:tenantId/Get", "parameters": [ { "$ref": "#/components/parameters/tenantId" }, { "$ref": "#/components/parameters/parentId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantDetails" }, "examples": { "Example Complete Tenant Record": { "description": "An example showing a single existing tenant record.", "summary": "Existing Tenant Record", "value": { "tenantId": "9f0a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c", "displayName": "Contoso - Testing", "parentId": "f3ed1efc-4e62-46b8-bf2a-6b59ca9784e5", "authorizedPrincipalList": [ "9f0a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c", "2e3f4a5b-6c7d-8e9f-0a1b-2c3d4e5f6a7b", "4b5c6d7e-8f9a-0b1c-2d3e-4f5a6b7c8d9e" ] } } } } }, "description": "OK" }, "404": { "$ref": "#/components/responses/404" }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, "summary": "Retrieves Tenant Record", "tags": [ "Tenant Records" ] }, "patch": { "description": "Update tenant record using provided information. Payload could contain any combination of existing properties. To remove a parent, set the parentId to be the same as the tenant ID value. This endpoint requires the `Tenant.ReadWrite.All` scopes (permissions).", "operationId": "/Api/Tenant/:tenantId/Patch", "parameters": [ { "$ref": "#/components/parameters/tenantId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tenantDisplayName": { "description": "Human readable name for the tenant record", "type": "string", "examples": [ "Contoso - R&D East" ] }, "parentId": { "description": "The object ID of the tenant that is considered a parent to this record", "format": "uuid", "maxLength": 36, "minLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string", "examples": [ "6a7b8c9d-0e1f-2a3b-4c5d-6e7f8a9b0c1d" ] }, "authorizedPrincipalList": { "description": "List of object IDs that are allowed to access this record and related data.", "type": "array", "items": { "format": "uuid", "maxLength": 36, "minLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string", "examples": [ "4cae3355-0cff-410c-b4f9-69cb5de8f1ac" ] }, "examples": [ [ "4cae3355-0cff-410c-b4f9-69cb5de8f1ac", "0e52e6ac-f8e1-4070-ae2e-9bd0a37507a1" ] ] } }, "anyOf": [ { "required": [ "displayName" ] }, { "required": [ "parentId" ] }, { "required": [ "authorizedPrincipalList" ] } ], "examples": [ { "tenantDisplayName": "Contoso - R&D East", "parentId": "6a7b8c9d-0e1f-2a3b-4c5d-6e7f8a9b0c1d", "authorizedPrincipalList": [ "4cae3355-0cff-410c-b4f9-69cb5de8f1ac", "0e52e6ac-f8e1-4070-ae2e-9bd0a37507a1" ] } ] }, "examples": { "Example Request to Update Tenant Parent": { "description": "Sample payload requesting adjustment to the parent value.", "summary": "Update Parent Information for Tenant", "value": { "parentId": "6a7b8c9d-0e1f-2a3b-4c5d-6e7f8a9b0c1d" } }, "Example Request for Tenant Name and Parent Update": { "description": "Sample payload requesting to update parent value and display name on the tenant record.", "summary": "Update Tenant Record Name and Parent Information", "value": { "parentId": "8f9a0b1c-2d3e-4f5a-6b7c-8d9e0a1b2c3d", "displayName": "Contoso - R&D West" } }, "Example Request for Tenant Authorized Principals Update": { "description": "Sample payload requesting to update authorized principals for the tenant record.", "summary": "Update Tenant Authorized Principals List", "value": { "authorizedPrincipalList": [ "4cae3355-0cff-410c-b4f9-69cb5de8f1ac", "0e52e6ac-f8e1-4070-ae2e-9bd0a37507a1" ] } } } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantDetails" }, "examples": { "Example Complete Tenant Record": { "description": "Sample response after updating a tenant record.", "summary": "Updated Tenant Record", "value": { "tenantId": "c00ffc2c-b6f6-4121-bd8e-4d02e9504eb9", "displayName": "Contoso - Testing", "parentId": "8c291062-a4f7-4706-b4df-59e605497f06", "authorizedPrincipalList": [ "b856517a-2086-4be4-b63e-d6ca8a5b0ff6" ] } } } } }, "description": "OK" }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, "summary": "Update Tenant Record", "tags": [ "Tenant Records" ] } } }, "security": [ { "EntraID": [] } ], "servers": [ { "description": "Server the hosts the API described in the document.", "url": "https://api.shilab.com" } ], "tags": [ { "description": "Routes for the core data gateway system.", "name": "Core System", "externalDocs": { "description": "Data Gateway Documentation", "url": "https://docs.shilab.com/Date-Gateway/" } }, { "description": "Manages the list of tenants that have interacted with the Data Gateway in the past.", "name": "Tenant Records" }, { "description": "Collects and reports data from the license analytics product.", "name": "License Analytics", "externalDocs": { "description": "License Analytics Documentation", "url": "https://docs.shilab.com/License-Analytics/" } }, { "description": "Manages and reports the list of purchased licenses for the various SHI Lab Products.", "name": "License Entitlement" }, { "description": "Collects data from the various SHI Lab products.", "name": "Telemetry" }, { "name": "SHIELD - Update", "description": "Update Service Configuration for SHIELD." }, { "name": "Chat", "description": "Enables query for available information (like tenant, license, etc) via conversation with OpenAI agent." } ] }