{ "openapi": "3.0.1", "info": { "title": "ESPER API REFERENCE", "x-logo": { "url": "esper-logo-white.svg", "backgroundColor": "#141418", "altText": "Logo" }, "description": "# Introduction\nWelcome to Esper’s API documentation. The Esper API allows users to accomplish operations outside of the console. Some common uses for our APIs include observing device information and console activity, installing and updating apps, uploading files, and sending files to devices. Our users have also used the API to automate app updates, perform bulk actions, and more.\n\nEsper API endpoints use REST-based architecture and return JSON responses.\n\nSee our documentation for:\n\n* [Getting started guides](https://help.esper.io/hc/en-us/articles/14199291792145-Getting-Started-with-APIs)\n* [Commonly used API examples](https://help.esper.io/hc/en-us/articles/16036992814609-Commonly-Used-APIs)\n* [API command examples](https://help.esper.io/hc/en-us/articles/16693582666769-Scheduling-API-Commands)\n* [Automated Script examples](https://help.esper.io/hc/en-us/articles/22957898441745-Automating-App-Updates-Using-the-API)\n* [And more](https://help.esper.io/hc/en-us/sections/11388094627857-API)\n\n\n# Authentication\nYou need to create an API Key to interact with our APIs. Learn more about generating an API Key. You can also learn more about Esper and sign up for an account at esper.io/signup.\n\nSome endpoints also require an Enterprise ID. This ID can be found in the API Management section of the Esper console.\n# Lifecycle Labels\nEsper uses lifecycle labels to communicate the support status of each API endpoint. Use the following table to understand what each label means and how to respond.\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
BadgeWhat it meansRecommended action
StableThis endpoint is fully supported and safe for production use.No action needed.
BetaThis endpoint is publicly available but may change. It is not recommended for production integrations.Use with caution. Monitor the API changelog for updates before relying on this endpoint.
LegacyThis endpoint uses an older architecture and is still supported, but a newer equivalent exists. It is not recommended for new integrations.Plan migration to the recommended replacement when possible. See the endpoint description for the alternative.
DeprecatedThis endpoint has stopped being supported. A removal date may be added at a later time. A replacement is available or the feature is entirely retired.Migrate before the removal date listed in the endpoint description. Do not use this endpoint in new integrations.
\n\n# Pagination\nResponses may be paginated.\nUse the following parameters to query the data. A full list of parameters can be found on the endpoint’s documentation page.\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
ParameterData TypeExplanation
limitintegerLimit the data returned. Default = 20.
offsetintegerOffset to the first item returned. Default = 0.
orderingstringOrder the results set by the field name. Varies by endpoint.
nextstringPaginate to the next response set.
previousstringPaginate to the last set response.
\n\n# Errors\nWe use standard HTTP status codes for success or failure.\nA typical error response may look something like this:\n\n```json\n{\n \"errors\": [],\n \"message\": \"error message\",\n \"status\": 400\n}\n```\n* `errors` - List of error details\n* `message` - Error description\n* `status` - HTTP status code\n\nSome common status codes and messages are:\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
NumberMessageExplanation
200OKThe request succeeded.
201Resource creationA resource was created.
401UnauthorizedThe API key is invalid.
404Not foundThe resource was not found.
429Rate limit exceededToo many requests. Wait a moment and try again.
500Server errorInternal error. Wait a moment and try again. If the issue persists, contact Esper.
\n\nSee how our systems are doing by checking our [status page](https://status.esper.cloud/).\n\n# Rate Limits\nTo ensure quality of service for all customers, we enforce rate limits for API requests. Most customers won’t hit this limit with normal use. In case you experience 429 or rate limit exceeded errors, we recommend the following:\n* Try sending requests in batches.\n* Begin with about 20 requests at a time and building up from there.\n* Ensure your scripts are efficient and don’t contain redundant calls.\n* Reach out to your account manager to discuss your options.\n", "termsOfService": "https://esper.io/terms-of-service", "contact": { "email": "developer@esper.io" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" }, "version": "1.0.0", "x-prefix-tag": "esper cloud api" }, "servers": [ { "url": "https://{foo}-api.esper.cloud/api", "variables": { "foo": { "default": "develop", "description": "Custom end point" } } } ], "tags": [ { "name": "esper_cloud_api_Company Settings", "description": "The Company Settings API manage the account information set up for your organization. Formerly known as Enterprise Information. ", "externalDocs": { "description": "Find out more about Company Settings", "url": "https://help.esper.io/hc/en-us/articles/12656541757457-Introduction-to-Company-Settings" }, "x-displayName": "Company Settings" }, { "name": "esper_cloud_api_Application", "description": "APIs for application management", "externalDocs": { "description": "Find out more about application management", "url": "https://help.esper.io/hc/en-us/articles/12652127923857" }, "x-displayName": "Application" }, { "name": "esper_cloud_api_Application V1", "description": "APIs for application management", "x-displayName": "Application V1" }, { "name": "esper_cloud_api_AndroidDevice", "description": "APIs for android device management", "externalDocs": { "description": "Find out more about device management", "url": "https://help.esper.io/hc/en-us/articles/12523891684369" }, "x-displayName": "AndroidDevice" }, { "name": "esper_cloud_api_Device Group", "description": "APIs for device group management", "externalDocs": { "description": "Find out more about device group management", "url": "https://help.esper.io/hc/en-us/articles/12523891684369" }, "x-displayName": "Device Group" }, { "name": "esper_cloud_api_Token (Deprecated)", "description": "⚠️ **Deprecation Notice:** The following APIs will soon be deprecated. Use the console to manage API keys instead.\n", "externalDocs": { "description": "Find out more about API Key generation", "url": "https://help.esper.io/hc/en-us/articles/12656959508497" }, "x-displayName": "Token (Deprecated)" }, { "name": "esper_cloud_api_Commands V2", "description": "Commands V2.0 provides advanced device commands capabilities like queuing, support for offline devices, dynamic device set for commands and command history. Commands 2.0 is in active development and we will add support for all the commands soon", "externalDocs": { "description": "Find out more about commands V2.0", "url": "https://help.esper.io/hc/en-us/articles/12524618746129" }, "x-displayName": "Commands V2" }, { "name": "esper_cloud_api_Enterprise Policy", "description": "APIs to Esper Compliance Policy", "externalDocs": { "description": "Find out more about Compliance Policy", "url": "https://help.esper.io/hc/en-us/articles/12653153592977" }, "x-displayName": "Enterprise Policy" }, { "name": "esper_cloud_api_Geofence", "description": "APIs for geofence management", "externalDocs": { "description": "Find out more about Geofence", "url": "https://help.esper.io/hc/en-us/articles/12655621844753" }, "x-displayName": "Geofence" }, { "name": "esper_cloud_api_Content", "description": "APIs to manage files", "externalDocs": { "description": "Find out more about Content management", "url": "https://help.esper.io/hc/en-us/articles/12655910179473" }, "x-displayName": "Content" }, { "name": "esper_cloud_api_User (Deprecated)", "description": "⚠️ **Deprecation Notice:** The following APIs will soon be deprecated. Please transition to the User APIs.", "externalDocs": { "description": "Find out more about User management", "url": "https://help.esper.io/hc/en-us/articles/12656615814929" }, "x-displayName": "User (Deprecated)" }, { "name": "esper_cloud_api_User", "description": "APIs for User Management", "externalDocs": { "description": "Find out more about User management", "url": "https://help.esper.io/hc/en-us/articles/12656615814929" }, "x-displayName": "User" }, { "name": "esper_cloud_api_Blueprint (Deprecated)", "description": "This is the API for the former Blueprints service.\n\n⚠️ **Deprecation Notice:** The following APIs will soon be deprecated. Use [Blueprints API](https://api.esper.io/tag/Blueprints-API) instead.\n", "x-displayName": "Blueprint (Deprecated)" }, { "name": "esper_cloud_api_Directory Record", "description": "APIs for Directory Record management. These APIs are only available to the customers using the new Onboarding experience.", "x-displayName": "Directory Record" }, { "name": "esper_cloud_api_Tile Icon", "description": "APIs to manage tile icons. Tile icons allow Templates-based users to apply a icons to devices.\n", "x-displayName": "Tile Icon" }, { "name": "esper_cloud_api_Alerts", "x-displayName": "Alerts" }, { "name": "esper_cloud_api_Alarms", "x-displayName": "Alarms" }, { "name": "esper_cloud_api_Wallpapers", "x-displayName": "Wallpapers" }, { "name": "esper_cloud_api_Device Telemetry", "x-displayName": "Device Telemetry" }, { "name": "esper_cloud_api_Daily and Custom Reports", "x-displayName": "Daily and Custom Reports" }, { "name": "esper_cloud_api_SSO Connections", "x-displayName": "SSO Connections" }, { "name": "esper_cloud_api_Roles", "x-displayName": "Roles" }, { "name": "esper_cloud_api_Personal Access Token", "x-displayName": "Personal Access Token" }, { "name": "blueprints_Blueprints API", "description": "APIs to manage blueprints. Learn more about [blueprints](https://help.esper.io/hc/en-us/articles/19118758564369-Introduction-to-Blueprints).", "x-displayName": "Blueprints API" }, { "name": "blueprints_Custom Actions API", "description": "APIs to manage custom actions. Custom actions allow you to define custom scripts and commands that can be executed on Linux devices. Currently, only Linux platform is supported for custom actions.", "x-displayName": "Custom Actions API" }, { "name": "blueprints_Background Scripts API", "description": "APIs to manage background scripts. Background scripts are scripts that can be configured to run continuously or at specified intervals on devices.", "x-displayName": "Background Scripts API" }, { "name": "pipelines_System Status Code", "description": "System status code descriptions\n * 900 (INTERNAL_REQUEST_SKIPPED) - Response code is used when a request is valid, but cannot be fulfilled.\n", "x-displayName": "System Status Code" }, { "name": "pipelines_System", "description": "System level APIs", "x-displayName": "System" }, { "name": "pipelines_Pipelines", "description": "Pipelines composition APIs", "x-displayName": "Pipelines" }, { "name": "pipelines_Stages", "description": "APIs to modify Stage information", "x-displayName": "Stages" }, { "name": "pipelines_Target Lists", "description": "APIs to modify Target List", "x-displayName": "Target Lists" }, { "name": "pipelines_Targets", "description": "Targets subsystem", "x-displayName": "Targets" }, { "name": "pipelines_Device Groups", "description": "APIs to modify Device Groups", "x-displayName": "Device Groups" }, { "name": "pipelines_Operation Lists", "description": "APIs to modify Operation List", "x-displayName": "Operation Lists" }, { "name": "pipelines_Operations", "description": "Operations subsystem", "x-displayName": "Operations" }, { "name": "pipelines_Pipeline Runs", "description": "APIs to manage Pipeline Runs. Pipeline run status descriptions\n * PENDING - Pipeline run created.\n * QUEUED - Pipeline run queued for processing.\n * PROCESSING - Pipeline run received by scheduler for processing. (Processing a pipeline involves performing the operations required before starting a pipeline)\n * RUNNING - Pipeline run has started running.\n * WAITING - Pipeline run is waiting for an action (manual/automatic).\n * COMPLETE - The pipeline run has completed processing i.e. All stage runs are processed. A complete pipeline run can move to success or failure.\n * SUCCESS - A completed pipeline run moves to success if all stage runs are successful.\n * FAILURE - A completed pipeline run moves to failure if all stage runs are not successful.\n * CANCELLED - Pipeline run is cancelled by the user.\n * TIMEOUT - The pipeline run has a timed out. This happens when the pipeline has not completed processing even after the timeout period (Default 21 days).\n * INVALID - A pipeline run moves to invalid state when Pipeline run has no stageruns i.e pipeline has zero stages.\n", "x-displayName": "Pipeline Runs" }, { "name": "pipelines_Stage Runs", "description": "APIs to manage Stage Runs. Stage run status descriptions\n * PENDING - Stage run created.\n * QUEUED - Stage run queued for processing.\n * PROCESSING - Stage run received by scheduler for processing.(Processing a stage run can involve performing the operations required before starting a stage run. In this case creating the target runs for the stage.)\n * RUNNING - Stage run has started running. \n * COMPLETE - Stage run moves to complete if all target runs are complete (target runs are complete if they are in a terminal state).\n * SUCCESS - A completed stage run moves to success if all target runs are successful. \n * FAILURE - A completed stage moves to failure if all target runs are not successful.\n * CANCELLED - Stage run cancelled by user.\n * TIMEOUT - The stage run has a timed out. This happens when the stage run has not completed processing even after the timeout period (Default 7 days).\n * INVALID - A stage run moves to invalid state when \n a. The associated stage has no targets.\n b. The associated stage has no operations.\n", "x-displayName": "Stage Runs" }, { "name": "pipelines_Target Runs", "description": "APIs to manage Target Runs. Target run status descriptions\n * PENDING - Target run created.\n * QUEUED - Target run queued for processing.\n * PROCESSING - Target run received by scheduler for processing (During target run processing the command request for the target run is created).\n * DISPATCHED - Target run moves to dispatched when a command is successfully queued for the target run. (Command status - QUEUED)\n * RUNNING - Target run moves to running state when the command has been sent to the device (Command status - INITIATED, ACKNOWLEDGED, INPROGRESS)\n * COMPLETE - Target run moves to complete state when it has completed running (Command status - FAILURE, SUCCESS, TIMEOUT, CANCELLED)\n * SUCCESS - A completed target run moves to success when the associated command is successful (Command status - SUCCESS)\n * FAILURE - A completed target run moves to success when the associated command is unsuccessful (Command status - FAILED, TIMEOUT, CANCELLED)\n * CANCELLED - Target run cancelled by the user (Target runs ind Pending, Queued and Processing state can be cancelled by the user)\n * TIMEOUT - The target run has a timed out. This happens when the target run has not completed processing even after the timeout period (7 days).\n * INVALID - Target run is invalid.\n", "x-displayName": "Target Runs" }, { "name": "device_Device", "description": "APIs to retrieve information about the device or delete the device.", "x-displayName": "Device" }, { "name": "device_Device Heartbeat", "description": "APIs to retrieve information about device's heartbeat which contains the last seen details.", "x-displayName": "Device Heartbeat" }, { "name": "device_Device Apps", "description": "APIs to get apps installed on iOS devices. Use [Application](https://api.esper.io/tag/Application/) to get apps for Android devices.", "x-displayName": "Device Apps" }, { "name": "device_Device Enrollment in EMM", "description": "APIs to enroll device with Google EMM", "x-displayName": "Device Enrollment in EMM" }, { "name": "device_Operations", "description": "APIs to get information about operations", "x-displayName": "Operations" }, { "name": "device_DeviceOperations", "description": "APIs to get information about device operations", "x-displayName": "DeviceOperations" }, { "name": "device_MultiOS Remote Viewer", "description": "API to get Remote Viewer activity for the tenant. Currently supports only Android devices with DPC 8.4 and above along with RemoteViewer 3.x.", "x-displayName": "MultiOS Remote Viewer" }, { "name": "apps_management_VPP License Management", "description": "APIs for managing VPP licenses for apps. Learn more about [VPP licenses](https://help.esper.io/hc/en-us/articles/20361103311761-Setting-Up-Apple-MDM-Management).", "x-displayName": "VPP License Management" }, { "name": "apps_management_VPP App Management", "description": "APIs for getting information about VPP apps. Learn more about [VPP apps](https://help.esper.io/hc/en-us/articles/20518326865681-Managing-iOS-Applications).", "x-displayName": "VPP App Management" }, { "name": "apps_management_Tenant Apps", "description": "API to manage Enterprise iOS apps for a tenant.", "x-displayName": "Tenant Apps" }, { "name": "apps_management_Apple App Store", "description": "API to search apple app store for apps", "x-displayName": "Apple App Store" }, { "name": "apps_management_App List", "description": "Unified API to query Webclips and Tenant IOS Apps", "x-displayName": "App List" }, { "name": "apps_management_Webclips", "description": "API to manage webclips for a tenant", "x-displayName": "Webclips" }, { "name": "apps_management_Provisioning Profiles", "description": "APIs for managing iOS provisioning profiles for app distribution", "x-displayName": "Provisioning Profiles" }, { "name": "apps_management_Preferred Regions", "description": "APIs for managing a tenant's preferred country/region list for App Store lookups", "x-displayName": "Preferred Regions" }, { "name": "apps_management_OEM Config Schema", "description": "APIs for retrieving OEM config schemas parsed from OEM APKs", "x-displayName": "OEM Config Schema" }, { "name": "apps_management_Esper Apps", "x-displayName": "Esper Apps" }, { "name": "apps_management_Tenant Esper Apps", "x-displayName": "Tenant Esper Apps" }, { "name": "commands_Command Request", "description": "APIs to view and manage command requests. Learn more about [commands](https://help.esper.io/hc/en-us/articles/16036992814609-Commonly-Used-APIs#h_01H2GZ8WM86BSQBGXE998QY8SM) or how to [schedule a command](https://help.esper.io/hc/en-us/articles/16036992814609-Commonly-Used-APIs#h_01H2GZ8WM86BSQBGXE998QY8SM).\n\nScheduled commands are currently compatible with Android devices.", "x-displayName": "Command Request" }, { "name": "commands_Command Status", "description": "APIs to view, filter, and manage command requests.", "x-displayName": "Command Status" }, { "name": "drift_Converge", "description": "APIs to list and create converge actions for devices.", "x-displayName": "Converge" }, { "name": "drift_Converge Command", "description": "API for converge command", "x-displayName": "Converge Command" }, { "name": "drift_Blueprint Drift", "description": "APIs to fetch device Blueprint Drift status", "x-displayName": "Blueprint Drift" }, { "name": "device_onboarding_DEP Sync Request", "description": "APIs to create and access DEP sync request information. Use DEP sync to sync the information from your Apple Business Manager account to the Esper console.", "x-displayName": "DEP Sync Request" }, { "name": "device_onboarding_ABM Provisioning", "description": "APIs to perform ABM provisioning. Learn more about [ABM provisioning](https://help.esper.io/hc/en-us/articles/20361103311761-Setting-Up-Apple-MDM-Management)", "x-displayName": "ABM Provisioning" }, { "name": "tenant_APNs certificate", "description": "APIs for managing APNS certificates. Learn more about [APNS certificates](https://help.esper.io/hc/en-us/articles/20361103311761-Setting-Up-Apple-MDM-Management)", "x-displayName": "APNs certificate" }, { "name": "tenant_DEP Profile", "description": "APIs to create and manage DEP profiles. Learn more about [DEP profiles](https://help.esper.io/hc/en-us/articles/20361103311761-Setting-Up-Apple-MDM-Management)", "x-displayName": "DEP Profile" }, { "name": "tenant_DEP Tokens", "description": "APIs to create and access DEP tokens. Learn more about [DEP tokens](https://help.esper.io/hc/en-us/articles/20361103311761-Setting-Up-Apple-MDM-Management)", "x-displayName": "DEP Tokens" }, { "name": "tenant_VPP Token Management", "description": "APIs to create, access, and delete VPP tokens. Learn more about [VPP tokens](https://help.esper.io/hc/en-us/articles/20361103311761-Setting-Up-Apple-MDM-Management).", "x-displayName": "VPP Token Management" }, { "name": "tenant_Google Enterprise", "description": "APIs to enroll the enterprise in Google EMM.", "x-displayName": "Google Enterprise" }, { "name": "tenant_MDM Service Config", "description": "Unauthenticated discovery endpoint for Apple's MDMServiceConfig spec.", "x-displayName": "MDM Service Config" }, { "name": "foundation_FoundryBuilds", "x-displayName": "FoundryBuilds" }, { "name": "foundation_FoundryDeviceModels", "x-displayName": "FoundryDeviceModels" }, { "name": "foundation_FoundryEvents", "x-displayName": "FoundryEvents" }, { "name": "reports_Reports API", "description": "APIs for managing reports.
Currently supports [App Reports](https://help.esper.io/hc/en-us/articles/27379366650257-App-Reports).", "x-displayName": "Reports API" }, { "name": "geofence_Geofences", "x-displayName": "Geofences" }, { "name": "geofence_Device State", "x-displayName": "Device State" } ], "paths": { "/enterprise/{enterprise_id}/application/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "List apps in enterprise", "description": "**Alternative Available**\n\nGET \"/v2/apps (tenant iOS and Windows apps only)\" or GET \"https://{foo}-api.esper.cloud/api/v1/enterprise/{enterprise_id}/application/\"\n\nLists all applications uploaded to an enterprise's application library. Returns a paginated collection of application records, including metadata such as package name, developer, category, and active status, with filter options to narrow results by name, package, SDK version, upload status, and timestamps. Default page size is 20.\n\n**About List Enterprise Applications**\n\nEsper's application library is the enterprise-level repository where APK files are uploaded and managed before deployment to devices. Each application entry groups multiple uploaded versions under a single record identified by package name. Applications can be filtered by active state, hidden status, and whether they have at least one uploaded version ready for deployment.\n\n**Key Query Parameters**\n\napplication_name — partial or exact name filter\npackage_name — filter by Android package name (e.g. com.example.app)\nhas_uploaded_version — when true, returns only apps with at least one APK version on record\nis_hidden — filters default Esper system apps; defaults to false\nis_active — filter for currently active applications\ncreated_on_gt / created_on_lt / updated_on_gt / updated_on_lt — timestamp range filters for audit or sync **Workflow**s\nlimit — results per page (default: 20)\n\n**Common Use Cases**\n\nInventory the full set of applications available for deployment across an enterprise\nLocate a specific app by package name before retrieving its versions for installation\nIdentify apps that have no uploaded versions and may need attention\n\n**Best Practices**\n\nNo need to delete prior versions. Multiple, different versions of apps can exist simultaneously. \nApplications must be removed from a blueprint before the blueprint can be deleted. \n\n**Workflow**\n\nCall this endpoint with relevant filters (name, package, active state) to find the target application\nNote the id field from the matching result — this is the application_id UUID needed for version lookups and installs\nProceed to GET .../application/{application_id}/version/ to retrieve available versions", "operationId": "getAllApplications", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "application_name", "in": "query", "description": "filter by application name", "schema": { "type": "string" } }, { "name": "package_name", "in": "query", "description": "filter by package name", "schema": { "type": "string" } }, { "name": "package_name_exact", "in": "query", "description": "filter by package name (exact match)", "schema": { "type": "string" } }, { "name": "has_uploaded_version", "in": "query", "description": "Returns applications having at least one version uploaded", "schema": { "type": "boolean" } }, { "name": "category", "in": "query", "description": "filter by category", "schema": { "type": "string" } }, { "name": "supported_sdk", "in": "query", "description": "filter by supported sdk versions", "schema": { "type": "integer" } }, { "name": "is_active", "in": "query", "description": "filter by active applications", "schema": { "type": "boolean" } }, { "name": "is_hidden", "in": "query", "description": "filter default esper apps", "schema": { "type": "boolean", "default": false } }, { "name": "created_on_gt", "in": "query", "description": "filter applications created after a given timestamp", "schema": { "type": "string", "format": "datetime" } }, { "name": "created_on_lt", "in": "query", "description": "filter applications created before a given timestamp", "schema": { "type": "string", "format": "datetime" } }, { "name": "updated_on_gt", "in": "query", "description": "filter applications updated after a given timestamp", "schema": { "type": "string", "format": "datetime" } }, { "name": "updated_on_lt", "in": "query", "description": "filter applications updated before a given timestamp", "schema": { "type": "string", "format": "datetime" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "description": "Return results from this index.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_Application" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/enterprise/{enterprise_id}/application/{application_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "Get application information", "description": "Lists all versions of a specific application registered in the enterprise library.\nReturns a paginated collection of AppVersion records for the specified application, filterable by version code, build number. Default page size is 20; results can be ordered by install count.\n\nAbout List App Versions\n\nAn Esper application can have multiple versions, each tracked as a distinct AppVersion record with its own UUID (version_id).The version_id is required when issuing install commands to specific devices.\n\n**Key Query Parameters**\n\nversion_code — filter by the version code string (as set in the APK manifest)\nbuild_number — filter by build number\napproval_status — filter by lifecycle status: AVAILABLE, ACCEPTED, APPROVED, or REJECTED\nis_enabled — filter for enabled versions only\nis_default — filter for the default version of the application\nordering — sort by installed_count (ascending) or -installed_count (descending)\nlimit — results per page (default: 20)\n\n**Common Use Cases**\n\nRetrieve the list of versions before selecting one for a device install command\n\n**Best Practices**\n\nStore version_id values from results — these UUIDs are required for device install and app detail lookups\n\n**Workflow**\n\nCall this endpoint with the target application_id and any filters \nSelect the appropriate version from the results and record its id (version_id)\nUse version_id in install commands or in GET .../version/{version_id}/ for full version detail", "operationId": "getApplication", "parameters": [ { "name": "application_id", "in": "path", "description": "A UUID string identifying this application.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Application" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "Delete an application", "description": "Alternative Available: DELETE /v1/enterprise/{enterprise_id}/application/{application_id}/\nTo remove an iOS or Windows application version: DELETE /v2/tenant-apps/{appId}/versions/{versionId}\nDelete Android enterprise application. Permanently removes an application and all of its associated versions from the enterprise. Once deleted, the application can no longer be assigned to devices or policies and cannot be managed or distributed unless re-uploaded.\n**Common Use Cases** Removing deprecated or unsupported applications from the enterprise catalog, cleaning up unused or test applications, eliminating duplicate entries, and decommissioning applications no longer approved for distribution.\n**Best Practices** Before deleting, download a backup copy of the application package from the Apps section in the console — deletion is permanent and cannot be undone. Verify the application is not referenced in any active blueprints before calling this endpoint; an application associated with a blueprint must be removed from that blueprint first or the deletion will fail. Review device and policy assignments to avoid unintended disruption to managed devices.\nNote: This endpoint removes the entire application record along with all versions. To remove iOS or Windows tenant application versions individually, use DELETE /v2/tenant-apps/{appId}/versions/{versionId} instead.\n**Workflow**:\n\n1. Use the List apps in enterprise endpoint to retrieve the application_id.\n2. Check whether the application is present in any blueprints: GET /v2/blueprints/\n3. If the application appears in one or more blueprints, note the relevant blueprint_id values.\n4. For each affected blueprint, remove the application by calling: PUT /v2/blueprints/{blueprint_id}/\n5. Once the application has been removed from all blueprints, call this endpoint with the application_id to permanently delete it and all associated versions from the enterprise.", "operationId": "deleteApplication", "parameters": [ { "name": "application_id", "in": "path", "description": "A UUID string identifying this application.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The resource was deleted successfully." }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/enterprise/{enterprise_id}/application/{application_id}/version/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "List App versions", "description": "Lists all versions of a specific application registered in the enterprise library.\n\nReturns a paginated collection of AppVersion records for the specified application, filterable by version code, build number, approval status, Google Play origin, enabled state, and timestamps. Default page size is 20; results can be ordered by install count.\n\n**About List App Versions**\n\nAn Esper application can have multiple versions, each tracked as a distinct AppVersion record with its own UUID (version_id). Versions may originate from a direct APK upload or from the Console Google Play Store (identifiable via is_g_play). Each version carries an approval_status (AVAILABLE, ACCEPTED, APPROVED, or REJECTED) and can be enabled or disabled independently. The version_id is required when issuing install commands to specific devices.\n\n**Key Query Parameters**\n\nversion_code — filter by the version code string (as set in the APK manifest)\n\nbuild_number — filter by build number\n\nis_g_play — true returns only versions sourced from the Console Google Play Store\n\napproval_status — filter by lifecycle status: AVAILABLE, ACCEPTED, APPROVED, or REJECTED\n\nis_enabled — filter for enabled versions only\n\nis_default — filter for the default version of the application\n\nordering — sort by installed_count (ascending) or -installed_count (descending)\n\nlimit — results per page (default: 20)\n\n**Common Use Cases**\n\nRetrieve the list of approved, enabled versions before selecting one for a device install command\nAudit which app versions are currently deployed across devices using installed_count ordering\nIdentify versions with approval_status=REJECTED or is_enabled=false to clean up the library\n\n**Best Practices**\n\nFilter by approval_status=APPROVED and is_enabled=true to limit results to deployment-ready versions\nUse is_g_play=false when working exclusively with internally uploaded APKs to exclude Play Store-sourced versions\nStore version_id values from results — these UUIDs are required for device install and app detail lookups\n\n**Workflow**\n\nCall this endpoint with the target application_id and any filters (approval status, enabled state)\nSelect the appropriate version from the results and record its id (version_id)\nUse version_id in install commands or in GET .../version/{version_id}/ for full version detail", "operationId": "getAppVersions", "parameters": [ { "name": "application_id", "in": "path", "description": "A UUID string identifying this application.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "version_code", "in": "query", "description": "filter by version code", "schema": { "type": "string" } }, { "name": "build_number", "in": "query", "description": "filter by build number", "schema": { "type": "string" } }, { "name": "is_g_play", "in": "query", "description": "filter google play applications", "schema": { "type": "boolean" } }, { "name": "approval_status", "in": "query", "description": "filter by approval status", "schema": { "type": "string", "enum": [ "AVAILABLE", "ACCEPTED", "APPROVED", "REJECTED" ] } }, { "name": "is_enabled", "in": "query", "description": "filter by enabled versions", "schema": { "type": "boolean" } }, { "name": "is_default", "in": "query", "description": "filter by default versions", "schema": { "type": "boolean" } }, { "name": "created_on_gt", "in": "query", "description": "filter applications created after a given timestamp", "schema": { "type": "string", "format": "datetime" } }, { "name": "created_on_lt", "in": "query", "description": "filter applications created before a given timestamp", "schema": { "type": "string", "format": "datetime" } }, { "name": "updated_on_gt", "in": "query", "description": "filter applications updated after a given timestamp", "schema": { "type": "string", "format": "datetime" } }, { "name": "updated_on_lt", "in": "query", "description": "filter applications updated before a given timestamp", "schema": { "type": "string", "format": "datetime" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "description": "Return results from this index.", "schema": { "type": "integer", "default": 0 } }, { "name": "ordering", "in": "query", "schema": { "type": "string" }, "description": "Order result set by field name.\n* installed_count: order by asc\n* -installed_count: order by desc\n" } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_AppVersion" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/enterprise/{enterprise_id}/application/{application_id}/version/{version_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "Get app version information", "description": "Retrieves full details for a single application version by its UUID.\nReturns the AppVersion object including version code, build number, release name, release track, approval status, enabled/default state, SDK version constraints, and install count. Use when you need complete metadata on a specific version identified by version_id.\n\nAbout Get App Version\n\nAppVersion records in Esper represent individual APK builds associated with an application. Each version has its own version_id UUID and carries release lifecycle metadata — including its release_track (Alpha, Beta, or Production), approval_status, and is_enabled flag — that governs whether it is eligible for deployment. This endpoint also includes a request_id query parameter that, when matched in cache, triggers deletion of the cached application and entry, useful for invalidating stale state during upload **Workflow**s.\n\nKey Fields / Query Parameters\n\napplication_id - The UUID of the application\n\nversion_id — path parameter UUID identifying this specific version\n\nversion_code — the version identifier from the APK manifest\n\nbuild_number — build-level identifier for the release\n\nis_enabled — whether this version is available for deployment\n\nis_default — whether this version is the designated default for the application\n\n**Common Use Cases**\n\nConfirm the approval status and release track of a version before scheduling a device install\nRetrieve SDK version constraints (min_sdk_version, target_sdk_version) to verify device compatibility\nLook up a version's installed_count to understand deployment breadth before deprecating or replacing it\n\n**Best Practices**\n\nVerify is_enabled=true before using a version_id in an install command\nUse this endpoint rather than the version list when you already have the version_id and need authoritative metadata fast\n\n**Workflow**\n\nObtain the version_id from a prior version list call or stored reference\nCall this endpoint to retrieve full version metadata\nConfirm release track and approval status, then proceed with install or deployment commands", "operationId": "getAppVersion", "parameters": [ { "name": "version_id", "in": "path", "description": "A UUID string identifying this app version.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "application_id", "in": "path", "description": "A UUID string identifying this application.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "request_id", "in": "query", "description": "If this value exists in cache, delete the application and cache entry.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_AppVersion" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "Delete app version", "description": "Alternative Available: DELETE /v1/enterprise/{enterprise_id}/application/{application_id}/version/{version_id}/ To remove an iOS or Windows application version: DELETE /v2/tenant-apps/{appId}/versions/{versionId}\n\nDelete Android enterprise application version. Permanently removes a specific version of an application from the enterprise app catalog. Only the targeted version is deleted — the application record and all other versions remain intact and unaffected.\n\n**Common Use Cases** Removing a buggy or recalled release, cleaning up test or development builds, and reducing catalog clutter by retiring outdated versions no longer approved for distribution.\n\nImportant behavior: You do not need to delete older versions before uploading a new one. Use this endpoint only when you want the selected version fully and permanently removed from the catalog.\n\n**Best Practices** Before deleting, download and retain a copy of the build artifact outside of Esper — this action is irreversible and the version cannot be recovered through the API. Verify the version is not referenced in any active blueprints before calling this endpoint; a version associated with a blueprint must be removed from that blueprint first or the deletion will fail. Review any deployment **Workflow**s that may reference this specific version to avoid unintended disruption.\n\n**Workflow**: 1. Use the List apps in enterprise endpoint to retrieve the application_id. 2. Use the List app versions endpoint to identify the version_id you want to remove. 3. Check whether the version is present in any blueprints: GET /v2/blueprints/ 4. If the version appears in one or more blueprints, note the relevant blueprint_id values. 5. For each affected blueprint, remove the version reference by calling: PUT /v2/blueprints/{blueprint_id}/ 6. Once the version has been removed from all blueprints, call this endpoint with the application_id and version_id to permanently delete it.", "operationId": "deleteAppVersion", "parameters": [ { "name": "version_id", "in": "path", "description": "A UUID string identifying this app version.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "application_id", "in": "path", "description": "A UUID string identifying this application.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "No request id is provided and the application is linked to one or more templates. Returns a request_id. Call with this request id to delete the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_AppVersionDelete" } } } }, "204": { "description": "The resource was deleted successfully." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "patch": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "Patch an App version instance", "description": "Alternative Available: PATCH /v1/enterprise/{enterprise_id}/application/{application_id}/version/{version_id}/\nTo update an iOS or Windows application version: PUT /v2/tenant-apps/{appId}/versions/{versionId}\n\nPatch Android enterprise application version. Updates editable metadata for a specific application version without changing the underlying build. Use this endpoint to modify fields such as release name, release comments, release track, approval status, SDK targets, and whether the version is enabled or set as the default.\n\n**Common Use Cases** Updating release notes or comments after upload, changing a version's release track (Alpha, Beta, or Production), enabling or disabling a specific version, setting a version as the default, and updating approval status as part of a review **Workflow**.\n\nImportant behavior: This endpoint does not upload or replace the app binary. To publish a new build, use: POST /enterprise/{enterprise_id}/application/upload/\n\n**Best Practices** Only include the fields you intend to change — unspecified fields will remain unchanged. Confirm the version_id before patching to avoid updating the wrong release. If updating approval_status or is_enabled as part of a release **Workflow**, verify downstream policies and blueprints referencing this version are ready before making the version active.\n**Workflow**:\n\n1. Use the List apps in enterprise endpoint to retrieve the application_id.\n2. Use the List app versions endpoint to identify the version_id you want to update.\n3. Send a PATCH request with only the metadata fields you want to modify.", "operationId": "patchAppVersion", "parameters": [ { "name": "version_id", "in": "path", "description": "A UUID string identifying this app version.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "application_id", "in": "path", "description": "A UUID string identifying this application.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "*/*": { "schema": { "type": "object", "properties": { "release_name": { "title": "Release name", "type": "string", "description": "Name of the Release" }, "release_comments": { "title": "Release comments", "type": "string", "description": "Additional comments about the release" }, "release_track": { "title": "Release track", "type": "string", "description": "Description of the content", "enum": [ "Alpha", "Beta", "Production" ] }, "is_enabled": { "title": "Is Enabled", "type": "boolean", "description": "Is the app version enabled" }, "min_sdk_version": { "title": "Minimum SDK version", "type": "string", "description": "Version number of minimum SDK version that supports this app version" }, "target_sdk_version": { "title": "Target SDK version", "type": "string", "description": "Target SDK version that supports this app version" }, "build_number": { "title": "Build Number", "type": "string", "description": "Build number of this app version" }, "version_code": { "title": "Version Code", "type": "string", "description": "Version code of this app version" }, "approval_status": { "title": "Approval Status", "type": "string", "description": "Approval status of this app version", "enum": [ "AVAILABLE", "ACCEPTED", "APPROVED", "REJECTED" ] }, "is_default": { "title": "Is default", "type": "boolean", "description": "Is the app version default" } } } } }, "required": false }, "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_AppVersion" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ], "x-codegen-request-body-name": "data" } }, "/enterprise/{enterprise_id}/application/{application_id}/version/{version_id}/installdevices": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "List install devices", "description": "List all devices with a specific app version installed. Retrieves a paginated list of devices on which the specified application version is currently installed. Results can be searched by device name, device alias, or group name.\n\nAbout App Install Tracking\n\nEsper tracks the installation state of each app version across enrolled devices. This endpoint provides an app-centric view of device coverage — rather than querying each device individually for its installed apps, you can query a specific app version to see exactly which devices have it installed. This is particularly useful for verifying deployment coverage after issuing an install command across a fleet.\n\nPlatform limitations\n\nThis endpoint is not supported for iOS, Linux, or Windows devices — retrieving a list of devices by app version is an Android-only capability. Additionally, kiosk-specific app attributes such as KioskAppName are not included in the summary-level device records returned by this endpoint; retrieving those attributes requires individual device detail calls via GET /enterprise/{enterprise_id}/device/{device_id}/.\n\n**Workflow**\n\n1. Call GET /enterprise/{enterprise_id}/application/ to retrieve the application_id for the app you want to audit.\n2. Call GET /enterprise/{enterprise_id}/application/{application_id}/version/ to retrieve the version_id for the specific version.\n3. Call this endpoint to retrieve the list of devices with that version installed.\n4. Cross-reference results against your target device list to identify any devices that are missing the installation.\n5. Use POST /commands/v0/commands/ to issue an install command to devices that have not yet received the app version.", "operationId": "getInstallDevices", "parameters": [ { "name": "version_id", "in": "path", "description": "A UUID string identifying this app version.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "application_id", "in": "path", "description": "A UUID string identifying this application.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "A search term, search based on device name, device alias_name, group name", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "Return results from this index.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_InstallDevices" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/enterprise/{enterprise_id}/application/upload/": { "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "Upload an application to enterprise", "description": "⚠️ Android only. This endpoint accepts APK files and applies exclusively to Android-managed devices. See iOS and Windows application endpoints for **Workflow**s.\n\nUploads an APK file to the enterprise application library, creating or updating an application and version record.\nAccepts a multipart/form-data payload with a single required field (app_file), and returns the resulting Application object including the newly created version upon success. This is the primary mechanism for adding privately distributed APKs to the Esper platform for enterprise deployment.\n\nAbout Upload Application\n\nThe upload endpoint ingests an APK binary and parses it to extract metadata such as package name, version code, and SDK requirements, automatically associating the upload with the correct application record (creating one if none exists for the package name). The returned Application object includes the new version in its versions array. \n\nKey Fields\n\napp_file — required; the binary APK file to upload, sent as multipart/form-data\n\n**Common Use Cases**\n\nAdd a new internal or privately distributed app to the enterprise library for managed deployment\nUpload a new version of an existing app, updating the version catalog without creating a duplicate application record\nAutomate app updates as part of a CI/CD pipeline that pushes new APK builds to Esper. Use the Operations endpoint for large deployments.\n\n**Best Practices**\n\nEnsure the APK is valid and signed before uploading — malformed or unsigned APKs will result in a 400 Bad Request\nStore the application_id and version_id from the response to use directly in install commands without a subsequent lookup\n\n**Workflow**\n\nBuild and sign your APK\nPOST the APK binary as app_file in a multipart/form-data request to this endpoint\nRetrieve the application_id and new version_id from the response, then proceed with install **Workflow**s", "operationId": "upload", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "app_file" ], "properties": { "app_file": { "type": "string", "description": "Valid APK file", "format": "binary" } } } }, "application/x-www-form-urlencoded": { "schema": { "required": [ "app_file" ], "properties": { "app_file": { "type": "string", "description": "Valid APK file", "format": "binary" } } } } }, "required": true }, "responses": { "201": { "description": "successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "application": { "$ref": "#/components/schemas/esper_cloud_api_Application" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "415": { "description": "Unsupported media type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v0/enterprise/{enterprise_id}/emm": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "List Google enterprises", "description": "List all Google Enterprise (EMM) instances for the enterprise. Retrieves all Google Enterprise bindings associated with the specified Esper enterprise, including the google_enterprise_id that links each binding to Google's EMM infrastructure.\n\nAbout Google EMM\n\nA Google Enterprise binding connects an Esper enterprise to Google's Enterprise Mobility Management (EMM) infrastructure, enabling management of GMS-enabled Android devices. This binding is the foundation for silent app installation, Play Store customization, managed configurations, and advanced device provisioning across a GMS fleet. Without an active EMM binding, Google Play-dependent management features are unavailable.\n\n\n**Common Use Cases** \n\nConfirming that a Google Enterprise binding exists before attempting GMS-dependent operations, retrieving the emm_id needed to call related EMM endpoints, and auditing the EMM enrollment state for a given enterprise.\n\n**Workflow**\n\n1. Call this endpoint to confirm the enterprise has an active EMM binding and retrieve the emm_id.\n2. Use GET /v0/enterprise/{enterprise_id}/emm/{emm_id}/ to retrieve full details for a specific EMM instance.", "operationId": "getEMMInstances", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_GoogleEnterprise" } } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v0/enterprise/{enterprise_id}/emm/{emm_id}": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "Get Google enterprise information", "description": "Get a specific Google Enterprise (EMM) instance for the enterprise. Retrieves the details of a single Google Enterprise binding identified by emm_id, including its association with the Esper enterprise and the google_enterprise_id that links it to Google's EMM infrastructure.\n\n**Common Use Cases** \n\nConfirming the details of a specific EMM binding before performing GMS-dependent operations, retrieving the google_enterprise_id for use in downstream **Workflow**s, and validating that the correct EMM instance is associated with the enterprise before managing web tokens or Google Play applications.\n\n**Workflow**\n\n1. Call GET /v0/enterprise/{enterprise_id}/emm/ to retrieve the emm_id.\n2. Call this endpoint to confirm the details of a specific EMM instance.", "operationId": "getEMMInstance", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "emm_id", "in": "path", "description": "An integer representing the ID of enterprise.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GoogleEnterprise" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v0/enterprise/{enterprise_id}/emm/{emm_id}/webtoken/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "List webtokens", "operationId": "getWebtokens", "description": "List all web tokens for a Google Enterprise (EMM) instance. Retrieves all web tokens associated with the specified EMM binding, including each token's value, parent_url, active status, and creation timestamp. Retrieve your webtoken from the Apps section of the console by using the inspector's network tab.\n\nAbout Web Tokens\n\nA Google web token is a credential required to access the Managed Google Play interface within the Esper Console. Web tokens are also a key part of the EMM enterprise enrollment **Workflow** — if token generation or retrieval fails, it can block new device onboarding and prevent access to app management features entirely.\n\n**Common Use Cases** \n\nRetrieving existing web tokens to verify their active status before launching the Managed Play Store interface, auditing which parent_url values are authorized for console Google Play Store use, and obtaining a webtoken_id needed to update or delete a specific token.\n\n**Workflow**\n\n1. Call GET /v0/enterprise/{enterprise_id}/emm/ to retrieve the emm_id for the enterprise's Google Enterprise binding.\n2. Call this endpoint to list all existing web tokens and check their active status and associated parent_url.\n3. If a suitable active token exists, use it to access the Managed Google Play interface for app selection, managed configurations, and Play Store customization.", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "emm_id", "in": "path", "description": "An integer representing the ID of enterprise.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_GoogleWebToken" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "Creates a webtoken instance", "description": "We recommend enrolling in EMM (Google Play) through the UI. See [Setting Up Google Play](https://help.esper.io/hc/en-us/articles/12652188061585-Setting-Up-Google-Play-EMM-Enrollment) for more information. Create a new web token for a Google Enterprise (EMM) instance. Generates a new web token scoped to a specified parent_url, which can then be used to access the Managed Google Play interface within the Esper Console or a custom management application. Returns the created token including its id, token value, parent_url, and active status.\n\nRequired request body fields\n\nemm — the integer ID of the EMM instance (from GET /v0/enterprise/{enterprise_id}/emm/)\n\nparent_url — the URL of the application that will host the Play Store iFrame; must use the https scheme", "operationId": "createWebtoken", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "emm_id", "in": "path", "description": "An integer representing the ID of enterprise.", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GoogleWebTokenUpdate" } } }, "required": true }, "responses": { "201": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GoogleWebToken" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v0/enterprise/{enterprise_id}/emm/{emm_id}/webtoken/{webtoken_id}": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "Get webtoken instance", "description": "Get a specific web token for a Google Enterprise (EMM) instance. See [Setting Up Google Play](https://help.esper.io/hc/en-us/articles/12652188061585-Setting-Up-Google-Play-EMM-Enrollment) for more information. Retrieves the details of a single web token identified by webtoken_id, including its token value, associated emm ID, parent_url, active status, and creation timestamp.\n\n**Common Use Cases** Verifying the active status and parent_url of a specific token before using it to render the Managed Google Play iFrame, retrieving token details for auditing or troubleshooting app management issues, and confirming a token's configuration before updating or deleting it.\n\n**Workflow**:\n\n1. Call GET /v0/enterprise/{enterprise_id}/emm/ to retrieve the emm_id for the enterprise's Google Enterprise binding.\n2. Call GET /v0/enterprise/{enterprise_id}/emm/{emm_id}/webtoken/ to list all web tokens and identify the webtoken_id for the token you want to inspect.\n4. Call this endpoint to retrieve the full details of the specific token.\n5. If the token is active and the parent_url is correct, use the token value to authenticate the Managed Google Play iFrame.\n6. Use PUT /v0/enterprise/{enterprise_id}/emm/{emm_id}/webtoken/{webtoken_id}/ to update the token, or DELETE to remove it if it is no longer needed. After deleting, reach out to Esper Support.", "operationId": "getWebtokenInstance", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "emm_id", "in": "path", "description": "An integer representing the ID of enterprise.", "required": true, "schema": { "type": "integer" } }, { "name": "webtoken_id", "in": "path", "description": "An integer identifying the webtoken.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GoogleWebToken" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "Updates webtoken instance", "description": "See [Setting Up Google Play](https://help.esper.io/hc/en-us/articles/12652188061585-Setting-Up-Google-Play-EMM-Enrollment) for more information. We generally recommend updating the token via the UI. Update a specific web token for a Google Enterprise (EMM) instance. Performs a full replacement of the web token record identified by webtoken_id, updating its configuration and returning the updated token object.\n\nRequired request body fields:\n\nemm — the integer ID of the EMM instance (from GET /v0/enterprise/{enterprise_id}/emm/)\nparent_url — the URL of the application that will host the Play Store iFrame; must use the https scheme", "operationId": "updateWebtokenInstance", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "emm_id", "in": "path", "description": "An integer representing the ID of enterprise.", "required": true, "schema": { "type": "integer" } }, { "name": "webtoken_id", "in": "path", "description": "An integer identifying the webtoken.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GoogleWebTokenUpdate" } } } }, "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GoogleWebToken" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "patch": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "Patches webtoken instance", "description": "We recommend handling EMM updates through the UI. See [Setting Up Google Play](https://help.esper.io/hc/en-us/articles/12652188061585-Setting-Up-Google-Play-EMM-Enrollment) for more information. Partially update a specific web token for a Google Enterprise (EMM) instance. Applies a partial update to the web token record identified by webtoken_id, modifying only the fields included in the request body and returning the updated token object. \n\nUpdatable fields:\n\nemm — the integer ID of the associated EMM instance\nparent_url — the URL of the application hosting the Play Store iFrame; must use the https scheme\nis_active — whether the token is currently active", "operationId": "patchWebtokenInstance", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "emm_id", "in": "path", "description": "An integer representing the ID of enterprise.", "required": true, "schema": { "type": "integer" } }, { "name": "webtoken_id", "in": "path", "description": "An integer identifying the webtoken.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GoogleWebTokenUpdateNoRequirements" } } } }, "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GoogleWebToken" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "Deletes a webtoken instance", "description": "We recommend unenrollment from the UI. See [Setting Up Google Play](https://help.esper.io/hc/en-us/articles/12652188061585-Setting-Up-Google-Play-EMM-Enrollment) for more information. Delete a specific web token for a Google Enterprise (EMM) instance. Permanently removes the web token identified by webtoken_id from the specified EMM instance. Returns an empty response on success (204 No Content). Reach out to Esper Support after unsubscribing from Managed Google Play. ", "operationId": "deleteWebtokenInstance", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "emm_id", "in": "path", "description": "An integer representing the ID of enterprise.", "required": true, "schema": { "type": "integer" } }, { "name": "webtoken_id", "in": "path", "description": "An integer identifying the webtoken.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The resource was deleted successfully." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v0/enterprise/{enterprise_id}/emm/{emm_id}/product/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "List Google Play applications", "description": "List all Google Play applications approved for a Google Enterprise (EMM) instance. See [Managing Google Play Apps](https://help.esper.io/hc/en-us/articles/12652339776401-Managing-Google-Play-Store-Apps) for more information. Retrieves a paginated list of Google Play apps that have been approved and associated with the specified EMM binding, including each app's google_product_id, package_name, title, icon_url, min_sdk_version, active status, and approval state. Results can be filtered by google_product_id, package_name, or creation and update timestamps.\n\nAbout Google Play Products\n\n When an enterprise enrolls in Google EMM, administrators approve specific apps from the Google Play Store for use across their GMS device fleet. Each approved app is represented as a product record tied to the EMM instance. These product records are the foundation for silent app installation and Play Store customization — only apps that appear in this list can be silently pushed to devices or made available to end users through the managed Play Store.\n\nAvailable query parameters\n\ngoogle_product_id — filter by the Google product ID (formatted as app:, e.g. app:com.android.chrome)\npackage_name — filter by the app's package name\ncreated_on — filter by the date the product record was created\nupdated_on — filter by the date the product record was last updated\nlimit / offset — for pagination (default page size: 20)\n\n**Workflow**:\n\n1. Call GET /v0/enterprise/{enterprise_id}/emm/ to retrieve the emm_id for the enterprise's Google Enterprise binding.\n2. Call this endpoint to retrieve the list of approved Google Play apps and identify the google_product_id or id for the app you want to work with.\n3. Use GET /v0/enterprise/{enterprise_id}/emm/{emm_id}/product/{product_id}/ to retrieve full details for a specific app.", "operationId": "getGoogleApps", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "emm_id", "in": "path", "description": "An integer representing the ID of enterprise.", "required": true, "schema": { "type": "integer" } }, { "name": "google_product_id", "in": "query", "description": "filter by Google product id", "schema": { "type": "string" } }, { "name": "package_name", "in": "query", "description": "filter by package name", "schema": { "type": "string" } }, { "name": "created_on", "in": "query", "description": "filter by date app created", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_on", "in": "query", "description": "filter by date app updated", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "description": "Return results from this index.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_GoogleProduct" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "Post a Google play application", "description": "Approves a Google Play application for a Google Enterprise (EMM) instance.\n\nRegisters a Play Store app (identified by its Google product identifier) as approved/managed for the specified Google Enterprise binding, making it available for install on GMS-enabled Android devices.\n\n**About Google EMM Managed Play Products**\nWe generally recommend approving and managing Google Play applications through the Console Google Play Store rather than this API — see Managing Google Play Store Apps in the help center. This endpoint exists for automation scenarios where app approval needs to happen programmatically as part of an enrollment or provisioning pipeline.\n\n**Key Fields / Query Parameters**\n- `emm_id` — UUID of the Google Enterprise (EMM) binding to add the app to\n- `google_product_id` — Google's own identifier for the Play Store product — distinct from Esper's internal product id\n- `package_name` — Android package name of the app (e.g., com.example.app)\n- `is_active` — Whether the app is active/approved for use\n- `min_sdk_version` — Minimum Android SDK version the app requires\n\n**Common Use Cases**\n- Automating Play Store app approval as part of a scripted EMM enrollment flow\n- Bulk-adding a set of approved apps when onboarding a new Google Enterprise binding\n- Keeping an external app catalog in sync with Esper's managed Play Store apps\n\n**Best Practices**\n- Use the Console Google Play Store UI for one-off approvals — reserve this endpoint for automation\n- Confirm the emm_id corresponds to an active Google Enterprise binding before adding products\n- Track package_name alongside Esper's internal id, since Google's product identifiers and Esper's UUIDs are not interchangeable\n\n**Workflow**\n1. Confirm the target emm_id via GET /v0/enterprise/{enterprise_id}/emm/{emm_id}/\n2. POST the app's package_name and Google product details to this endpoint\n3. Verify the app appears via GET /v0/enterprise/{enterprise_id}/emm/{emm_id}/product/\n", "operationId": "addGoogleApp", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "emm_id", "in": "path", "description": "An integer representing the ID of enterprise.", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GoogleProduct" } } }, "required": true }, "responses": { "201": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GoogleProduct" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v0/enterprise/{enterprise_id}/emm/{emm_id}/product/{product_id}": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "Get application information", "description": "Get a specific Google Play application from a Google Enterprise (EMM) instance. Retrieves the full details of a single Google Play product record identified by product_id, including its google_product_id, package_name, title, icon_url, min_sdk_version, active status, and approval state.\n\n**Common Use Cases** \n\nConfirming the google_product_id and active status of a specific app before using it in a silent install command, verifying that an app's approval state is valid after it has been added to the EMM instance, and retrieving full product details for auditing or troubleshooting app deployment issues.\n\n**Best Practices** \n\nUse GET /v0/enterprise/{enterprise_id}/emm/{emm_id}/product/ first to list all product records and obtain the product_id (the Esper-generated UUID id field in the response) before calling this endpoint.", "operationId": "getAppInfo", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "emm_id", "in": "path", "description": "An integer representing the ID of enterprise.", "required": true, "schema": { "type": "integer" } }, { "name": "product_id", "in": "path", "description": "A string identifying the product.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GoogleProduct" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "Update application instance", "description": "Update or approve a specific Google Play application for a Google Enterprise (EMM) instance. We recommend handling Google Play application modifications via the UI. See [Managing Google Play Store Apps](https://help.esper.io/hc/en-us/articles/12652339776401-Managing-Google-Play-Store-Apps) for more information.", "operationId": "updateAppInfo", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "emm_id", "in": "path", "description": "An integer representing the ID of enterprise.", "required": true, "schema": { "type": "integer" } }, { "name": "product_id", "in": "path", "description": "A string identifying the product.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "*/*": { "schema": { "type": "object", "properties": { "icon_url": { "type": "string", "format": "url" }, "is_active": { "title": "Is Active", "type": "boolean" }, "updated_on": { "type": "string", "format": "date-time" }, "min_sdk_version": { "title": "Minimum SDK Version", "type": "integer" }, "unapproved": { "type": "boolean", "title": "Unapproving an app deletes it" } } } } }, "required": false }, "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GoogleProduct" } } } }, "204": { "description": "The resource was deleted successfully." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "patch": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "Patch application instance", "description": "Partially update specific fields of a managed Google Play application for a Google Enterprise (EMM) instance. We recommend handling Google Play application modifications via the UI. See [Managing Google Play Store Apps](https://help.esper.io/hc/en-us/articles/12652339776401-Managing-Google-Play-Store-Apps) for more information.", "operationId": "patchAppInfo", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "emm_id", "in": "path", "description": "An integer representing the ID of enterprise.", "required": true, "schema": { "type": "integer" } }, { "name": "product_id", "in": "path", "description": "A string identifying the product.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "*/*": { "schema": { "type": "object", "properties": { "icon_url": { "type": "string", "format": "url" }, "is_active": { "title": "Is Active", "type": "boolean" }, "updated_on": { "type": "string", "format": "date-time" }, "min_sdk_version": { "title": "Minimum SDK Version", "type": "integer" } } } } }, "required": false }, "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_PatchGoogleProduct" } } } }, "204": { "description": "The resource was deleted successfully." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "Delete application instance", "description": "Delete application. Permanently removes an application from the enterprise. This action deletes the application record and its associated metadata, preventing it from being assigned to devices, policies, or blueprints. Once deleted, the application cannot be managed or distributed unless it is re-uploaded.\n\n**Common Use Cases** \n\nRemoving deprecated or unsupported applications, cleaning up unused or test applications, eliminating duplicate entries, or decommissioning applications that are no longer approved for distribution.\n\n**Best Practices**\n\nBefore deleting an application, download a copy for backup and archival purposes. To do this, navigate to the Apps section in the console and download the application package. Deletion is permanent and cannot be undone.\n\nAdditionally, ensure the application is not referenced in any blueprints prior to deletion. An application associated with a blueprint must be removed from that blueprint before it can be successfully deleted. Review device and blueprint assignments to avoid unintended disruption.\n\n**Workflow**\n\nUse the List apps in enterprise endpoint to retrieve the application_id.\n\nCheck whether the application is present in any blueprints by calling:\nGET https://{foo}-api.esper.cloud/api/v2/blueprints/\n\nIf the application appears in one or more blueprints, note the relevant blueprint_id values.\n\nFor each affected blueprint, update it to remove the application entry by calling:\nPUT https://{foo}-api.esper.cloud/api/v2/blueprints/{blueprint_id}/\n\nAfter the application has been removed from all blueprints, call this endpoint with the application_id to permanently delete the application from the enterprise.", "operationId": "deleteAppInstance", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "emm_id", "in": "path", "description": "An integer representing the ID of enterprise.", "required": true, "schema": { "type": "integer" } }, { "name": "product_id", "in": "path", "description": "A string identifying the product.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The resource was deleted successfully." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v0/enterprise/{enterprise_id}/emm/{emm_id}/product/{product_id}/install/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "List product installations", "description": "List all installation records for Google Play applications on a Google Enterprise (EMM) instance. Retrieves a paginated list of installation records for the specified product, each representing the install state of the app on a specific GMS device. Results can be filtered by Google device ID, install state, version code, creation timestamp range, and active status. \n\n\n**Best Practices** \n\nCall GET /v0/enterprise/{enterprise_id}/emm/{emm_id}/product/ to retrieve the Esper-generated id UUID for the app you want to audit — this is the value used as product_id in the path.", "operationId": "listProducts", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "emm_id", "in": "path", "description": "An integer representing the ID of enterprise.", "required": true, "schema": { "type": "integer" } }, { "name": "product_id", "in": "path", "description": "A string identifying the product.", "required": true, "schema": { "type": "string" } }, { "name": "google_product", "in": "query", "description": "Filter by Google product", "schema": { "type": "string" } }, { "name": "google_device", "in": "query", "description": "Filter by Google device", "schema": { "type": "string" } }, { "name": "install_state", "in": "query", "description": "Filter by install state", "schema": { "type": "string" } }, { "name": "version_code", "in": "query", "description": "Filter by version code", "schema": { "type": "string" } }, { "name": "created_on_gt", "in": "query", "description": "filter installations created after a given timestamp", "schema": { "type": "string", "format": "datetime" } }, { "name": "created_on_lt", "in": "query", "description": "filter installations created before a given timestamp", "schema": { "type": "string", "format": "datetime" } }, { "name": "is_active", "in": "query", "description": "filter by active installations", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_GoogleProductInstall" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v1/enterprise/{enterprise_id}/applications-minimal/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application" ], "summary": "Gets minimum information regarding application", "description": "List minimal application information for all applications in the enterprise. Returns a lightweight list containing only the id (UUID) and package_name for each application uploaded to the enterprise. Use this endpoint instead of the full application list endpoints when you only need to look up an application_id by package name, or build a quick reference map of all applications in the enterprise without the overhead of retrieving full application metadata.\n\nThis endpoint returns Android applications only. For other platforms, use the following alternatives:\n\niOS (tenant/enterprise apps): GET /v2/tenant-apps/ — returns iOS IPAs and supports filtering by package_name and app_name\niOS (VPP and App Store apps): GET /v2/ios-apps/ — returns information about VPP-managed and App Store iOS apps\niOS (unified app list including webclips): GET /v2/apps/ — returns a unified list of iOS apps and webclips for the tenant\n\n**Workflow**\n\nCall this endpoint to retrieve the full list of Android application id and package_name pairs for the enterprise.\nIdentify the application_id UUID for the package you want to work with.\nUse GET /v1/enterprise/{enterprise_id}/application/{application_id}/version/ to retrieve available versions for that application.\nUse the version_id from step 3 in POST /commands/v0/commands/ to issue an install command to target devices.", "operationId": "getMinAppInfo", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "package_name": { "type": "string" } } } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/enterprise/{enterprise_id}/device/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_AndroidDevice" ], "summary": "Fetch all devices in an enterprise", "description": "⚠️ Android only. This endpoint applies exclusively to Android-managed devices enrolled in Esper. For other devices, use the other device management endpoints.\n\nLists all devices enrolled in an enterprise, with rich filtering options.\n\nReturns a paginated collection of DeviceInfo records with filters for device name, group, IMEI, serial number, state, brand, GMS support, tags, blueprint assignment, and more. Default page size is 20.\n\nAbout List Enterprise Devices\n\nDevices in Esper represent Android endpoints enrolled under enterprise management. Each device record contains hardware identifiers (IMEI, serial), current state, group membership, blueprint assignment, and status metadata. The group filter traverses the full subtree — filtering by a parent group will include all devices in its subgroups. This endpoint is the primary entry point for fleet-wide device discovery and inventory.\n\n**Key Query Parameters**\n\nname — filter by device display name\ngroup — filter by group UUID; returns all devices in that group and all of its subgroups\nimei — filter by IMEI number\nserial — filter by device serial number\nstate — filter by enrollment state (see DeviceStateEnum)\nbrand — filter by device manufacturer/brand\nis_gms — filter for GMS (Google Mobile Services)-capable devices\nsearch — free-text search across device name, IMEI, and MAC address\ntags — partial text search across device tags\nassigned_blueprint_id — filter devices by their assigned blueprint UUID\ncurrent_blueprint_id — filter devices by the blueprint currently applied\ncurrent_blueprint_version_id — filter by the specific blueprint version currently applied\nlimit — results per page (default: 20)\n\n**Common Use Cases**\n\nEnumerate all devices in a specific group (including subgroups) for bulk operations or reporting\nSearch for a device by serial number or IMEI when responding to a field support request\nFilter by blueprint assignment to identify devices running a specific configuration or a stale blueprint version\n\n**Best Practices**\n\nUse the group filter to scope operations to a target group's subtree rather than processing the full enterprise list\nCombine search with state to quickly isolate enrolled-but-offline devices in large fleets\nUse assigned_blueprint_id vs. current_blueprint_id deliberately — a device may have a new blueprint assigned but not yet applied\n\n**Workflow**\n\nCall this endpoint with relevant filters (group, state, blueprint) to identify the target device set\nCollect device_id values from the paginated results\nUse individual device IDs for detail lookups, command dispatch, or app queries", "operationId": "getAllDevices", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "ID of the enterprise", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "name", "in": "query", "description": "filter by device name", "schema": { "type": "string" } }, { "name": "group", "in": "query", "description": "filter by group id. It will list all the devices under this group including the subgroups", "schema": { "type": "string", "format": "uuid" } }, { "name": "imei", "in": "query", "description": "filter by imei", "schema": { "type": "string" } }, { "name": "serial", "in": "query", "description": "filter by serial number", "schema": { "type": "string" } }, { "name": "state", "in": "query", "schema": { "$ref": "#/components/schemas/esper_cloud_api_DeviceStateEnum" } }, { "name": "brand", "in": "query", "description": "filter by brand", "schema": { "type": "string" } }, { "name": "is_gms", "in": "query", "description": "filter for gms devices", "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "description": "A search term. Search by device name, imei or mac address", "schema": { "type": "string" } }, { "name": "tags", "in": "query", "description": "A partial text search for device tags", "schema": { "type": "string" } }, { "name": "assigned_blueprint_id", "in": "query", "description": "Filter by assigned blueprint id", "schema": { "type": "string", "format": "uuid" } }, { "name": "current_blueprint_id", "in": "query", "description": "Filter by current blueprint id", "schema": { "type": "string", "format": "uuid" } }, { "name": "current_blueprint_version_id", "in": "query", "description": "Filter by current blueprint version id", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "description": "Return results from this index.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "format": "int64" }, "next": { "type": "string", "format": "url" }, "previous": { "type": "string", "format": "url" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_DeviceInfo" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/enterprise/{enterprise_id}/device/{device_id}/": { "get": { "x-badges": [ { "name": "Legacy", "color": "orange" } ], "tags": [ "esper_cloud_api_AndroidDevice" ], "summary": "Fetch device details by ID", "description": "⚠️ Android only. This endpoint applies exclusively to Android-managed devices enrolled in Esper. \n\nAlternative Available\n\nUse the v2 endpoint /v2/devices/{id} for an updated and forward-compatible device model, especially in multi-OS environments.\n\nRetrieves the full DeviceInfo record for a single enrolled device by its UUID.\nReturns comprehensive device metadata including hardware identifiers, enrollment state, group membership, applied and assigned blueprint versions, and status information. Use when you already have a device_id and need complete, authoritative device detail.\n\nAbout Get Device\n\nThe DeviceInfo object is Esper's full representation of an enrolled Android device. It includes all fields returned in list results, plus any additional status and configuration detail associated with the device's current enrollment state. Device IDs are stable UUIDs and do not change after enrollment; they are the primary reference for all device-specific API operations — commands, app installs, event feeds, and status queries.\n\nKey Fields\n\ndevice_id — path parameter UUID; Esper's stable internal identifier for this device\n\nBlueprint fields — reflect the gap between assigned_blueprint_id (what's intended) and current_blueprint_id / current_blueprint_version_id (what's applied)\n\nEnrollment state — current device lifecycle state (see DeviceStateEnum)\n\n**Common Use Cases**\n\nRetrieve full device details after discovering a device_id from a list or event payload\n\nConfirm current enrollment state before issuing a command or checking compliance\n\nInspect blueprint assignment vs. applied blueprint to detect configuration drift\n\n**Best Practices**\n\nUse this endpoint for authoritative single-device lookups rather than scanning list results — it avoids pagination overhead and returns a complete record.\nCheck state before dispatching commands; commands may not execute on devices in offline or unenrolled states.\nStore the device_id UUID in your system — it is the stable key for all downstream device operations and does not change.\n\n**Workflow**\n\nObtain device_id from a device list call, enrollment event, or stored reference.\nCall this endpoint to retrieve the full DeviceInfo record.\nUse the returned state and configuration data to determine the appropriate next action (command, install, group operation).", "operationId": "getDeviceById", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "ID of the enterprise", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "device_id", "in": "path", "description": "ID of the device", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_DeviceInfo" } } } }, "400": { "description": "Bad request" } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/enterprise/{enterprise_id}/device/{device_id}/app/": { "get": { "x-badges": [ { "name": "Legacy", "color": "orange" } ], "tags": [ "esper_cloud_api_AndroidDevice" ], "summary": "List all device apps", "description": "⚠️ Android only. This endpoint applies exclusively to Android-managed devices enrolled in Esper. \nAlternative Available\n\nFor iOS and Windows device applications, use /api/v2/tenant-esper-apps\n\nLists all apps present on a specific enrolled device, as tracked by Esper.\nReturns a paginated DeviceApp collection reflecting the apps Esper is aware of on the device, filterable by package name or app name. Default page size is 20.\n\nAbout List Device Apps\n\nThe DeviceApp resource represents the per-device app inventory as seen by Esper — each record corresponds to an app instance on the device, tied to the device's reported state. This differs from the enterprise application library (.../application/) which tracks apps available for deployment; the device app list reflects what is actually installed and known on a given device. Results can be filtered by package name for precise lookups or searched by app name for broader discovery.\n\n**Key Query Parameters**\n\npackage_name — filter by exact Android package name (e.g. com.example.app)\n\nwhitelisted — filter by whitelist status\n\nsearch — free-text search by app name (app_name field)\n\nlimit — results per page (default: 20)\n\n**Common Use Cases**\n\nAudit which apps are installed on a specific device for compliance or security review.\nVerify that a target app (by package name) is present on the device before or after an install command.\nCheck whitelist status of installed apps on a managed device.\n\n**Best Practices**\n\nUse package_name for targeted lookups rather than fetching the full list and filtering client-side.\nCross-reference results with the enterprise application library to identify apps on the device that are not managed through Esper.\nConfirm app presence via this endpoint after issuing an install command to verify successful delivery.\n\n**Workflow**\n\nObtain the device_id from a device list or stored reference.\nCall this endpoint, optionally filtering by package_name or search.\nReview the returned DeviceApp records to confirm installation state and whitelist status.", "operationId": "getDeviceApps", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "device_id", "in": "path", "description": "A UUID string identifying device.", "required": true, "schema": { "type": "string" } }, { "name": "package_name", "in": "query", "description": "Filter by Package name", "schema": { "type": "string" } }, { "name": "whitelisted", "in": "query", "description": "Whitelist filter", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "A search term. Search by app_name.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "description": "Return results from this index.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_DeviceApp" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/enterprise/{enterprise_id}/device/{device_id}/app/{app_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_AndroidDevice" ], "summary": "Get device app details", "description": "Get details of a specific app installed on an Android device. Retrieves the full DeviceApp record for a single app identified by app_id on the specified Android device, including the app's app_name, package_name, state, app_type, version_code, version_name, is_active, is_kiosk_app, is_esper_controlled, whitelisted, is_data_clearable, and is_uninstallable fields.\n\n**Workflow**\n\nCall this endpoint to retrieve the full list of Android application id and package_name pairs for the enterprise.\nIdentify the application_id UUID for the package you want to work with.\nUse GET /v1/enterprise/{enterprise_id}/application/{application_id}/version/ to retrieve available versions for that application.\nUse the version_id from step 3 in POST /commands/v0/commands/ to issue an install command to target devices.", "operationId": "getDeviceAppById", "parameters": [ { "name": "app_id", "in": "path", "description": "A UUID string identifying this device app.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this device.", "required": true, "schema": { "type": "string" } }, { "name": "device_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_DeviceApp" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/enterprise/{enterprise_id}/device/{device_id}/install/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_AndroidDevice" ], "summary": "List installed apps", "description": "Get details of a specific app installed on an Android device. Retrieves the full DeviceApp record for a single app identified by app_id on the specified Android device, including the app's app_name, package_name, state, app_type, version_code, version_name, is_active, is_kiosk_app, is_esper_controlled, whitelisted, is_data_clearable, and is_uninstallable fields.\n\nThis endpoint is for Android devices only. For other platforms use the following alternatives:\n\niOS and other non-Android devices: GET /v2/devices/{deviceId}/device-apps/ — returns apps for a device and supports filtering by app type including VPP, TENANT_IOS, ESPER_IOS, WEBCLIP, ESPER_WINDOWS, and TENANT_WINDOWS\n\n**Common Use Cases** \n\nRetrieving the full details of a specific app on an Android device to check its current state, version, or kiosk configuration, confirming whether an app is set as the kiosk app (is_kiosk_app: true) on a device, verifying app attributes such as is_uninstallable or is_data_clearable before issuing an uninstall or data-clear command, and auditing whether a specific app is whitelisted on a device.\n\n\n**Workflow**\n\n1. Call GET /enterprise/{enterprise_id}/device/{device_id}/app/ and filter by package_name to locate the app and retrieve its app_id.\n2. Call this endpoint to retrieve the full DeviceApp record for that specific app.\n3. Check state, version_code, and is_active to confirm the app's current status on the device.", "operationId": "getAppInstalls", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "device_id", "in": "path", "description": "A UUID string identifying device.", "required": true, "schema": { "type": "string" } }, { "name": "device", "in": "query", "description": "filter by device id", "schema": { "type": "string" } }, { "name": "package_name", "in": "query", "description": "filter by package name", "schema": { "type": "string" } }, { "name": "application_name", "in": "query", "description": "filter by application name", "schema": { "type": "string" } }, { "name": "install_state", "in": "query", "description": "filter by install state", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "description": "Return results from this index.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_AppInstall" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/enterprise/{enterprise_id}/device/{device_id}/status/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_AndroidDevice" ], "summary": "Get latest device event", "description": "Get the latest status event for an Android device. Retrieves the most recent DeviceStatus record for the specified Android device, containing a data payload with the device's current telemetry snapshot — including battery, connectivity, memory, storage, and other real-time device state information — along with the associated device and enterprise references and the event created_on timestamp.\nThis endpoint is for Android devices only. For other platforms, use the following alternatives:\n\niOS, Linux, and Windows devices: GET /device/v0/devices/{id}/devicestate — returns current device state for non-Android platforms\nAndroid (v2): GET /v2/devices/{id}/ — returns a broader Android device record including current state fields in a more structured format\n\nNote The latest_event query parameter must be set to 1 to return the most recent status event. Without this parameter the endpoint may return a paginated list of historical status records rather than the current snapshot.\n**Common Use Cases** Retrieving a real-time telemetry snapshot of an Android device's current state before issuing commands, checking battery level, connectivity, and storage availability as part of a pre-deployment health check, monitoring device state in custom dashboards or alerting **Workflow**s, and diagnosing device issues by reviewing the most recent reported status.\n\n**Best Practices** \n\nAlways include latest_event=1 when you need the current device state rather than historical events — omitting it may return a paginated history rather than the snapshot you expect. For broader device metadata including policy assignments, group membership, and hardware information, use GET /enterprise/{enterprise_id}/device/{device_id}/ instead. For a full history of device events over time, use GET /enterprise/{enterprise_id}/device/{device_id}/report/eventfeed/.", "operationId": "getDeviceEvent", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "device_id", "in": "path", "description": "A UUID string identifying device.", "required": true, "schema": { "type": "string" } }, { "name": "latest_event", "in": "query", "description": "Returns the latest event. Must be set to 1.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_DeviceStatus" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/enterprise/{enterprise_id}/device/{device_id}/download/eventfeed/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_AndroidDevice" ], "summary": "Download Event Feed for Device", "description": "Download the event feed for an Android device. Retrieves a paginated, chronologically ordered list of EventFeed records for the specified Android device, each containing an event id, message_id, device_status_id, created_on timestamp, and a message describing what occurred — including commands issued, who issued them, and from which state they were issued. Results default to 250 records per page.\n\nThis endpoint is for Android devices only. For group-level event history, use GET /enterprise/{enterprise_id}/group/{group_id}/download/eventfeed/ instead.\n\nAbout the Event Feed\n\nThe event feed is a chronological record of activity on a device, capturing commands, state transitions, and other significant events. It is the primary source for auditing device history, investigating incidents, and understanding the sequence of operations performed on a device. Each event links back to a device_status_id, which can be used to retrieve the full telemetry snapshot associated with that event.\nAvailable query parameters:\n\nlimit — number of results per page (default: 250)\noffset — pagination offset (default: 0)\n\n**Common Use Cases** \n\nAuditing the full history of commands issued to a specific Android device, investigating device incidents by reviewing the sequence of events leading up to a failure or unexpected state change, downloading a complete event log for offline analysis or compliance reporting, and correlating device events with command requests to verify that operations were executed as expected.\n\n**Best Practices** \n\nFor large event histories, use limit and offset to paginate through results rather than fetching everything in a single call. If you only need the most recent device status snapshot rather than a full event history, use GET /enterprise/{enterprise_id}/device/{device_id}/status/?latest_event=1 instead — it is significantly lighter. For the Esper Console timeline view of device events, use GET /v1/enterprise/{enterprise_id}/device/{device_id}/report/eventfeed/ instead, which returns the same data with a smaller default page size suited to UI rendering.\n\n**Workflow**\n\n1. Call GET /enterprise/{enterprise_id}/device/{device_id}/ to confirm the device details and retrieve the device_id.\n2. Call this endpoint to retrieve the full chronological event feed for the device.\n3. Use message and created_on to identify the events relevant to your investigation or audit.\n4. Use device_status_id from a specific event to retrieve the associated telemetry snapshot via GET /enterprise/{enterprise_id}/device/{device_id}/status/ if deeper context is needed.", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "device_id", "in": "path", "description": "A UUID string identifying the device", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer", "default": 250 } }, { "name": "offset", "in": "query", "description": "Return results from this index.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_EventFeed" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/enterprise/{enterprise_id}/group/{group_id}/download/eventfeed/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_AndroidDevice" ], "summary": "Download Event Feed for Group", "description": "Download the event feed for an Android device group. Retrieves a paginated, chronologically ordered list of command request records for the specified group, each containing details of operations issued to the group. Results default to 250 records per page.\n\nThis endpoint is for Android device groups only. For device-level event history, use GET /enterprise/{enterprise_id}/device/{device_id}/download/eventfeed/ instead.\nAbout the Group Event Feed: The group event feed provides a chronological record of command requests issued at the group level, making it the primary source for auditing bulk operations across a device group. Rather than reviewing events device by device, this endpoint surfaces the group-level commands that were dispatched — useful for understanding the sequence of operations applied to a group as a whole, and for correlating group-level actions with individual device outcomes.\n\n**Common Use Cases** \n\nAuditing the history of commands issued to a specific Android device group, investigating incidents by reviewing the sequence of group-level operations leading up to an unexpected fleet state, downloading a complete group command log for offline analysis or compliance reporting, and verifying that scheduled or bulk operations were dispatched to the group as expected.\n\n**Best Practices** \n\nUse limit and offset to paginate through results for groups with long command histories rather than fetching everything in a single call. For individual device-level event history within the group, use GET /enterprise/{enterprise_id}/device/{device_id}/download/eventfeed/ per device. To check the execution status of a specific command request returned in this feed, use GET /commands/v0/status/?request={request_id} to retrieve per-device status records for that command.\n\nAvailable query parameters\n\nlimit — number of results per page (default: 250)\noffset — pagination offset (default: 0)\n\n**Workflow**\n\n1. Call GET /enterprise/{enterprise_id}/devicegroup/ to list all groups and retrieve the group_id for the group you want to audit.\n2. Call this endpoint to retrieve the chronological command history for that group.\n3. Identify the command requests relevant to your investigation using the event details and timestamps.\n4. Use GET /commands/v0/status/?request={request_id} to retrieve per-device execution status for any specific command request returned in the feed.", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "group_id", "in": "path", "description": "A UUID string identifying the group", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer", "default": 250 } }, { "name": "offset", "in": "query", "description": "Return results from this index.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_V0CommandRequest" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v1/enterprise/{enterprise_id}/device/{device_id}/report/eventfeed/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_AndroidDevice" ], "summary": "Lists event feed for device", "description": "List event feed for device. Retrieves a device’s event history, including command activity and system events, in reverse-chronological order. The response is paginated and returns entries in the results array.\n\nAbout Device Event Feed\n\nThe event feed provides an audit trail of significant device lifecycle events — enrollment state transitions, command executions, and status changes — as recorded by Esper. Each record includes a message field that describes the event in plain language (including the command issued and the initiating user), a device_status_id linking to the device status snapshot at the time of the event, and a message_id UUID. This endpoint returns paginated JSON; for bulk export of event history, use the download variant at GET .../device/{device_id}/download/eventfeed/ (default page size: 250). \nThis endpoint is for Event Feed activities for device commands. Use (GET https://{foo}-api.esper.cloud/api/v0/devices/{deviceId}/operations/) for dispatch (Operations) commands. \n\n**Common Use Cases**\n\nAuditing who issued commands and when, tracking command state changes (acknowledged → in progress → success/failure), investigating device activity over time, and correlating events to operational issues.\n\n**Best Practices**\n\nUse limit and pagination (next/previous, or offset) to manage large event histories and reduce response size. When troubleshooting a specific window of time, page in smaller increments to avoid missing relevant events.\n\n**Workflow**\n\nIdentify the device_id using a device listing endpoint.\n\nCall this endpoint with the device_id to retrieve the device’s event feed.\n\nFollow the next URL (or increment offset) until you’ve collected the events you need.\n\nLearn more: https://help.esper.io/hc/en-us/articles/43110064004881-What-Are-Device-Commands", "operationId": "getEventFeed", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "device_id", "in": "path", "description": "A UUID string identifying the device", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "description": "Return results from this index.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_EventFeed" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/enterprise/{enterprise_id}/devicegroup/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Device Group" ], "summary": "List device groups", "description": "Returns a paginated list of all device groups in the enterprise. Device groups organize devices into logical collections by location, use case, or deployment stage, and serve as the primary unit for policy assignment, app deployment, and bulk commands.\n\n **Common Use Cases** \n \n Discovering group IDs for downstream operations; auditing group structure; populating group selectors in custom tools; confirming a group exists before assigning devices or Blueprints.\n\n**Best Practices** \n\nUse the `name` query parameter to filter instead of fetching all groups; cache group IDs for use in commands and policy calls; paginate with `limit` and `offset` for large enterprises.", "operationId": "getAllGroups", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "Filter by group name", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_DeviceGroup" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Device Group" ], "summary": "Create a device group", "description": "Creates a new device group within the enterprise. Device groups organize devices into logical collections for policy assignment, app deployment, Blueprint application, and bulk command targeting. Groups can be nested — pass a parent group ID to create a subgroup within an existing group hierarchy.\n\nRequest body fields\n\nname (required) — Display name for the new group\nparent (optional) — UUID of the parent group; omit to create a top-level group\ndevice_ids (optional) — Array of device UUIDs to add to the group at creation time\n\n**Common Use Cases**\n\nSetting up a new group before provisioning a batch of devices into it\nCreating subgroups to represent locations, departments, or device roles within a larger fleet segment\nProgrammatically building out a group hierarchy as part of an onboarding or deployment **Workflow**\n\n**Best Practices**\n\nGroup names should be descriptive and consistent with your naming convention — they appear throughout the Console and API responses\nYou can add devices at creation via device_ids, or add them later using the update endpoint\nStore the id from the 201 response immediately — it's required for all subsequent group operations (policy assignment, commands, Blueprint targeting, etc.)\nUse GET /enterprise/{enterprise_id}/devicegroup/ first to confirm the group doesn't already exist before creating a duplicate", "operationId": "createGroup", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_DeviceGroupUpdate" } } }, "required": true }, "responses": { "201": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_DeviceGroup" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ], "x-codegen-request-body-name": "data" } }, "/enterprise/{enterprise_id}/devicegroup/{group_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Device Group" ], "summary": "Get device group information", "description": "Retrieves full details for a single device group by its UUID.\n\nUse this endpoint to fetch group metadata — including name, device count, child group count, hierarchy path, and associated blueprint — when you have a specific group_id and need its current state rather than a paginated list.\nAbout Get Device Group Information\nDevice groups in Esper are hierarchical collections of devices used to organize and apply policies at scale. Each group can have a parent group, child groups, and an associated blueprint that defines the configuration applied to devices in that group. This endpoint returns a snapshot of a single group's metadata and is commonly used to validate group structure before performing bulk operations or blueprint assignments. To retrieve a group_id, use the List Device Groups endpoint first.\n\nKey Fields\n\nid — The group's UUID; use this as group_id in subsequent group-scoped requests\npath — The full hierarchy path of the group within the enterprise's group tree\nparent — URL reference to the parent group, if the group is nested\ndevice_count — Number of devices directly in this group\nchildren_count — Number of child groups nested under this group\nblueprint — URL reference to the blueprint currently associated with this group\n\n**Common Use Cases**\n\nConfirm a group exists and retrieve its metadata before applying a blueprint or running a pipeline\nInspect a group's position in the hierarchy (path, parent) when managing nested group structures\nVerify device_count before initiating bulk device operations against a group\n\n**Best Practices**\n\nUse List Device Groups to discover group_id values; avoid hardcoding UUIDs across environments\nCheck children_count before deleting a group — child groups must be removed first, and groups containing devices cannot be deleted until devices are moved or removed\nCache group metadata conservatively; group structure can change as devices are enrolled or moved\n\n**Workflow**\n\n1. Call List Device Groups (GET /enterprise/{enterprise_id}/devicegroup/) to find the target group and retrieve its group_id\n2. Call this endpoint with the group_id to fetch full group details\n3. Use the returned blueprint, path, and device_count to inform downstream operations such as blueprint updates, pipeline targeting, or group deletion", "operationId": "getGroupById", "parameters": [ { "name": "group_id", "in": "path", "description": "A UUID string identifying this enterprise device group.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_DeviceGroup" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Device Group" ], "summary": "Update device group", "description": "Fully updates a device group's properties using the action query parameter to specify the operation being performed. This endpoint controls group membership, naming, and hierarchy — use it to add or remove devices, rename a group, or move it to a different parent in the group tree.\n\naction query parameter values\n\nadd — Add the devices specified in device_ids to the group\nremove — Remove the devices specified in device_ids from the group\nrename — Rename the group using the name field\nmove — Move the group under a new parent using the parent field\n\nRequest body fields (DeviceGroupUpdate)\n\nname (required by schema, contextual by action) — Group display name; used with rename\nparent — UUID of the new parent group; used with move\ndevice_ids — Array of device UUIDs to add or remove; used with add / remove\n\n**Common Use Cases**\n\nAdding newly provisioned devices into their target group\nReorganizing a group hierarchy by moving subgroups to a new parent\nRenaming a group to reflect a changed location, team, or deployment role\nRemoving retired or reassigned devices from a group\n\n**Best Practices**\n\nAlways supply the correct action value — omitting it or mismatching it with the body fields will produce unexpected behavior\nFor bulk membership changes, prefer passing all affected device_ids in a single call rather than iterating per device\nUse GET /enterprise/{enterprise_id}/devicegroup/{group_id}/ to verify current group state before and after updates\nFor partial updates (e.g., updating only one field without requiring all required fields), prefer PATCH /enterprise/{enterprise_id}/devicegroup/{group_id}/ instead", "operationId": "updateGroup", "parameters": [ { "name": "group_id", "in": "path", "description": "A UUID string identifying this enterprise device group.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "add / remove / rename / move", "schema": { "type": "string" } } ], "requestBody": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_DeviceGroupUpdate" } } }, "required": true }, "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_DeviceGroup" } } } }, "400": { "description": "User update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ], "x-codegen-request-body-name": "data" }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Device Group" ], "summary": "Delete a device group", "description": "Permanently deletes a device group from the enterprise. The group must be empty — groups containing one or more devices cannot be deleted. Move all member devices to another group first before issuing the delete request.\n\n**Common Use Cases**\n\nRemoving groups that are no longer needed after a deployment phase ends\nCleaning up duplicate or incorrectly named groups\nReorganizing fleet structure by consolidating groups\n\n**Best Practices**\n\nEnsure the group has no devices before calling this endpoint — the operation will fail if any devices remain in the group; use PUT /enterprise/{enterprise_id}/devicegroup/{group_id}/ with action=remove or action=move to empty the group first\nConfirm the group ID is correct using GET /enterprise/{enterprise_id}/devicegroup/{group_id}/ before issuing the delete — this action is irreversible\nCheck for any active Pipelines, Blueprints, or scheduled commands targeting this group before deleting to avoid orphaned configurations\nIf the goal is to reorganize rather than fully remove, consider using action=move to reassign the group to a new parent instead", "operationId": "deleteGroup", "parameters": [ { "name": "group_id", "in": "path", "description": "A UUID string identifying this enterprise device group.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The resource was deleted successfully." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "patch": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Device Group" ], "summary": "Partially update a device group", "description": "Partially updates one or more properties of a device group without requiring all fields to be present in the request body. Like the full update endpoint, the action query parameter specifies the operation being performed — but here only the fields relevant to that action need to be included. Use this endpoint instead of PUT when making a single targeted change, such as renaming a group or adding a small set of devices, without needing to supply the full group object.\n\naction query parameter values\n\nadd — Add the devices specified in device_ids to the group\nremove — Remove the devices specified in device_ids from the group\nrename — Rename the group using the name field\nmove — Move the group under a new parent using the parent field\n\nRequest body fields (all optional)\n\nname — Group display name; used with rename\nparent — UUID of the new parent group; used with move\ndevice_ids — Array of device UUIDs; used with add / remove\n\n**Common Use Cases**\n\nRenaming a group without affecting its membership or hierarchy\nAdding or removing a subset of devices without resending the full group payload\nMoving a group to a new parent as part of a hierarchy reorganization\n\n**Best Practices**\n\nPrefer this endpoint over PUT for single-field changes — it reduces payload size and minimizes the risk of accidentally overwriting other fields\nAlways supply the action query parameter and ensure the body fields match the intended action\nUse GET /enterprise/{enterprise_id}/devicegroup/{group_id}/ to verify the current group state before and after updates", "operationId": "partialUpdateGroup", "parameters": [ { "name": "group_id", "in": "path", "description": "A UUID string identifying this enterprise device group.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "add / remove / rename / move", "schema": { "type": "string" } } ], "requestBody": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_DeviceGroupPartialUpdate" } } }, "required": true }, "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_DeviceGroup" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ], "x-codegen-request-body-name": "data" } }, "/enterprise/{enterprise_id}/devicegroup/thumbnail/": { "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" } ], "tags": [ "esper_cloud_api_Device Group" ], "summary": "Upload a thumbnail pic", "description": "Uploads an image to use as a thumbnail for a device group.\n\nUploads an image file that can subsequently be applied to represent a Device Group visually in the Devices & Groups section of the Esper Console. The image must be at least 180 x 180 px.\n\n**About Device Group Thumbnails**\nDevice Group thumbnails are purely cosmetic — they help admins visually distinguish groups in the Console UI and have no effect on device management, policies, or pipeline targeting.\n\n**Key Fields / Query Parameters**\n- `image_file` — The image file to upload (multipart/form-data)\n\n**Common Use Cases**\n- Uploading a custom icon to visually distinguish a store or region's device group in the Console\n- Building a library of group thumbnail images for a large multi-group organization\n- Standardizing group iconography across an enterprise's Console\n\n**Best Practices**\n- Use recognizable, consistent imagery across groups to make the Console easier to navigate at a glance\n- Check List thumbnail pics first to avoid uploading duplicate images\n- Keep uploaded images reasonably sized for fast loading in the Console UI\n\n**Workflow**\n1. POST the image file to this endpoint\n2. Note the returned thumbnail_id\n3. Reference that thumbnail_id when assigning the image to a device group in the Console or API\n", "operationId": "uploadGroupThumbnail", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "image_file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Thumbnail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GroupThumbnail" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ], "x-codegen-request-body-name": "data" }, "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" } ], "tags": [ "esper_cloud_api_Device Group" ], "summary": "List thumbnail pics", "description": "Lists all group thumbnail images uploaded for the enterprise.\n\nReturns every thumbnail image file previously uploaded for use with Device Groups in the Devices & Groups section of the Console.\n\n**About Device Group Thumbnails**\nDevice Group thumbnails are purely cosmetic images used to visually distinguish groups in the Console UI.\n\n**Common Use Cases**\n- Browsing available thumbnail images before assigning one to a new device group\n- Auditing which thumbnail images are currently uploaded for an enterprise\n- Finding a thumbnail_id needed for the get/delete thumbnail endpoints\n\n**Best Practices**\n- Check this list before uploading a new image to avoid duplicates\n- Remove unused thumbnails periodically to keep the library manageable\n- Use descriptive thumbnail choices so Console users can distinguish groups quickly\n\n**Workflow**\n1. GET this endpoint to list available thumbnails\n2. Use a returned thumbnail_id, or upload a new one via POST if none fit\n3. Apply the thumbnail to a device group in the Console\n", "operationId": "listGroupThumbnail", "security": [ { "esper_cloud_api_apiKey": [] } ], "responses": { "200": { "description": "Thumbnail", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_GroupThumbnail" } } } } } } } } } }, "/enterprise/{enterprise_id}/devicegroup/thumbnail/{thumbnail_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" }, { "$ref": "#/components/parameters/esper_cloud_api_GroupThumbnailID" } ], "tags": [ "esper_cloud_api_Device Group" ], "summary": "Get thumbnail detail", "description": "Retrieves a single device group thumbnail by its ID.\n\nReturns the details of one previously-uploaded thumbnail image, identified by thumbnail_id. Use List thumbnail pics to find available thumbnail IDs.\n\n**About Device Group Thumbnails**\nDevice Group thumbnails are purely cosmetic images used to visually distinguish groups in the Console UI.\n\n**Key Fields / Query Parameters**\n- `thumbnail_id` — ID of the thumbnail image to retrieve\n\n**Common Use Cases**\n- Confirming a specific thumbnail's image URL before applying it to a group\n- Verifying a thumbnail still exists prior to deleting or reassigning it\n- Displaying a specific thumbnail in a custom admin tool built on the Esper API\n\n**Best Practices**\n- Use the list endpoint to find valid thumbnail_id values rather than guessing\n- Re-check a thumbnail's existence here before referencing it elsewhere, since it may have been deleted\n- Cache thumbnail URLs client-side rather than re-fetching repeatedly, since thumbnails rarely change\n\n**Workflow**\n1. List thumbnails to find the target thumbnail_id\n2. GET this endpoint to confirm details before use\n3. Apply the thumbnail_id to a device group as needed\n", "operationId": "getGroupThumbnail", "security": [ { "esper_cloud_api_apiKey": [] } ], "responses": { "200": { "description": "Thumbnail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GroupThumbnail" } } } } } }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" }, { "$ref": "#/components/parameters/esper_cloud_api_GroupThumbnailID" } ], "tags": [ "esper_cloud_api_Device Group" ], "summary": "Delete group thumbnail", "description": "Deletes a device group thumbnail image.\n\nPermanently removes the specified thumbnail image from the enterprise's thumbnail library.\n\n**About Device Group Thumbnails**\nDeleting a thumbnail removes the uploaded image itself. If a device group is currently using this thumbnail, plan to assign a replacement image so the group isn't left without one in the Console UI.\n\n**Key Fields / Query Parameters**\n- `thumbnail_id` — ID of the thumbnail image to delete\n\n**Common Use Cases**\n- Cleaning up unused or outdated thumbnail images\n- Removing an incorrectly uploaded image\n- Maintaining a curated thumbnail library over time\n\n**Best Practices**\n- Confirm no device group still needs this thumbnail before deleting, since deletion is irreversible\n- Use List thumbnail pics to confirm the correct thumbnail_id before deleting\n- Upload a replacement thumbnail first if a group's current image is being retired\n\n**Workflow**\n1. List thumbnails and confirm the thumbnail_id to remove\n2. DELETE using that thumbnail_id\n3. Reassign an alternative thumbnail to any group that was using the deleted image\n", "operationId": "deleteGroupThumbnail", "security": [ { "esper_cloud_api_apiKey": [] } ], "responses": { "204": { "description": "Deleted group thumbnail" }, "401": { "description": "Group thumbnail delete error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } } } }, "/api/v2/subgroups/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Device Group" ], "summary": "List the subgroups of list of groups", "description": "Returns a list of subgroup UUIDs for one or more parent groups. Use the parent_group_ids parameter to specify which parent groups to query, and the immediate parameter to control whether the response includes only direct children or all descendants at every level of the hierarchy.\n\nNote that the response contains only subgroup UUIDs — not full group objects. Use GET /enterprise/{enterprise_id}/devicegroup/{group_id}/ to retrieve full details for any returned group ID.\n\nQuery parameters\n\nparent_group_ids (optional) — Comma-separated list of parent group UUIDs to query; omitting this parameter may return subgroups across all groups\nimmediate (optional, default: false) — When false, returns all descendant subgroups at every level; when true, returns only the immediate (direct) children of the specified parent groups\n\n**Common Use Cases**\n\nTraversing a group hierarchy to discover all subgroups beneath one or more parent groups\nChecking whether a group has children before deciding to delete or restructure it\nCollecting a full list of descendant group IDs to use as targets for bulk operations\n\n**Best Practices**\n\nWhen only direct children are needed, set immediate=true to avoid retrieving the full descendant tree, which may be large in deep hierarchies\nSince the response returns UUIDs only, plan for follow-up calls to GET /devicegroup/{group_id}/ if group names, device counts, or other metadata are required\nUse parent_group_ids to scope the query — querying without it may return more data than expected", "operationId": "getAllSubGroups", "parameters": [ { "name": "parent_group_ids", "in": "query", "description": "Filter by parent group ids. This is a comma separated list of group ids.", "schema": { "type": "string" } }, { "name": "immediate", "in": "query", "description": "This is a boolean value. If true, only immediate subgroups are returned.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "content" ], "type": "object", "properties": { "content": { "items": { "$ref": "#/components/schemas/esper_cloud_api_DeviceSubGroup" } } } } } } }, "400": { "description": "Bad Request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/enterprise/{enterprise_id}/policy/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Enterprise Policy" ], "summary": "List all policies in enterprise", "description": "⚠️ **Legacy feature.** Compliance Policies (along with Templates, which apply them) are a legacy Esper product. For new device configuration work, use Blueprints instead — Compliance Policies remain available for existing Template-based deployments. See Introduction to Compliance Policies: https://help.esper.io/hc/en-us/articles/12653153592977-Introduction-to-Compliance-Policies\n\nRetrieves all Compliance Policies configured for the enterprise.\n\nReturns the enterprise's Compliance Policies — legacy, Template-applied device restriction/permission profiles — with optional filtering by name and active state.\n\n**About Compliance Policies**\nA Compliance Policy is a set of device-configuration permissions and restrictions — screen and unlock behavior (keyguard, safe boot), connectivity (USB, tethering, NFC), communication (SMS, outgoing/incoming calls, dialer), hardware (camera, screenshots), and system controls (factory reset, ADB, side-loading, Play Store, app uninstall, date/time configuration) — that gets applied to a device after it has already been provisioned through a Template. They're commonly used to make a post-provisioning change to a Kiosk-mode device, such as temporarily re-enabling the status bar or ADB to pull a bug report, without re-provisioning the device. Templates and Compliance Policies are legacy Esper products; Blueprints are the current, recommended way to define device configuration for new work.\n\n**Key Fields / Query Parameters**\n- `name` — Filter policies by name\n- `is_active` — Filter to only active (or inactive) policies\n- `limit` — Page size for pagination\n- `offset` — Pagination offset\n\n**Common Use Cases**\n- Auditing which legacy Compliance Policies still exist on Template-provisioned devices\n- Finding an existing policy by name to reuse rather than duplicate on an older Template-based deployment\n- Checking is_active status across all policies during a legacy-device configuration review\n\n**Best Practices**\n- For new device configuration, use Blueprints instead of creating additional Compliance Policies\n- Filter by is_active=true when looking for policies currently in use on legacy Template devices\n- Paginate with limit/offset for enterprises with many policies\n\n**Workflow**\n1. GET this endpoint to review existing Compliance Policies on legacy Template devices\n2. POST a new policy only if the device fleet is still Template-based and not yet migrated to Blueprints\n3. Apply the policy's uuid to devices or groups still on the legacy Template system\n", "operationId": "listPolicies", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "ID of the enterprise", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "name", "in": "query", "description": "filter by policy name", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "description": "filter by Active policies", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "description": "Return results from this index.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_EnterprisePolicy" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Enterprise Policy" ], "summary": "Create a new Enterprise Policy", "description": "⚠️ **Legacy feature.** Compliance Policies (along with Templates, which apply them) are a legacy Esper product. For new device configuration work, use Blueprints instead — Compliance Policies remain available for existing Template-based deployments. See Introduction to Compliance Policies: https://help.esper.io/hc/en-us/articles/12653153592977-Introduction-to-Compliance-Policies\n\nCreates a new Compliance Policy for the enterprise.\n\nCreates a Compliance Policy record defining a set of device restrictions/permissions that can subsequently be applied to Template-provisioned devices.\n\n**About Compliance Policies**\nA Compliance Policy is a set of device-configuration permissions and restrictions — screen and unlock behavior (keyguard, safe boot), connectivity (USB, tethering, NFC), communication (SMS, outgoing/incoming calls, dialer), hardware (camera, screenshots), and system controls (factory reset, ADB, side-loading, Play Store, app uninstall, date/time configuration) — that gets applied to a device after it has already been provisioned through a Template. They're commonly used to make a post-provisioning change to a Kiosk-mode device, such as temporarily re-enabling the status bar or ADB to pull a bug report, without re-provisioning the device. Templates and Compliance Policies are legacy Esper products; Blueprints are the current, recommended way to define device configuration for new work.\n\n**Key Fields / Query Parameters**\n- `name` — Required — name of the Policy\n- `description` — Free-text description of the policy's purpose\n- `policy` — The underlying Policy Data object — the actual restriction/permission toggles (e.g., cameraDisabled, adbDisabled, phonePolicy) applied to the device\n- `is_active` — Whether the policy should be active immediately\n\n**Common Use Cases**\n- Temporarily re-enabling a restricted feature (e.g., status bar or ADB) on a Kiosk-mode device to pull a bug report\n- Defining a restriction profile for a class of legacy Template-provisioned devices\n- Making a post-provisioning configuration change without re-running the device through its Template\n\n**Best Practices**\n- Use Blueprints instead of creating a new Compliance Policy for any device not already on the legacy Template system\n- Give the policy a clear, descriptive name so it's identifiable later among other Compliance Policies\n- Test a new policy on a small device group before rolling it out broadly, since restriction changes can affect Kiosk-mode usability\n\n**Workflow**\n1. Confirm the target devices are still on the legacy Template/Compliance Policy system (not yet migrated to Blueprints)\n2. Design the restriction/permission configuration to apply\n3. POST it to this endpoint with a name and description, then apply the resulting policy uuid to the relevant devices or groups\n", "operationId": "createPolicy", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "ID of the enterprise", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "The request body to create an Enteprise Policy", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_EnterprisePolicy" } } }, "required": true }, "responses": { "201": { "description": "command request successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_EnterprisePolicy" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ], "x-codegen-request-body-name": "request" } }, "/enterprise/{enterprise_id}/policy/{policy_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Enterprise Policy" ], "summary": "Get Enterprise Policy", "description": "⚠️ **Legacy feature.** Compliance Policies (along with Templates, which apply them) are a legacy Esper product. For new device configuration work, use Blueprints instead — Compliance Policies remain available for existing Template-based deployments. See Introduction to Compliance Policies: https://help.esper.io/hc/en-us/articles/12653153592977-Introduction-to-Compliance-Policies\n\nRetrieves a single Compliance Policy by ID.\n\nReturns the full details of one Compliance Policy, including its restriction/permission configuration and the count of devices it's currently applied to.\n\n**About Compliance Policies**\nA Compliance Policy is a set of device-configuration permissions and restrictions — screen and unlock behavior (keyguard, safe boot), connectivity (USB, tethering, NFC), communication (SMS, outgoing/incoming calls, dialer), hardware (camera, screenshots), and system controls (factory reset, ADB, side-loading, Play Store, app uninstall, date/time configuration) — that gets applied to a device after it has already been provisioned through a Template. They're commonly used to make a post-provisioning change to a Kiosk-mode device, such as temporarily re-enabling the status bar or ADB to pull a bug report, without re-provisioning the device. Templates and Compliance Policies are legacy Esper products; Blueprints are the current, recommended way to define device configuration for new work.\n\n**Key Fields / Query Parameters**\n- `policy_id` — UUID of the Compliance Policy to retrieve\n- `device_count` — Number of devices this policy is currently applied to\n\n**Common Use Cases**\n- Reviewing a policy's full restriction configuration before applying it to additional legacy devices\n- Confirming device_count before changing a policy that's still widely applied to Template-provisioned devices\n- Auditing a specific policy's settings during a security review of legacy Kiosk devices\n\n**Best Practices**\n- Check device_count before editing or deleting a policy, since changes affect every device it's applied to\n- Use the list endpoint to find the policy_id if it isn't already known\n- Treat this as read-only legacy configuration data — plan a Blueprint equivalent if the device fleet is migrating\n\n**Workflow**\n1. List policies to find the policy_id of interest\n2. GET this endpoint for full detail on its restriction configuration\n3. PATCH or DELETE as needed once the impact (device_count) is understood\n", "operationId": "getPolicyById", "parameters": [ { "name": "policy_id", "in": "path", "description": "An integer identifying this enterprise policy.", "required": true, "schema": { "type": "integer" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_EnterprisePolicy" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Enterprise Policy" ], "summary": "Update Enterprise Policy", "description": "Enterprise/Compliance Policies are a legacy service and may not be generally available to all customers.\n\nFully replaces an existing Enterprise Policy (known as a Compliance Policy in the console) for the given policy_id with the values provided in the request body. Use this when you need to overwrite all policy fields at once; for updating only specific fields, use the partial-update (PATCH) variant instead.\n\nRequires a complete EnterprisePolicy object in the request body — any fields omitted are treated as unset — and returns the updated EnterprisePolicy instance.\n\n**About Enterprise Policy**\n\nAn Enterprise Policy defines the configuration and restrictions applied to devices under an enterprise. Policies are referenced by an integer policy_id scoped to the enterprise, and devices report which policy_id/policy_name they're currently associated with.\n\n**Key Fields / Query Parameters**\n\n- policy_id — integer identifier for the enterprise policy being updated\n\n**Common Use Cases**\n\n- Overwriting an entire policy's configuration in one call after building the full desired state client-side\n\n**Best Practices**\n\n- Use PATCH (partial update) instead of PUT when only a subset of policy fields needs to change, to avoid accidentally clearing fields not included in the request body\n", "operationId": "updatePolicy", "parameters": [ { "name": "policy_id", "in": "path", "description": "An integer identifying this enterprise policy.", "required": true, "schema": { "type": "integer" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_EnterprisePolicy" } } }, "required": true }, "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_EnterprisePolicy" } } } }, "400": { "description": "User update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ], "x-codegen-request-body-name": "data" }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Enterprise Policy" ], "summary": "Delete a Enterprise Policy", "description": "⚠️ **Legacy feature.** Compliance Policies (along with Templates, which apply them) are a legacy Esper product. For new device configuration work, use Blueprints instead — Compliance Policies remain available for existing Template-based deployments. See Introduction to Compliance Policies: https://help.esper.io/hc/en-us/articles/12653153592977-Introduction-to-Compliance-Policies\n\nDeletes a Compliance Policy.\n\nPermanently removes the specified Compliance Policy. All devices must be removed prior to deleting the policy. Apply a different policy to all devices prior to calling the Delete endpoint. \n\n**About Compliance Policies**\nA Compliance Policy is a set of device-configuration permissions and restrictions — screen and unlock behavior (keyguard, safe boot), connectivity (USB, tethering, NFC), communication (SMS, outgoing/incoming calls, dialer), hardware (camera, screenshots), and system controls (factory reset, ADB, side-loading, Play Store, app uninstall, date/time configuration) — that gets applied to a device after it has already been provisioned through a Template. They're commonly used to make a post-provisioning change to a Kiosk-mode device, such as temporarily re-enabling the status bar or ADB to pull a bug report, without re-provisioning the device. Templates and Compliance Policies are legacy Esper products; Blueprints are the current, recommended way to define device configuration for new work.\n\n**Key Fields / Query Parameters**\n- `policy_id` — UUID of the Compliance Policy to delete\n\n**Common Use Cases**\n- Removing an outdated or unused legacy policy during cleanup\n- Retiring a Compliance Policy after its devices have been migrated to a Blueprint\n- Correcting a policy created in error\n\n**Best Practices**\n- Remove all devices from the policy before calling delete\n\n**Workflow**\n1. GET the policy to confirm device_count and review its configuration\n2. Reassign or migrate affected devices as needed\n3. DELETE the policy once it's safe to remove\n", "operationId": "deleteEnterprisePolicy", "parameters": [ { "name": "policy_id", "in": "path", "description": "An integer identifying this enterprise policy.", "required": true, "schema": { "type": "integer" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The resource was deleted successfully." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "patch": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Enterprise Policy" ], "summary": "Partial update EnterprisePolicy", "description": "⚠️ **Legacy feature.** Compliance Policies (along with Templates, which apply them) are a legacy Esper product. For new device configuration work, use Blueprints instead — Compliance Policies remain available for existing Template-based deployments. See Introduction to Compliance Policies: https://help.esper.io/hc/en-us/articles/12653153592977-Introduction-to-Compliance-Policies\n\nPartially updates a Compliance Policy.\n\nUpdates one or more fields of the specified Compliance Policy — including its restriction/permission configuration — without requiring the full object in the request body; only included fields are changed. Does not update configurations on devices linked to the policy. Apply a new policy to update the device.\n\n**About Compliance Policies**\nA Compliance Policy is a set of device-configuration permissions and restrictions — screen and unlock behavior (keyguard, safe boot), connectivity (USB, tethering, NFC), communication (SMS, outgoing/incoming calls, dialer), hardware (camera, screenshots), and system controls (factory reset, ADB, side-loading, Play Store, app uninstall, date/time configuration) — that gets applied to a device after it has already been provisioned through a Template. They're commonly used to make a post-provisioning change to a Kiosk-mode device, such as temporarily re-enabling the status bar or ADB to pull a bug report, without re-provisioning the device. Templates and Compliance Policies are legacy Esper products; Blueprints are the current, recommended way to define device configuration for new work.\n\n**Key Fields / Query Parameters**\n- `policy_id` — UUID of the Compliance Policy to update\n- `name` — Updated policy name\n- `description` — Updated description\n- `policy` — Updated Policy Data object — the restriction/permission toggles\n- `is_active` — Updated active state\n\n**Common Use Cases**\n- Temporarily loosening a restriction (e.g., re-enabling ADB or the status bar) on Kiosk devices to pull a bug report\n- Re-tightening restrictions after a troubleshooting session is complete\n- Renaming or deactivating a legacy policy without deleting it outright\n", "operationId": "partialupdatePolicy", "parameters": [ { "name": "policy_id", "in": "path", "description": "An integer identifying this enterprise policy.", "required": true, "schema": { "type": "integer" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_EnterprisePolicyPartialUpdate" } } }, "required": true }, "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_EnterprisePolicy" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ], "x-codegen-request-body-name": "data" } }, "/v0/enterprise/{enterprise_id}/command/": { "get": { "x-badges": [ { "name": "Legacy", "color": "orange" } ], "tags": [ "esper_cloud_api_Commands V2" ], "summary": "List command requests", "description": "Alternative Available (recommended): For broader multi-OS support and enhanced command visibility, use the stable command request API: https://api.esper.io/openapi/command-request/listcommandrequests\n\nReturns a paginated list of command requests within the enterprise. Each record includes the command type, targeted devices or groups, schedule details, arguments, and current status.\n\nThis endpoint provides visibility into commands that have been issued, whether they are queued, in progress, successful, or failed.", "operationId": "listCommandRequest", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "ID of the enterprise", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "command_type", "in": "query", "description": "Filter by type of command request i.e device, group etc", "schema": { "type": "string" } }, { "name": "devices", "in": "query", "description": "Filter by device IDs. Accepts comma separated values.", "schema": { "type": "string" } }, { "name": "device_type", "in": "query", "description": "Filter by device type i.e active, inactive etc", "schema": { "type": "string" } }, { "name": "command", "in": "query", "description": "Filter by command name", "schema": { "type": "string" } }, { "name": "issued_by", "in": "query", "description": "Filter by user. Accepts user id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "on successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "format": "int64" }, "next": { "type": "string", "format": "url" }, "previous": { "type": "string", "format": "url" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_V0CommandRequest" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "post": { "x-badges": [ { "name": "Legacy", "color": "orange" } ], "tags": [ "esper_cloud_api_Commands V2" ], "summary": "Create a command request", "description": "⚠️ Android only. This endpoint issues commands to Android-managed devices.\n\nAlternative Available\n\nA newer, multi-OS commands API is available and recommended for most use cases\nhttps://api.esper.io/openapi/command-request/createcommandrequest\n\nCreates a command request targeting one or more devices or groups, dispatching a managed operation such as an install, reboot, lock, or configuration change. Accepts a V0CommandRequest body specifying the target scope (DEVICE, GROUP, or DYNAMIC), the command type, any required arguments, and an optional schedule. Returns the created command request including its id (request_id), which is used to poll for per-device execution status. Alternative endpoint- https://{foo}-api.esper.cloud/api/commands/v0/commands/\n\nAbout Create Command Request\n\nEsper's command system dispatches operations to enrolled Android devices asynchronously. A command request defines what to do (command), who to do it to (devices or groups), any parameters the command requires (command_args), and when to do it (schedule and schedule_args). The command_type field determines targeting scope: DEVICE targets up to 1,000 specific devices, GROUP targets up to 500 groups, and DYNAMIC targets a custom cross-group subset. After creation, use the request_id to query per-device execution status at the status endpoint.\n\nKey Fields\n\ncommand_type — targeting scope: DEVICE, GROUP, or DYNAMIC\n\ndevices — list of device UUIDs to target (up to 1,000); used with command_type: DEVICE\n\ngroups — list of group UUIDs to target (up to 500); used with command_type: GROUP\n\ncommand — the operation to perform (e.g. INSTALL, REBOOT, LOCK; see V0DeviceCommandEnum for the full list)\n\n\ncommand_args — command-specific parameters (e.g. app_version UUID for INSTALL, package_name for CLEAR_APP_DATA)\n\nschedule — scheduling mode (immediate or deferred)\n\nschedule_args — scheduling parameters when using deferred execution\n\nSee https://help.esper.io/hc/en-us/articles/29710806069393-Creating-API-Commands for command examples.", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "ID of the enterprise", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "The request body to create a command for set of devices or groups", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_V0CommandRequest" } } }, "required": true }, "responses": { "201": { "description": "command request successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_V0CommandRequest" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ], "x-codegen-request-body-name": "request" } }, "/v0/enterprise/{enterprise_id}/command/{request_id}/status/": { "get": { "x-badges": [ { "name": "Legacy", "color": "orange" } ], "tags": [ "esper_cloud_api_Commands V2" ], "summary": "get status list for command request", "description": "⚠️ Android only. This endpoint applies to command requests issued to Android-managed devices.\n\nAlternative Available\n\nA newer, multi-OS commands API is available and recommended for most use cases https://api.esper.io/openapi/command-request/listcommandrequests\n\nReturns the per-device execution status for a specific command request, with optional filtering by device or command state.\nReturns a paginated list of V0CommandStatus1 records — one per targeted device — each showing the device reference, current execution state, reason, and timestamps. Use this to monitor command propagation after creating a request via POST .../command/.\n\nAbout Get Command Request Status\n\nWhen a command request is created, Esper generates a per-device status record for each target in the request. This endpoint surfaces those records, allowing integrators to track whether each device has queued, acknowledged, completed, failed, timed out, or been cancelled. The state field reflects the full command lifecycle from Command Queued through Command Success or Command Failure. The reason field provides detail on why a command reached its current state — useful for diagnosing failures.\n\nKey Fields / Query Parameters\n\nrequest_id — path parameter; UUID of the command request whose status to retrieve.\n\ndevice — optional query filter; narrows results to a single device UUID.\n\nstate — optional query filter; narrows results to a specific execution state (e.g. Command Failure, Command Success).\n\nstate values: Command Queued, Command Initiated, Command Acknowledged, Command In Progress, Command TimeOut, Command Success\n, Command Failure, Command Scheduled, Command Cancelled.\n\nreason — plain-language explanation of why the command is in its current state.\n\n**Common Use Cases**\n\nMonitor rollout progress for a group-scoped install command by checking how many devices have reached Command Success.\nIdentify devices that failed or timed out by filtering on state=Command Failure or state=Command TimeOut. Note: timeout status will continue to success or failure.\nConfirm that a specific device received and acknowledged a command before proceeding with a dependent operation.\n\n**Best Practices**\n\nPoll this endpoint periodically after creating a command request rather than expecting immediate completion — devices may be offline or slow to respond\nFilter by state=Command Failure first to quickly surface problem devices before reviewing overall progress\nStore request_id from the create response immediately — it cannot be recovered from the status endpoint itself\n\n**Workflow**\n\nAfter creating a command request, capture the request_id from the POST response.\nCall this endpoint with the request_id to retrieve per-device status records.\nFilter by state to isolate devices in specific execution states; retry or investigate failures as needed.", "operationId": "getCommandRequestStatus", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "ID of the enterprise", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "request_id", "in": "path", "description": "ID for the command request", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "device", "in": "query", "description": "Filter status result by device id.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "Filter by command state", "schema": { "type": "string" } } ], "responses": { "200": { "description": "on successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "format": "int64" }, "next": { "type": "string", "format": "url" }, "previous": { "type": "string", "format": "url" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_V0CommandStatus1" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v0/enterprise/{enterprise_id}/content/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Content" ], "summary": "List content", "description": "Returns a paginated list of all files uploaded to the enterprise's Content Management library. Each result includes file metadata such as MIME type, size, tags, description, path, and ownership — but not the file content itself. Use this endpoint to discover content IDs for use in downstream operations such as pushing files to devices.\n\n**Query parameters:**\n\nsearch (optional) — Filter results by tags or description; does not search by filename\n\nlimit (optional, default: 20) — Number of results to return per page\n\noffset (optional, default: 0) — Index from which to start returning results\n\n**Response fields of note** (Content schema):\n\nkey — The filename or identifier for the content\n\nkind — MIME type of the file (e.g., application/pdf, image/png)\n\nsize — File size in bytes\n\ntags — Array of tag strings; searchable via the search parameter\n\ndescription — Optional description for the file; also searchable via search\n\npath — Path to the content within the library\n\nis_dir — Whether the entry represents a directory rather than a file\n\nowner — User who uploaded the content\n\n**Common Use Cases**\n\nDiscovering content IDs needed to reference files in device push operations\n\nAuditing the enterprise content library for stale, duplicate, or untagged files\n\nBuilding content browsing or selection UIs in custom management tools\n\nVerifying a file exists and retrieving its metadata before issuing a push command\n\n**Best Practices**\n\nUse the search parameter to filter by tags or description rather than fetching all content and filtering client-side — note that search does not match on filename (key)\n\nUse descriptive tags at upload time to make content discoverable via this endpoint's search\n\nPaginate with limit and offset for enterprises with large content libraries", "operationId": "getAllContent", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Search by tags, description", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_Content" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v0/enterprise/{enterprise_id}/content/{content_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Content" ], "summary": "Get content information", "description": "Returns metadata for a single content item in the enterprise's Content Management library, identified by its content_id. The response includes the same fields as the list endpoint — filename, MIME type, size, tags, description, path, and ownership — but scoped to a single file. Does not return the file's binary content.\n\n**Common Use Cases**\n\nVerifying a specific file's metadata (type, size, tags, path) before referencing it in a device push operation\nConfirming a file exists and retrieving its details after upload\nChecking ownership or modification timestamps for auditing purposes\n\n**Best Practices**\n\nUse GET /v0/enterprise/{enterprise_id}/content/ with the search parameter to find a content_id if you don't already have it — this endpoint requires knowing the ID in advance\nThis endpoint returns metadata only", "operationId": "getContent", "parameters": [ { "name": "content_id", "in": "path", "description": "A UUID string identifying a content instance.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Content" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Content" ], "summary": "Delete Content", "description": "Permanently deletes a content item from the enterprise's Content Management library by content_id. This action is irreversible — the file and its metadata are removed immediately and cannot be recovered.\n\n**Common Use Cases**\n\nRemoving outdated or superseded files from the content library\nCleaning up test or temporary files uploaded during development\nMaintaining a tidy library by removing content that is no longer referenced in any active device operations\n\n**Best Practices**\n\nConfirm the correct content_id using GET /v0/enterprise/{enterprise_id}/content/{content_id}/ before deleting — this action cannot be undone\nVerify the file is not actively referenced in any pending or scheduled device push operations before deleting to avoid broken references\nUse GET /v0/enterprise/{enterprise_id}/content/ to audit the library and identify candidates for deletion", "operationId": "deleteContent", "parameters": [ { "name": "content_id", "in": "path", "description": "A UUID string identifying a content instance.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The resource was deleted successfully." }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "patch": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Content" ], "summary": "Patch a content instance", "description": "Partially updates the metadata of an existing content item in the enterprise's Content Management library. Only tags and description can be updated — the file itself and its core properties (filename, size, MIME type, path) cannot be modified through this endpoint.\n\nRequest body fields (all optional)\n\nReplaces the existing tag array with the new set of tag strings provided\nUpdates the human-readable description for the content item\n\n**Common Use Cases**\n\nAdding or correcting tags to improve discoverability via the search parameter on GET /v0/enterprise/{enterprise_id}/content/\nUpdating a description to reflect a file's current purpose after it has changed\nRetroactively tagging content that was uploaded without tags\n\n**Best Practices**\n\nTags is a full replacement, not an append — if you want to add a tag while preserving existing ones, retrieve the current tags first via GET /v0/enterprise/{enterprise_id}/content/{content_id}/ and include them all in the patch body\nThis endpoint cannot be used to replace or rename the file itself — upload a new file via POST /v0/enterprise/{enterprise_id}/content/upload/ and delete the old one if the file content needs to change\nApply consistent, descriptive tags across your library to make content searchable and auditable", "operationId": "patchContent", "parameters": [ { "name": "content_id", "in": "path", "description": "A UUID string identifying a content instance.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "*/*": { "schema": { "type": "object", "properties": { "tags": { "title": "Tags", "type": "array", "description": "Tags for the content", "items": { "maxLength": 255, "type": "string" } }, "description": { "title": "Description", "type": "string", "description": "Description of the content" } } } } }, "required": false }, "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Content" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "415": { "description": "Unsupported media type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ], "x-codegen-request-body-name": "data" } }, "/v0/enterprise/{enterprise_id}/content/upload/": { "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Content" ], "summary": "Upload new content", "description": "Uploads a file to the enterprise content library, creating a new Content record.\nAccepts a multipart/form-data payload with the binary file in the key field and returns the resulting Content object including id, download_url, MIME type, hash, and size. This is the primary mechanism for adding files to Esper's content library for device distribution.\n\nAbout Upload Content\n\nThe content upload endpoint stores an arbitrary file in Esper's enterprise content library, which acts as a managed file repository for pushing files to enrolled devices. This is not intended for application uploads. Use the app upload endpoint instead. On successful upload, Esper returns a Content record with a download_url, a computed hash for integrity verification, and a detected kind (MIME type). The returned id is used to reference the content in distribution commands and PATCH operations. Unlike the APK upload endpoint, content upload accepts any supported file type — configuration files, scripts, media, documents, and more.\n\nKey Fields\n\nkey — required; the binary file to upload, sent as multipart/form-data\n\nid — returned in the response; integer identifier for this content record used in downstream operations\n\ndownload_url — direct URL to retrieve the uploaded file\n\nhash — SHA hash of the uploaded file for integrity verification\n\nkind — MIME type detected from the uploaded file\n\ntags / description — not set at upload; add via PATCH .../content/{content_id}/ after upload\n\n**Common Use Cases**\n\nUpload configuration files, scripts, or reference documents to the content library for device distribution.\nAdd media or resource files that devices need to download as part of a provisioning **Workflow**.\nAutomate content updates as part of a CI/CD or content management pipeline.\n\n**Best Practices**\n\nTags and descriptions cannot be set at upload time — immediately follow a successful upload with PATCH .../content/{content_id}/ to add tags and a description, which are needed for the search parameter on the list endpoint to find this file later.\nStore the id from the response; it is an integer (not a UUID) and is the reference for all downstream content operations.\nVerify the returned hash against your local file hash to confirm upload integrity.\n\n**Workflow**\n\nPOST the file binary as key in a multipart/form-data request.\nCapture the id, download_url, and hash from the response.\nImmediately PATCH the new content record to add tags and description for searchability.", "operationId": "postContent", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "key" ], "properties": { "key": { "type": "string", "description": "Valid file to upload", "format": "binary" } } } } }, "required": true }, "responses": { "200": { "description": "Successful Operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Content" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "415": { "description": "Unsupported media type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v0/enterprise/{enterprise_id}/content/remote-file/": { "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Content" ], "summary": "Upload file to Remote File Manager", "description": "Uploads a file to the Remote File Manager bucket for temporary storage.\n\nAccepts a multipart file upload up to 50MB and returns a file_key, bucket name, size, content type, and a pre-signed download_url. Files uploaded here are automatically deleted after 1 day, so this is intended for short-lived transfers rather than long-term content storage.\n\n**About Upload File to Remote File Manager**\n\nThe Remote File Manager bucket is a temporary staging area distinct from Esper's main Content management system. Because files here are auto-deleted after 1440 minutes (1 day), it's best suited for short-lived use cases such as generating a one-time download link or briefly staging a file for another workflow, rather than for files devices need to reference long-term.\n\n**Key Fields / Request Body**\n\nfile — the file to upload, required, maximum 50MB\n\nfilename — an optional custom filename; defaults to the uploaded file's name\n\ncontent_type — an optional MIME type override, auto-detected if omitted\n\n**Common Use Cases**\n\nGenerating a short-lived, shareable download link for a file\n\nStaging a file temporarily for a downstream automation step\n\n**Best Practices**\n\nDo not rely on this endpoint for files that need to persist beyond 1 day; use the Content API for anything longer-lived\n\nCapture the file_key immediately, since it is required to generate additional download URLs later\n\n**Workflow**\n\nPOST the file as multipart form data to this endpoint\n\nCapture the returned file_key and download_url\n\nUse the generate_download_url endpoint with the file_key if you need a new pre-signed URL after the original expires\n", "operationId": "uploadRemoteFile", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "properties": { "file": { "type": "string", "description": "The file to upload (max 50MB)", "format": "binary" }, "filename": { "type": "string", "description": "Custom filename (optional, defaults to uploaded file name)" }, "content_type": { "type": "string", "description": "MIME type of the file (optional, auto-detected)" } } } } }, "required": true }, "responses": { "201": { "description": "File uploaded successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "file_key": { "type": "string", "description": "Unique storage key for the file", "example": "123/files/document_abc123.pdf" }, "bucket": { "type": "string", "description": "Storage bucket name", "example": "REMOTE_FILE_MANAGER" }, "file_size": { "type": "integer", "description": "Size of uploaded file in bytes", "example": 1048576 }, "content_type": { "type": "string", "description": "Detected/validated MIME type", "example": "application/pdf" }, "auto_delete_after_minutes": { "type": "integer", "description": "When file will be auto-deleted", "example": 1440 }, "download_url": { "type": "string", "description": "Pre-signed URL for downloading the file", "example": "https://s3.amazonaws.com/REMOTE_FILE_MANAGER/123/files/document_abc123.pdf?AWSAccessKeyId=..." }, "download_expires_in": { "type": "integer", "description": "Download URL expiration time in seconds", "example": 3600 } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No file provided" } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "413": { "description": "File too large (max 50MB)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "File size exceeds maximum allowed size of 52428800 bytes" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Failed to upload file" } } } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v0/enterprise/{enterprise_id}/content/remote-file/generate_download_url/": { "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Content" ], "summary": "Generate download URL for existing file", "description": "Generates a new pre-signed download URL for a file already stored in the Remote File Manager bucket.\n\nUse this when the original download_url returned at upload time has expired but the file itself (auto-deleted after 1 day from upload) is still available. Accepts an optional expires_in value to control how long the new URL remains valid.\n\n**About Generate Download URL**\nThe download_url returned when a file is uploaded expires after a set duration; this endpoint issues a fresh pre-signed URL against the same file_key without re-uploading the file. It only works while the underlying file still exists in the bucket, which is limited to roughly 1 day after upload.\n\n**Key Fields / Request Body**\n\nfile_key — the storage key of the file, required, returned from the original upload\n\nexpires_in — how long the new URL should remain valid, in seconds; defaults to 3600, minimum 60, maximum 86400\n\n**Common Use Cases**\n\nRe-generating a download link after the original one expired but before the file's 1-day auto-delete window closes\n\nIssuing a longer- or shorter-lived download URL than the one originally returned at upload time\n\n**Best Practices**\n\nTrack each file's upload time so you don't attempt to generate a URL for a file that has already been auto-deleted\n\nSet expires_in to match how long the downstream consumer actually needs access, rather than defaulting to the maximum\n\n**Workflow**\n\nRetrieve the file_key from the original upload response\n\nPOST the file_key and desired expires_in to this endpoint\n\nShare the returned download_url before it expires\n", "operationId": "generateDownloadUrl", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "file_key" ], "properties": { "file_key": { "type": "string", "description": "The storage key of the file to download", "example": "123/files/document_abc123.pdf" }, "expires_in": { "type": "integer", "description": "URL expiration time in seconds (optional, default 3600)", "default": 3600, "minimum": 60, "maximum": 86400 } } } } }, "required": true }, "responses": { "200": { "description": "Download URL generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "file_key": { "type": "string", "description": "The storage key of the file", "example": "123/files/document_abc123.pdf" }, "download_url": { "type": "string", "description": "Pre-signed URL for downloading the file", "example": "https://s3.amazonaws.com/REMOTE_FILE_MANAGER/123/files/document_abc123.pdf?AWSAccessKeyId=..." }, "expires_in": { "type": "integer", "description": "URL expiration time in seconds", "example": 3600 } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "file_key is required" } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Failed to generate download URL" } } } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v1/enterprise/{enterprise_id}/alertchannels/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Alerts" ], "summary": "List alert channels in enterprise", "description": "\n⚠️ Android only. \n\nReturns a paginated list of all alert channels configured in the enterprise. Alert channels define the destinations where alert notifications are sent when alarm rules are triggered — currently supporting email as the delivery type. Use this endpoint to discover channel IDs for associating with alarm rules, or to audit existing notification destinations.\n\n**Common use cases**\n\nRetrieving channel IDs to associate with new or existing alarm rules\n\nAuditing notification destinations across the enterprise\n\nVerifying which alarm rules are linked to a given channel before updating or deleting it\n\n**Best practices**\n\nCheck linked_alerts in the response before deleting a channel — removing a channel that is actively linked to alarm rules will affect those rules' notification delivery\n\nUse the name filter to quickly locate a specific channel without paginating through all results\n\nNote that id is an integer, not a UUID — use it as-is in subsequent calls to GET, PUT, PATCH, or DELETE on /alertchannels/{alert_id}\n", "operationId": "listAlertChannels", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "Filter alert channels by name.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "description": "Return results from this index.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_AlertChannelsV1" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Alerts" ], "summary": "Creates alert channel", "description": "Creates a new alert channel in the enterprise, defining a notification destination to be used when alarm rules are triggered. Alert channels are prerequisites for alarm rules — a channel must exist before it can be linked to any rule. Currently, email is the supported delivery type.\n\n**Workflow**\n\nCreate an alert channel using this endpoint → receive a channel id in the response\n\nUse that id when creating or updating an alarm rule via POST /v1/enterprise/{enterprise_id}/alarmrules/ to link the channel as a notification destination\n\n**Common use cases**\n\nSetting up a new email destination for device or fleet alert notifications\n\nCreating dedicated channels for different teams (e.g., a channel for ops, another for IT support) so alarm rules can target the appropriate recipients\n\nProgrammatically provisioning notification infrastructure as part of an enterprise onboarding workflow\n\n**Best practices**\n\nUse a descriptive name that makes the channel's purpose and recipient clear (e.g., \"IT Ops - Device Offline Alerts\") — this is how channels are identified in the Console and when auditing via GET /alertchannels/\n\nStore the integer id from the 201 response — it is required for all subsequent operations on this channel and for linking it to alarm rules\n\nA channel can be linked to multiple alarm rules; create shared channels for common recipients rather than duplicating channels per rule\n", "operationId": "createAlertChannel", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_UpdateAlertChannelsV1" } } }, "required": true }, "responses": { "201": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_AlertChannelsV1" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v1/enterprise/{enterprise_id}/alertchannels/{alert_id}": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Alerts" ], "summary": "Get alert channel", "description": "⚠️ Android only. \n\nReturns the details of a single alert channel identified by its alert_id. Use this endpoint to retrieve the current configuration of a specific channel — including its delivery type, destination address, and any alarm rules it is linked to — before updating or deleting it.\n\nNote that alert_id is an integer, not a UUID. Use GET /v1/enterprise/{enterprise_id}/alertchannels/ to look up an alert_id if it is not already known.\n\n**Response fields of note**\n\nid — Integer identifier for the channel\n\nname — Display name for the channel\n\ntype — Delivery format (e.g., email)\n\nproperties.to_address — The email address notifications are sent to\n\nlinked_alerts — Array of alarm rules currently using this channel\n\ncreated_on / updated_on — Timestamps for auditing purposes\n\n**Common use cases**\n\nRetrieving a channel's current configuration before issuing an update\n\nChecking linked_alerts to understand which alarm rules depend on this channel before modifying or deleting it\n\nConfirming a channel was created correctly after a POST /alertchannels/ call\n\n**Best practices**\n\nAlways retrieve the current state of a channel before updating it to avoid overwriting fields unintentionally\n\nReview linked_alerts before deletion — channels actively linked to alarm rules should be unlinked or replaced first to avoid disrupting alert delivery\n\nIf the alert_id is not known, use GET /alertchannels/ with the name filter to locate it\n", "operationId": "getAlertChannel", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "alert_id", "in": "path", "description": "An integer identifying the alert channel.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_AlertChannelsV1" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Alerts" ], "summary": "Update alert channel information", "description": "Fully updates an existing alert channel identified by its integer alert_id. All writable fields should be included in the request body — this is a full replacement operation, not a partial update. To change only one field without affecting others, use PATCH /v1/enterprise/{enterprise_id}/alertchannels/{alert_id} instead.\n\nRequest body fields\n\nname — Display name for the channel\n\ntype — Delivery format (e.g., email)\n\nproperties.to_address — The email address notifications are sent to\n\n**Common use cases**\n\nUpdating the destination email address for a channel (e.g., when a team's distribution list changes)\n\nRenaming a channel to better reflect its current purpose or recipients\n\nCorrecting a misconfigured channel after creation\n\n**Best practices**\n\nRetrieve the current channel state with GET /v1/enterprise/{enterprise_id}/alertchannels/{alert_id} before updating — since this is a full replacement, omitting fields may clear them unintentionally\n\nPrefer PATCH over PUT when only a single field needs to change, to reduce the risk of accidental data loss\n\nNote that alert_id is an integer, not a UUID — use GET /alertchannels/ to look it up if needed\n\nUpdating the destination address on a channel affects all alarm rules linked to it immediately — review linked_alerts on the channel before making changes that will affect notification routing\n", "operationId": "updateAlertChannel", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying the enterprise.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "alert_id", "in": "path", "description": "An integer identifying the alert channel.", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_UpdateAlertChannelsV1" } } }, "required": true }, "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_AlertChannelsV1" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "patch": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Alerts" ], "summary": "Partially updates alert channel information", "description": "Partially updates one or more fields of an existing alert channel identified by its integer alert_id. Only the fields included in the request body are modified — omitted fields retain their current values. Use this endpoint instead of PUT when making a targeted change to a single field without needing to resend the full channel object.\n\n**Request body fields (all optional)**\n\nname — Display name for the channel\n\ntype — Delivery format (e.g., email)\n\nproperties.to_address — The email address notifications are sent to\n\n**Common use cases**\n\nUpdating only the destination email address without affecting the channel name or type\n\nRenaming a channel without modifying its delivery configuration\n\nMaking a quick correction to a single field after creation\n\n**Best practices**\n\nPrefer this endpoint over PUT for single-field changes — it reduces payload size and eliminates the risk of accidentally clearing fields that are not included in the body\n\nNote that alert_id is an integer, not a UUID — use GET /alertchannels/ with the name filter to look it up if needed\n\nChanges to properties.to_address take effect immediately and affect all alarm rules currently linked to this channel — review linked_alerts via GET /alertchannels/{alert_id} before updating the destination if multiple rules depend on it\n", "operationId": "patchAlertChannel", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying the enterprise.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "alert_id", "in": "path", "description": "An integer identifying the alert channel.", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_UpdateAlertChannelsV1" } } } }, "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_AlertChannelsV1" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Alerts" ], "summary": "Delete an alert channel", "description": "\n⚠️ Android only. \n\nPermanently deletes an alert channel identified by its integer alert_id. This action is irreversible. Any alarm rules that were linked to this channel will lose their association with it — verify the channel's linked_alerts before deleting to avoid silently disrupting alert delivery for active alarm rules.\n\n**Common use cases**\n\nRemoving a channel whose destination email address is no longer valid or monitored\n\nCleaning up duplicate or test channels created during setup\n\nDecommissioning a channel as part of a notification infrastructure reorganization\n\n**Best practices**\n\nCheck linked_alerts by calling GET /v1/enterprise/{enterprise_id}/alertchannels/{alert_id} before deleting — if the channel is actively linked to alarm rules, update or delete those rules first, or reassign them to a different channel, to avoid broken alert delivery\n\nConfirm the correct alert_id before issuing the delete — this action cannot be undone and alert_id is an integer, not a UUID\n\nUse GET /v1/enterprise/{enterprise_id}/alertchannels/ with the name filter to locate the correct channel if the alert_id is not already known\n", "operationId": "deleteAlertChannel", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying the enterprise.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "alert_id", "in": "path", "description": "An integer identifying the alert channel.", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "The resource was deleted successfully." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v1/enterprise/{enterprise_id}/alarmrules/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Alarms" ], "summary": "Get list of alarm rules", "description": "\n⚠️ Android only. \n\nReturns a paginated list of all alarm rules configured in the enterprise. Alarm rules define the conditions under which device or fleet alerts are triggered — specifying which metric to monitor, the threshold conditions, which devices or groups are in scope, and which alert channels receive notifications when the rule fires.\n\n**Key Query parameters**\n\nname (optional) — Filter rules by name\n\ndescription (optional) — Filter rules by description\n\nis_active (optional) — Filter by active (true) or inactive (false) rules\n\n\n**Response fields of note**\n\nid — UUID identifying the alarm rule; used in all subsequent rule operations\n\nname / description — Display name and description for the rule\n\nmetric — The device metric being monitored (e.g., battery level, connectivity)\n\nconditions — Threshold definition including value, unit, comparator, and toggle_state\n\ndevices / groups — The specific devices or device groups the rule applies to\n\nalert_channels — Array of alert channel IDs that receive notifications when the rule fires\n\naction_emails — Direct email recipients for notifications, independent of alert channels\n\nis_active — Whether the rule is currently enabled\n\nrealert_interval — Interval in minutes before the rule re-alerts if the condition persists\n\nrepeat_times — Number of times the alert will repeat\n\ntrigger_count / daily_trigger_count — Cumulative and daily counts of how many times the rule has fired\n\n**Common use cases**\n\nAuditing all active alarm rules across the enterprise to review monitoring coverage\n\nRetrieving rule IDs for use in get, update, patch, or delete operations\n\nFiltering for inactive rules to identify stale or disabled monitoring configurations\n\nReviewing trigger counts to assess alert frequency and rule health\n\n**Best practices**\n\nUse is_active=true to scope results to currently enabled rules when auditing live monitoring configuration\n\nUse created_on_gt / created_on_lt to scope results to a specific time window when reviewing recently added or historical rules\n\nNote that alarm_id used in single-rule operations is a UUID, unlike the integer alert_id used by alert channels\n", "operationId": "getAlarmRules", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "Filter alarm rules by name.", "schema": { "type": "string" } }, { "name": "description", "in": "query", "description": "Filter alarm rules by description.", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "description": "Filter active alarm rules.", "schema": { "type": "boolean" } }, { "name": "created_on_gt", "in": "query", "description": "Filter alarm rules created after a given timestamp.", "schema": { "type": "string" } }, { "name": "created_on_lt", "in": "query", "description": "Filter alarm rules created before a given timestamp.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "description": "Return results from this index.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_AlarmRule" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Alarms" ], "summary": "Creates instance of alarm rules", "description": "⚠️ Android only. \n\nCreates a new alarm rule in the enterprise, defining the conditions under which a device metric alert is triggered and where notifications are sent. Alarm rules combine a monitored metric, a threshold condition, a set of target devices or groups, and one or more notification destinations into a single automated monitoring configuration.\n\nAn alert channel must already exist before it can be referenced in a new alarm rule. Create channels first via POST /v1/enterprise/{enterprise_id}/alertchannels/ if needed.\n\n**Request body fields**\n\nRequired\n\nenterprise — UUID of the enterprise\n\nname — Display name for the rule\n\nmetric — The device metric to monitor (e.g., battery level, connectivity status)\n\nconditions — Threshold definition object containing\n\nvalue — Numeric threshold value\n\nunit — Unit of measurement for the threshold\n\ncomparator — Comparison operator (e.g., less than, greater than, equals)\n\ntoggle_state — Boolean for toggle-based metrics (e.g., connectivity on/off)\n\n\nrealert_interval — Interval in minutes before re-alerting if the condition continues to be met\n\nOptional\n\ndescription — Human-readable description of the rule's purpose\n\ndevices — Array of specific device IDs to monitor; omit to target groups instead\n\ngroups — Array of device group IDs to monitor\n\nalert_channels — Array of alert channel IDs (UUIDs) to notify when the rule fires\n\naction_emails — Array of email addresses to notify directly, independent of alert channels\n\nactions — Array of actions to perform when the rule fires\n\nis_active — Whether the rule is active immediately on creation (defaults to active if omitted)\n\nrepeat_times — Number of times to repeat the alert\n\n**Workflow**\n\nCreate alert channels via POST /alertchannels/ if they don't already exist\n\nCreate the alarm rule using this endpoint, referencing the channel IDs in alert_channels\n\nStore the UUID id from the 201 response for future get, update, or delete operations\n\nMonitor firing activity via GET /alarmrules/{alarm_id}/alarmhistory/\n\n**Common use cases**\n\nSetting up automated alerts for low battery thresholds across a device group\n\nMonitoring connectivity status for devices in a specific location or fleet segment\n\nConfiguring re-alert intervals for persistent conditions that require ongoing attention\n\n**Best practices**\n\nTarget groups rather than individual devices where possible — group-scoped rules automatically apply to new devices added to the group\n\nSupply both alert_channels and action_emails if notifications need to reach both a shared channel and specific individuals\n\nSet a sensible realert_interval to avoid alert fatigue — too short an interval on frequently triggered conditions can flood notification recipients\n\nUse a descriptive name and description so the rule's purpose is clear when auditing via GET /alarmrules/\n", "operationId": "addAlarmRule", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_UpdateAlarmRule" } } }, "required": true }, "responses": { "201": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_AlarmRule" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v1/enterprise/{enterprise_id}/alarmrules/{alarm_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Alarms" ], "summary": "Get instance of alarm rule", "description": "⚠️ Android only. \n\nReturns the full details of a single alarm rule identified by its UUID alarm_id, including the monitored metric, threshold conditions, target devices or groups, linked alert channels, notification settings, and cumulative trigger counts. Use this endpoint to inspect a rule's current configuration before updating it, or to check trigger activity for a specific rule.\n\n**Response fields of note**\n\nid — UUID identifying the alarm rule\n\nname / description — Display name and description\n\nmetric — The device metric being monitored\n\nconditions — Threshold definition including value, unit, comparator, and toggle_state\n\ndevices / groups — The specific devices or groups the rule applies to\n\nalert_channels — Alert channel IDs receiving notifications when the rule fires\n\naction_emails — Direct email recipients independent of alert channels\n\nis_active — Whether the rule is currently enabled\n\nrealert_interval — Minutes before re-alerting if the condition persists\n\nrepeat_times — Number of times the alert repeats\n\ntrigger_count / daily_trigger_count — Cumulative and daily counts of how many times the rule has fired\n\n**Common use cases**\n\nRetrieving a rule's current configuration before issuing an update or patch\n\nInspecting trigger_count and daily_trigger_count to assess how frequently the rule is firing\n\nConfirming a rule was created correctly after a POST /alarmrules/ call\n\nChecking which devices, groups, and alert channels are currently associated with a rule\n\n**Best practices**\n\nAlways retrieve the current state of a rule before updating it to avoid overwriting fields unintentionally when using PUT\n\nUse GET /alarmrules/ with the name filter to locate an alarm_id if it is not already known — note that alarm_id is a UUID, unlike the integer alert_id used by alert channels\n\nFor a history of when and on which devices the rule has fired, use GET /alarmrules/{alarm_id}/alarmhistory/ rather than relying solely on trigger_count\n", "operationId": "getAlarmRule", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "alarm_id", "in": "path", "description": "A UUID string identifying the alarm ruleset.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_AlarmRule" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Alarms" ], "summary": "Update alarm rules", "description": "⚠️ Android only. \n\nFully updates an existing alarm rule identified by its UUID alarm_id. This is a full replacement operation — all required fields must be included in the request body and any optional fields not included may be cleared. To change only one or two fields without resending the full rule object, use PATCH /v1/enterprise/{enterprise_id}/alarmrules/{alarm_id}/ instead.\n\n**Request body fields (UpdateAlarmRule)**\n\nRequired\n\nenterprise — UUID of the enterprise\n\nname — Display name for the rule\n\nmetric — The device metric to monitor\n\nconditions — Threshold definition object containing value, unit, comparator, and toggle_state\n\nrealert_interval — Interval in minutes before re-alerting if the condition persists\n\nOptional\n\ndescription — Human-readable description of the rule's purpose\n\ndevices — Array of specific device UUIDs to monitor\n\ngroups — Array of device group UUIDs to monitor\n\nalert_channels — Array of alert channel UUIDs to notify when the rule fires\n\naction_emails — Array of email addresses to notify directly\n\nactions — Array of actions to perform when the rule fires\n\nis_active — Whether the rule is enabled\n\nrepeat_times — Number of times to repeat the alert\n\n**Common use cases**\n\nUpdating the target devices or groups after a fleet restructure\n\nChanging the threshold condition or metric as monitoring requirements evolve\n\nAdding or swapping alert channels when notification routing changes\n\nEnabling or disabling a rule by toggling is_active\n\n**Best practices**\n\nAlways retrieve the current rule state with GET /v1/enterprise/{enterprise_id}/alarmrules/{alarm_id}/ before updating — this is a full replacement and omitting optional fields that were previously set may clear them unintentionally\n\nPrefer PATCH over PUT for single-field changes to reduce payload size and risk of accidental data loss\n\nNote that alarm_id is a UUID, unlike the integer alert_id used by alert channels — use GET /alarmrules/ to look it up if needed\n\nUpdating alert_channels replaces the existing channel associations entirely — include all desired channel IDs in the updated body, not just the new ones\n", "operationId": "updateAlarmRule", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "alarm_id", "in": "path", "description": "A UUID string identifying the alarm ruleset.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_UpdateAlarmRule" } } }, "required": true }, "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_AlarmRule" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "patch": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Alarms" ], "summary": "Partially updates alarm rules", "description": "⚠️ Android only. \n\nPartially updates one or more fields of an existing alarm rule identified by its UUID alarm_id. Only the fields included in the request body are modified — omitted fields retain their current values. Use this endpoint instead of PUT when making a targeted change to a single field without needing to resend the full rule object.\n\n**Request body fields (all optional for PATCH)**\n\nenterprise — UUID of the enterprise\n\nname — Display name for the rule\n\nmetric — The device metric to monitor\n\nconditions — Threshold definition object containing value, unit, comparator, and toggle_state\n\nrealert_interval — Interval in minutes before re-alerting if the condition persists\n\ndescription — Human-readable description of the rule's purpose\n\ndevices — Array of specific device UUIDs to monitor\n\ngroups — Array of device group UUIDs to monitor\n\nalert_channels — Array of alert channel UUIDs to notify when the rule fires\n\naction_emails — Array of email addresses to notify directly\n\nactions — Array of actions to perform when the rule fires\n\nis_active — Whether the rule is enabled\n\nrepeat_times — Number of times to repeat the alert\n\n**Common use cases**\n\nToggling is_active to quickly enable or disable a rule without touching any other configuration\n\nUpdating realert_interval to tune alert frequency without modifying threshold conditions\n\nAdding or replacing alert_channels or action_emails when notification routing changes\n\nAdjusting conditions thresholds as device fleet behavior or monitoring standards evolve\n\n**Best practices**\n\nPrefer this endpoint over PUT for targeted changes — it reduces payload size and eliminates the risk of accidentally clearing fields that are not included in the body\n\nNote that array fields such as alert_channels, devices, and groups are fully replaced when included — if adding to an existing array, retrieve the current values first via GET /alarmrules/{alarm_id}/ and include them all in the patch body\n\nalarm_id is a UUID, not an integer — use GET /alarmrules/ with the name filter to look it up if needed.\n", "operationId": "patchAlarmRule", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "alarm_id", "in": "path", "description": "A UUID string identifying the alarm ruleset.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_UpdateAlarmRule" } } } }, "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_AlarmRule" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Alarms" ], "summary": "Deletes alarm rule", "description": "⚠️ Android only. \n\nPermanently deletes an alarm rule identified by its UUID alarm_id. This action is irreversible — the rule, its configuration, and its association with any alert channels are removed immediately. Historical firing data for the rule is also no longer accessible after deletion.\n\n**Common use cases**\n\nRemoving alarm rules that are no longer relevant after a fleet restructure or deployment phase ends\n\nCleaning up duplicate or misconfigured rules created during setup\n\nDecommissioning monitoring configurations for device groups that have been dissolved\n\n**Best practices**\n\nRetrieve the rule with GET /v1/enterprise/{enterprise_id}/alarmrules/{alarm_id}/ before deleting to confirm it is the correct rule — this action cannot be undone\n\nIf the intent is to stop the rule from firing temporarily rather than permanently remove it, consider using PATCH /v1/enterprise/{enterprise_id}/alarmrules/{alarm_id}/ to set is_active=false instead\n\nReview firing history via GET /alarmrules/{alarm_id}/alarmhistory/ before deleting if the rule's historical trigger data is needed for reporting or auditing purposes — this data will not be recoverable after deletion\n\nNote that deleting an alarm rule does not delete the alert channels it referenced — channels are enterprise-level resources and remain available for use by other rules\n", "operationId": "deleteAlarmRule", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "alarm_id", "in": "path", "description": "A UUID string identifying the alarm ruleset.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The resource was deleted successfully." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v1/enterprise/{enterprise_id}/alarmrules/{alarm_id}/alarmhistory/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Alarms" ], "summary": "Get history of alarm rule", "description": "⚠️ Android only. \n\nReturns the firing history for a specific alarm rule identified by its UUID alarm_id. Each record in the response represents an instance when the rule's conditions were met, identifying the device that triggered the alert, the group it belongs to, and the timestamps for when the alert fired and when the condition was last observed.\n\n**Response fields of note**\n\ndevice_name — Name of the device that triggered the alert\n\ndevice_id — UUID of the device that triggered the alert\n\ngroup_id — Array of group UUIDs the triggering device belongs to\n\ngroup_name — Name of the group the triggering device belongs to\n\nalert_time — Timestamp of when the alert fired\n\nlatest_seen — Timestamp of when the triggering condition was last observed on the device\n\n**Common use cases**\n\nInvestigating which specific devices triggered an alarm rule and when, to support troubleshooting or incident response\n\nAuditing alert activity before deleting an alarm rule to preserve a record of its history\n\nAssessing whether a rule is firing too frequently or on unexpected devices, to inform threshold tuning\n\nGenerating compliance or operational reports on device health events over time\n\n**Best practices**\n\nReview this endpoint before deleting an alarm rule — firing history is not recoverable after the rule is deleted\n\nCross-reference device_id values with GET /enterprise/{enterprise_id}/device/{device_id}/ to retrieve full device context for triggered alerts\n\nalarm_id is a UUID — use GET /alarmrules/ with the name filter to look it up if it is not already known\n", "operationId": "getAlarmHistory", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "alarm_id", "in": "path", "description": "A UUID string identifying the alarm ruleset.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_AlarmHistory" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v1/enterprise/{enterprise_id}/wallpaper/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Wallpapers" ], "summary": "Get list of wallpapers", "description": "Returns a paginated list of all wallpaper images uploaded to the enterprise. Each result includes the image URL, thumbnail URL, orientation, and active status. Wallpapers can be uploaded directly via the API or may have been added through a blueprint configuration.\n\n**Response fields of note**\n\nid — UUID identifying the wallpaper; used to reference it in Windows blueprint wallpaper settings\n\nimage_file — URL of the full-resolution wallpaper image\n\nthumbnail — URL of the thumbnail preview\n\norientation — Orientation of the image (e.g., landscape)\n\nis_active — Whether the wallpaper is currently active\n\ncreated_on / updated_on — Timestamps for auditing purposes\n\n**Common Use Cases**\n\nDiscovering wallpaper_id values to reference in Windows blueprint homescreen or lock screen wallpaper settings\n\nVerifying a wallpaper was successfully uploaded before referencing it in a blueprint\n\nBuilding wallpaper selection UIs in custom management tools\n\n**Best Practices**\n\nUse timestamp filters to scope results when auditing recently added or modified wallpapers rather than fetching the full list\n\nStore wallpaper_id UUIDs for use in Windows blueprint configuration — the wallpaper_id field appears in both homescreen and lock screen landscape settings\n\nNote that wallpapers uploaded as part of a blueprint configuration will also appear in this list and can be reused across multiple blueprints", "operationId": "getWallpapers", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "created_on_gt", "in": "query", "description": "Filter applications created after a given timestamp.", "schema": { "type": "string", "format": "datetime" } }, { "name": "created_on_lt", "in": "query", "description": "Filter applications created before a given timestamp.", "schema": { "type": "string", "format": "datetime" } }, { "name": "updated_on_gt", "in": "query", "description": "Filter applications updated after a given timestamp.", "schema": { "type": "string", "format": "datetime" } }, { "name": "updated_on_lt", "in": "query", "description": "Filter applications updated before a given timestamp.", "schema": { "type": "string", "format": "datetime" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "description": "Return results from this index.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_Wallpaper" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Wallpapers" ], "summary": "Create wallpaper", "description": "Uploads a new wallpaper image to the enterprise. The image is submitted as a multipart/form-data request and, once uploaded, can be referenced by wallpaper_id in Windows blueprint homescreen and lock screen settings. There is no dedicated wallpaper library in the console. Wallpapers are only visible by previewing their associated blueprint.\n\n**Request body (multipart/form-data)**\n**Request body (multipart/form-data)**\n\nimage_file (required) — The image file to upload\n\n\norientation (required) — Orientation of the image (e.g., landscape)\n\n**Common Use Cases**\n\nAdding a new branded wallpaper before assigning it to a Windows blueprint\n\nProgrammatically uploading wallpapers as part of an enterprise onboarding or branding \n\n**Workflow**\n\nAdding a new branded wallpaper before assigning it to a blueprint\n\nProgrammatically uploading wallpapers as part of an enterprise onboarding or branding \n\n**Workflow**\n\nReplacing an outdated wallpaper by uploading a new version and updating blueprint references to point to the new wallpaper_id\n\n**Best Practices**\n\nStore the wallpaper_id UUID from the response — it is required to reference the wallpaper in a blueprint homescreen and lock screen settings\n\nSince wallpapers are not browsable in the Console, use GET /v1/enterprise/{enterprise_id}/wallpaper/ to audit what has been uploaded and avoid creating duplicates\n\n\nSpecify orientation accurately at upload time — this metadata cannot be changed after upload; upload a new image if the orientation needs to be corrected\n\n\nVerify a wallpaper is not referenced in any active blueprint before deleting it, as there is no Console warning to flag active references", "operationId": "addWallpaper", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "image_file", "orientation" ], "properties": { "image_file": { "type": "string", "description": "Valid file to upload", "format": "path" }, "orientation": { "type": "string", "description": "Orientation of image e.g. landscape" } } } } }, "required": true }, "responses": { "201": { "description": "Successful Operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Wallpaper" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "415": { "description": "Unsupported media type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v1/enterprise/{enterprise_id}/wallpaper/{wallpaper_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Wallpapers" ], "summary": "Get instance of wallpaper", "description": "Returns the details of a single wallpaper image identified by its UUID wallpaper_id, including the full-resolution image URL, thumbnail URL, orientation, and active status. There is no dedicated wallpaper library in the Console — wallpapers are only visible by previewing the blueprint they are associated with, making this endpoint the primary way to retrieve details for a specific wallpaper programmatically.\n\n**Response fields of note**\n**Response fields of note**\n\nid — UUID identifying the wallpaper\n\n\nimage_file — URL of the full-resolution wallpaper image\n\nthumbnail — URL of the thumbnail preview\n\norientation — Orientation of the image (e.g., landscape)\n\nis_active — Whether the wallpaper is currently active\n\ncreated_on / updated_on — Timestamps for auditing purposes\n\n**Common Use Cases**\n\nRetrieving wallpaper details to confirm a successful upload before referencing the wallpaper_id in a blueprint\n\nAuditing the metadata of a specific wallpaper when the wallpaper_id is already known\n\nVerifying the orientation or active status of a wallpaper before assigning it to a Windows blueprint\n\n**Best Practices**\n\nIf the wallpaper_id is not already known, use GET /v1/enterprise/{enterprise_id}/wallpaper/ with timestamp filters to locate it — wallpapers are not browsable in the Console\n\nThis endpoint returns metadata and image URLs only; the image itself must be accessed directly via the image_file URL in the response", "operationId": "getWallpaper", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "wallpaper_id", "in": "path", "description": "A UUID string identifying the wallpaper.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Wallpaper" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Wallpapers" ], "summary": "Deletes instance of wallpaper", "description": "Permanently deletes a wallpaper image from the enterprise identified by its UUID wallpaper_id. This action is irreversible. Since there is no dedicated wallpaper library in the Console, use GET /v1/enterprise/{enterprise_id}/wallpaper/ to confirm the correct wallpaper_id before deleting.\n\n**Common Use Cases**\n\nRemoving outdated or superseded wallpaper images from the enterprise\n\nCleaning up duplicate or test wallpapers uploaded during setup\n\nDecommissioning branding assets that are no longer in use\n\n**Best Practices**\n\nVerify the wallpaper is not currently referenced in any active blueprint before deleting — there is no Console warning to flag active references, and removing a wallpaper that is still assigned to a blueprint may result in those devices receiving no wallpaper on next convergence\n\nConfirm the correct wallpaper_id using GET /v1/enterprise/{enterprise_id}/wallpaper/{wallpaper_id}/ before deleting — this action cannot be undone\n\nIf replacing a wallpaper rather than simply removing it, upload the new image first via POST /v1/enterprise/{enterprise_id}/wallpaper/, update all blueprint references to the new wallpaper_id, and then delete the old wallpaper", "operationId": "deleteWallpaper", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "wallpaper_id", "in": "path", "description": "A UUID string identifying the wallpaper.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The resource was deleted successfully." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v1/enterprise/{enterprise_id}/tile-icons/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Tile Icon" ], "summary": "Get List of Device Tile Icons", "description": "Retrieves the list of device tile icons configured for the enterprise. Once used for earlier versions of the Blueprints experience. \n\nReturns tile icon records.\n\n**About Device Tile Icons**\nDevice tile icons are the small representative images shown for devices in fleet/tile-style Console views. Icons can be built-in (by device_model/category) or custom-uploaded by the enterprise.\n", "operationId": "getTileIcons", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "created_on_gt", "in": "query", "description": "Filter tile icons created after a given timestamp.", "schema": { "type": "string", "format": "datetime" } }, { "name": "created_on_lt", "in": "query", "description": "Filter tile icons created before a given timestamp.", "schema": { "type": "string", "format": "datetime" } }, { "name": "updated_on_gt", "in": "query", "description": "Filter tile icons updated after a given timestamp.", "schema": { "type": "string", "format": "datetime" } }, { "name": "updated_on_lt", "in": "query", "description": "Filter tile icons updated before a given timestamp.", "schema": { "type": "string", "format": "datetime" } }, { "name": "category", "in": "query", "description": "Filter tile icons by category.", "schema": { "type": "string" } }, { "name": "device_model", "in": "query", "description": "Filter tile icons by device model.", "schema": { "type": "string" } }, { "name": "custom", "in": "query", "description": "Filter custom tile icons.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_TileIcon" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Tile Icon" ], "summary": "Create a tile icon", "description": "Creates a new custom tile icon for the enterprise. Once used for earlier versions of the Blueprints experience. \n\n\nUploads a new icon image, optionally associated with a specific device model, for use in Console fleet tile views.\n\n**About Device Tile Icons**\nDevice tile icons are the small representative images shown for devices in fleet/tile-style Console views. Custom icons let an enterprise brand or distinguish specific device types beyond the built-in icon set.\n", "operationId": "addTileIcon", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "icon_file", "device_model", "enterprise" ], "properties": { "icon_file": { "type": "string", "description": "Valid file to upload", "format": "path" }, "device_model": { "type": "string", "description": "Device model" }, "enterprise": { "type": "string", "format": "uuid", "description": "UUID string representing enterprise of tile icon" } } } } }, "required": true }, "responses": { "201": { "description": "Successful Operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_TileIcon" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "415": { "description": "Unsupported media type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v1/enterprise/{enterprise_id}/tile-icons/{tileicons_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Tile Icon" ], "summary": "Get instance of a tile icon", "description": "Retrieves a single device tile icon by ID. Once used for earlier versions of the Blueprints experience. \n\n\nReturns the details of one tile icon record, identified by tileicons_id.\n\n**About Device Tile Icons**\nDevice tile icons are the small representative images shown for devices in fleet/tile-style Console views.\n", "operationId": "getTileIcon", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "tileicons_id", "in": "path", "description": "A UUID string identifying the tile icon.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_TileIcon" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Tile Icon" ], "summary": "Delete a tile icon", "description": "Deletes a device tile icon.\n\nPermanently removes the specified custom tile icon from the enterprise's icon library. Once used for earlier versions of the Blueprints experience. \n\n\n**About Device Tile Icons**\nDevice tile icons are the small representative images shown for devices in fleet/tile-style Console views. Deleting a custom icon that is currently applied to devices will leave those devices without that specific icon in fleet views.\n", "operationId": "deleteTileIcon", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "tileicons_id", "in": "path", "description": "A UUID string identifying the tile icon.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The resource was deleted successfully." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v1/enterprise/{enterprise_id}/tile-icon-apply/": { "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Tile Icon" ], "summary": "Set a tile icon for a device", "description": "Applies a tile icon to one or more devices, groups, or a device model. Once used for earlier versions of the Blueprints experience. \n\n\nSets the specified icon as the tile icon for the target scope, determined by apply_mode — individual devices, all devices, device groups, or all devices of a given model.\n\n**About Device Tile Icons**\nThis endpoint controls how an icon is scoped when applied — a single call can update a specific list of devices, every device in one or more groups, every device of a given model, or the entire fleet, depending on apply_mode.\n", "operationId": "applyTileIcon", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ApplyTileIcon" } } }, "required": true }, "responses": { "201": { "description": "Successful Operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ApplyTileIcon" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v1/enterprise/{enterprise_id}/tile-icon-unapply/": { "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Tile Icon" ], "summary": "Removes tile icon for device", "description": "Removes an applied tile icon from all devices of a given model. Tile icons were used in earlier versions of the Blueprints experience and are no longer used.\n\nClears the tile icon currently applied to every device that matches the specified model, returning those devices to their default icon.\n\n**About Device Tile Icons**\nTile icons set the icon shown for a device. To set one, use `POST /v1/enterprise/{enterprise_id}/tile-icon-apply/`.\n\n**Key Fields / Query Parameters**\n- `model` — Device model whose tile icon to remove (required)\n", "operationId": "removeTileIcon", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "model" ], "properties": { "model": { "type": "string", "description": "Model of device" } } } } }, "required": true }, "responses": { "201": { "description": "Successful Operation", "content": { "application/json": { "schema": { "properties": { "model": { "type": "string", "description": "Model of device" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v1/enterprise/{enterprise_id}/report/location/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Device Telemetry" ], "summary": "Get list of device locations", "description": "Lists reported location data for devices in an enterprise.\n\nReturns a paginated list (count/next/previous/results) of DeviceLocations records, the same data source used to power the Console's device map/location dashboard view.\n\n**About Device Location Reports**\n\nThis is part of Esper's Device Telemetry reporting, which surfaces device-reported data (like location) for fleet monitoring rather than issuing commands to devices.\n\n**Key Fields / Query Parameters**\n\n- limit — number of results to return per page\n- offset — the initial index from which to return results\n\n**Common Use Cases**\n\n- Powering a map view of where fleet devices are located\n- Auditing device location history for compliance or asset-tracking purposes\n", "operationId": "getDeviceLocations", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_DeviceLocations" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v1/enterprise/{enterprise_id}/report/location/{location_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Device Telemetry" ], "summary": "Get location of specific device", "description": "Retrieves a single reported device location record by ID.\n\nReturns the DeviceLocations detail for the given location_id, useful when you already have a specific location record's identifier (for example, from the list endpoint) and want its full detail.\n\n**About Device Location Reports**\n\nThis is part of Esper's Device Telemetry reporting, which surfaces device-reported data such as location for fleet monitoring. The location_id here identifies a specific reported location record, not the device itself.\n\n**Key Fields / Query Parameters**\n\n- location_id — integer ID of the specific location record to retrieve\n\n**Common Use Cases**\n\n- Fetching the detail behind a single location entry surfaced in a location list or map view\n", "operationId": "getSpecificLocations", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "location_id", "in": "path", "description": "An integer identifying the location.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_DeviceLocations" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v1/enterprise/{enterprise_id}/report/device-tiles/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Device Telemetry" ], "summary": "Get list of device tiles reports", "description": "⚠️ **Android only.** This endpoint returns data for Android devices only. For device-level reporting across platforms, use the Reports API (`POST /report/v0/reports`).\n\nRetrieves a paginated list of device tile records for the enterprise's fleet.\n\nEach record is a per-device summary that combines device details, network information, battery level, and security state. Supports a wide set of filters, including group, model, Android version, battery level, security status, and last-seen time.\n\n**About Device Tiles**\nA device tile is a snapshot of one device's status in a single record, convenient for fleet overviews and filtered lists. It's a summary view; for detailed or exportable device data, use the Reports API.\n\n**Key Fields / Query Parameters**\n- `group`, `group_multi`, `group_name` — Filter by device group ID or name\n- `battery_level_gte` / `battery_level_lte` — Filter by battery level range\n- `security_status`, `at_risk` — Filter by security state\n- `last_seen_gt` / `last_seen_lt` — Filter by when the device last checked in\n- `model`, `android_version`, `dpc_version` — Filter by hardware and software versions\n- `battery_level`, `security_state`, `network_info` — Key fields in each returned record\n\n**Common Use Cases**\n- Finding devices with low battery or a risky security state\n- Listing devices in a group that haven't checked in recently\n- Building a filtered fleet overview by model or Android version\n\n**Best Practices**\n- Combine filters to keep responses small on large fleets\n- Use `next` to page through results instead of requesting everything at once\n- Use the Reports API when you need full device-level data or exports\n\n**Workflow**\n1. Choose filters for the devices you need\n2. Call this endpoint with `enterprise_id` and those filters\n3. Follow `next` until it's null\n", "operationId": "getDeviceTileReports", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "Filter device-tile reports by state.", "schema": { "type": "integer" } }, { "name": "created_on_gt", "in": "query", "description": "Filter device-tile reports created after a given timestamp.", "schema": { "type": "string", "format": "datetime" } }, { "name": "created_on_lt", "in": "query", "description": "Filter device-tile reports created before a given timestamp.", "schema": { "type": "string", "format": "datetime" } }, { "name": "provisioned_on_gt", "in": "query", "description": "Filter device-tile reports provisioned after a given timestamp.", "schema": { "type": "string", "format": "datetime" } }, { "name": "provisioned_on_lt", "in": "query", "description": "Filter device-tile reports provisioned before a given timestamp.", "schema": { "type": "string", "format": "datetime" } }, { "name": "updated_on_gt", "in": "query", "description": "Filter device-tile reports updated after a given timestamp.", "schema": { "type": "string", "format": "datetime" } }, { "name": "updated_on_lt", "in": "query", "description": "Filter device-tile reports updated before a given timestamp.", "schema": { "type": "string", "format": "datetime" } }, { "name": "last_seen_gt", "in": "query", "description": "Filter device-tile reports last seen after a given timestamp.", "schema": { "type": "string", "format": "datetime" } }, { "name": "last_seen_lt", "in": "query", "description": "Filter device-tile reports last seen before a given timestamp.", "schema": { "type": "string", "format": "datetime" } }, { "name": "battery_level_gte", "in": "query", "description": "Filter device-tile reports by battery level greater than given battery level.", "schema": { "type": "number", "format": "double" } }, { "name": "battery_level_lte", "in": "query", "description": "Filter device-tile reports by battery level lower than given battery level.", "schema": { "type": "number", "format": "double" } }, { "name": "at_risk", "in": "query", "description": "Filter device-tile reports by whether they are at risk.", "schema": { "type": "boolean" } }, { "name": "security_status", "in": "query", "schema": { "$ref": "#/components/schemas/esper_cloud_api_SecurityStatesEnum" } }, { "name": "status", "in": "query", "description": "Filter device-tile reports by status.", "schema": { "type": "string" } }, { "name": "group", "in": "query", "description": "Filter device-tile reports by group.", "schema": { "type": "string", "format": "uuid" } }, { "name": "group_name", "in": "query", "description": "Filter device-tile reports by group name.", "schema": { "type": "string" } }, { "name": "group_name_multi", "in": "query", "description": "Filter device-tile reports using multiple group names.", "schema": { "type": "string", "description": "Add group names to filter by comma separating" } }, { "name": "group_multi", "in": "query", "description": "Filter device-tile reports by using multiple group ID's", "schema": { "type": "string", "format": "uuid", "description": "Add group UUID to filter by comma separating" } }, { "name": "group_multi_immediate", "in": "query", "description": "Filter device-tile reports by immediate groups", "schema": { "type": "string" } }, { "name": "group_null", "in": "query", "description": "Filter device-tile reports by availability of group. True returns device-tiles with no group. False returns device-tiles with group.", "schema": { "type": "string", "format": "boolean", "description": "Allowed values are True, False, true, false, 1, 0." } }, { "name": "imei", "in": "query", "description": "Filter device-tile reports by imei.", "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "Filter device-tile reports by device name.", "schema": { "type": "string" } }, { "name": "recently_added", "in": "query", "description": "Filter device-tile reports by recently added.", "schema": { "type": "boolean" } }, { "name": "is_gms", "in": "query", "description": "Filter device-tile reports for gms devices.", "schema": { "type": "boolean" } }, { "name": "tags", "in": "query", "description": "Filter device-tile reports by tag.", "schema": { "type": "string" } }, { "name": "is_geofence_applied", "in": "query", "description": "Filter device-tile reports by geofence application.", "schema": { "type": "boolean" } }, { "name": "serial", "in": "query", "description": "Filter device-tile reports by device serial id.", "schema": { "type": "string" } }, { "name": "android_version", "in": "query", "description": "Filter device-tile reports by android version.", "schema": { "type": "integer" } }, { "name": "android_version_multi", "in": "query", "description": "Filter device-tile reports by multiple android versions.", "schema": { "type": "integer", "description": "List of android versions- comma separated." } }, { "name": "wifi_ssid", "in": "query", "description": "Filter device-tile reports by wifi-ssid.", "schema": { "type": "string" } }, { "name": "network_type", "in": "query", "description": "Filter device-tile reports by network type.", "schema": { "type": "string" } }, { "name": "network_type_multi", "in": "query", "description": "Filter device-tile reports by multiple network types.", "schema": { "type": "string", "description": "List of network types, comma separated." } }, { "name": "model", "in": "query", "description": "Filter device-tile reports by device model.", "schema": { "type": "string" } }, { "name": "template", "in": "query", "description": "Filter device-tile reports by template.", "schema": { "type": "string" } }, { "name": "template_multi", "in": "query", "description": "Filter device-tile reports by multiple templates.", "schema": { "type": "string", "description": "List of templates, comma separated." } }, { "name": "policy", "in": "query", "description": "Filter device-tile reports by policy name.", "schema": { "type": "string" } }, { "name": "policy_multi", "in": "query", "description": "Filter device-tile reports by multiple policies.", "schema": { "type": "string", "description": "List of policy names, comma separated." } }, { "name": "policy_null", "in": "query", "description": "Filter device-tile reports by null-value policy.", "schema": { "type": "boolean" } }, { "name": "dpc_version", "in": "query", "description": "Filter device-tile reports by DPC version.", "schema": { "type": "string" } }, { "name": "location", "in": "query", "description": "Filter device-tile reports by location.", "schema": { "type": "string", "description": "City or state can be used to filter location." } }, { "name": "active_connection", "in": "query", "description": "Filter device-tile reports by active connection status.", "schema": { "type": "boolean" } }, { "name": "device_type", "in": "query", "description": "Filter device-tile reports by device type.", "schema": { "type": "string" } }, { "name": "has_seamlessInfo", "in": "query", "description": "Filter device-tile reports by seamless information.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_DeviceTiles" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v1/enterprise/{enterprise_id}/report/device-tiles/{device_tiles_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Device Telemetry" ], "summary": "Get instance of device tiles report", "description": "Android only.\n\nRetrieves a single device tiles report instance. Use the Reports endpoints for device-level reporting. \n\nReturns the full detail for one device tile report record, identified by device_tiles_id.\n\n**About Device Tiles Report**\nThe Device Tiles report powers Console fleet views that show a tile per device with at-a-glance status. This single-record endpoint returns detail for one such tile.\n", "operationId": "getDeviceTileReport", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "device_tiles_id", "in": "path", "description": "An integer representing the device tile report.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_DeviceTiles" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v1/enterprise/{enterprise_id}/report/status-metrics/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Device Telemetry" ], "summary": "Get status metrics report for enterprise", "description": "Android only.\n\nReturns a single aggregate object of fleet-wide device status counts for the enterprise.\n\nReturns one JSON object (not a per-device list or paginated collection) with fixed count fields covering enrollment state, security risk classification, battery, provisioning, and recency — a snapshot of the whole fleet in one call.\n\n**About Status Metrics Report (v1)**\nThis v1 report returns exactly one object with a fixed set of integer count fields.\n", "operationId": "getStatusMetrics", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_StatusMetrics" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/enterprise/report/info/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Daily and Custom Reports" ], "summary": "Get report information", "description": "⚠️ Legacy feature. Android only. Daily and Custom Reports are a legacy feature. For current reporting needs, use the Reports API: GET /report/v0/report-types, POST /report/v0/reports, and GET /report/v0/reports/{report_id}.\n\nRetrieves metadata about your enterprise's reporting configuration, including how far back historical report data is available.\n\nUse this endpoint to check whether the reports workflow is enabled for your enterprise and the earliest date from which report data can be queried before making date-scoped report requests.\n\n**About Get Report Info**\n\nThis endpoint returns two key configuration values for the enterprise's legacy reporting system: reportAvailabilityFrom, which indicates the earliest datetime from which historical report data exists, and enableReports**Workflow**, a boolean indicating whether the reporting feature is active. Query this endpoint first when working with the legacy report endpoints to avoid date-range errors and confirm feature availability.\n", "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "reportAvailabilityFrom": { "type": "string", "format": "date-time" }, "enableReports**Workflow**": { "type": "boolean" } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/enterprise/report/device-report/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Daily and Custom Reports" ], "summary": "Get device status reports within specified date-time range", "description": "⚠️ Legacy feature. Android only. Daily and Custom Reports are a legacy feature. For current reporting needs, use the Reports API: GET /report/v0/report-types, POST /report/v0/reports, and GET /report/v0/reports/{report_id}.\n\nReturns per-device status reports organized by device group for a specified date-time range.\nThis endpoint provides a hierarchical view of device health data grouped by Esper device groups, including active, inactive, registered, new, and disabled device counts, with per-device detail records nested inside each group.\n\n**About Get Device Report**\n\nThe device report is a time-scoped snapshot of device status across your fleet, structured by group. Each group entry includes aggregate device counts and an array of DeviceStatusReport objects representing individual devices. Both start_date and end_date are required; only data within that window is returned.\n", "operationId": "getDeviceReport", "parameters": [ { "name": "start_date", "in": "query", "required": true, "description": "Start date of range in which to retrieve device status reports", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_date", "in": "query", "required": true, "description": "End date of range in which to retrieve device status reports", "schema": { "type": "string", "format": "date-time" } }, { "name": "sync", "in": "query", "required": false, "description": "Sync device status report to specified field", "schema": { "type": "boolean", "default": true } }, { "name": "fields", "in": "query", "required": false, "description": "List of fields to add to device status report, comma separated", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "group_id": { "type": "string", "format": "uuid" }, "group_name": { "type": "string" }, "group_path": { "type": "string" }, "active_devices": { "type": "integer" }, "inactive_devices": { "type": "integer" }, "registered_devices": { "type": "integer" }, "new_devices": { "type": "integer" }, "disabled_devices": { "type": "integer" }, "device_status_reports": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_DeviceStatusReport" } } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/enterprise/report/enterprise-report/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Daily and Custom Reports" ], "summary": "Get enterprise report", "description": "⚠️ Legacy feature. Android only.Daily and Custom Reports are a legacy feature. For current reporting needs, use the Reports API: GET /report/v0/report-types, POST /report/v0/reports, and GET /report/v0/reports/{report_id}.\n\nReturns a high-level summary of device provisioning and activity across the entire enterprise for a specified date-time range.\nUse this endpoint to retrieve top-level fleet metrics — peak active devices, total provisioned devices, and total registered devices — for a given reporting window, without group or per-device breakdowns.\n\n**About Get Enterprise Report**\n\nThe enterprise report provides a single aggregated view of fleet scale and activity for a time window bounded by start_date and end_date. Unlike the device report (per-device data by group) or the group report (segmented by group), this endpoint collapses the entire fleet into three summary metrics. It is most useful for executive dashboards, capacity planning, and trend tracking in legacy reporting contexts.\n", "operationId": "getEnterpriseReport", "parameters": [ { "name": "start_date", "in": "query", "required": true, "description": "Start date of range in which to retrieve enterprise report.", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_date", "in": "query", "required": true, "description": "End date of range in which to retrieve enterprise report.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "peak_active_devices": { "type": "integer" }, "provisioned_devices": { "type": "integer" }, "registered_devices": { "type": "integer" } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/enterprise/report/group-report/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Daily and Custom Reports" ], "summary": "Get group report", "description": "⚠️ Legacy feature. Android only. Daily and Custom Reports are a legacy feature. For current reporting needs, use the Reports API: GET /report/v0/report-types, POST /report/v0/reports, and GET /report/v0/reports/{report_id}.\n\nReturns device count summaries broken down by device group for a specified date-time range.\nUse this endpoint to get group-level device status aggregates — active, inactive, registered, new, and disabled counts — without per-device detail records.\n\n**About Get Group Report**\n\nThe group report provides a fleet view organized by Esper device groups, returning one GroupReport object per group within the specified date window. It is a leaner alternative to the device report when group-level aggregates are all that's needed. Both start_date and end_date are required.\n", "operationId": "getGroupReport", "parameters": [ { "name": "start_date", "in": "query", "required": true, "description": "Start date of range in which to retrieve group report.", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_date", "in": "query", "required": true, "description": "End date of range in which to retrieve group report.", "schema": { "type": "string", "format": "date-time" } }, { "name": "sync", "in": "query", "required": false, "description": "Sync device status report to specified field", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_GroupReport" } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/enterprise/report/subscription/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Daily and Custom Reports" ], "summary": "Get list of subscription reports", "description": "⚠️ Legacy feature. Android only. Daily and Custom Reports are a legacy feature. For current reporting needs, use the Reports API: GET /report/v0/report-types, POST /report/v0/reports, and GET /report/v0/reports/{report_id}.\n\nCreates a new report subscription that sends scheduled daily reports to one or more email addresses.\nSupply a list of recipient email addresses in the request body; Esper creates a subscription record and begins delivering daily fleet reports to those recipients.\n\n**About Create Report Subscription**\n\nReport subscriptions were Esper's mechanism for automated, scheduled delivery of daily device and fleet status reports via email. Subscriptions are part of the legacy Daily and Custom Reports system and do not exist in the current Reports API. Each subscription holds a list of recipient email addresses and an is_subscribed toggle. The integer id returned on creation is required for all subsequent GET, PUT, PATCH, and DELETE operations on the subscription.\n", "operationId": "getSubscriptionReports", "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_Subscription" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Daily and Custom Reports" ], "summary": "Post subscription to enterprise", "description": "⚠️ Legacy feature. Android only.Daily and Custom Reports are a legacy feature, and report subscriptions are not part of the current reporting system. For current reporting needs, use the Reports API: GET /report/v0/report-types, POST /report/v0/reports, and GET /report/v0/reports/{report_id}.\n\nReturns a paginated list of all report subscriptions configured for the enterprise.\nUse this endpoint to inspect which email addresses are enrolled for legacy daily report delivery and the active/inactive state of each subscription record.\n\n**About List Report Subscriptions**\n\nThis endpoint returns all legacy subscription records associated with the enterprise, each containing the recipient email list, subscription status, and timestamps. Subscriptions are not part of the current Reports API — this endpoint is relevant only for enterprises still operating on the legacy Daily and Custom Reports system. Results are paginated with count, next, previous, and results fields.\n", "operationId": "addSubscription", "requestBody": { "content": { "application/json": { "schema": { "required": [ "email_ids" ], "properties": { "email_ids": { "type": "array", "items": { "type": "string", "format": "email" } } } } } }, "required": true }, "responses": { "201": { "description": "Successful Operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Subscription" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/enterprise/report/subscription/{subscription_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Daily and Custom Reports" ], "summary": "Get instance of subscription", "description": "⚠️ Legacy feature. Android only.Daily and Custom Reports are a legacy feature, and report subscriptions are not part of the current reporting system. For current reporting needs, use the Reports API: GET /report/v0/report-types, POST /report/v0/reports, and GET /report/v0/reports/{report_id}.\n\nRetrieves a single legacy report subscription record by its integer subscription ID.\nUse this endpoint to inspect the full detail of a specific subscription — its recipient email addresses, active/inactive status, and creation and modification timestamps.\n\n**About Get Report Subscription**\n\nEach subscription record represents a configured channel for legacy daily report delivery. This endpoint returns the full Subscription object for the given subscription_id, including email_ids, is_subscribed, created_on, and updated_on. Note that subscription_id is an integer, not a UUID. Subscriptions are part of the legacy Daily and Custom Reports system and do not exist in the current Reports API.\n", "operationId": "getSubscriptionReport", "parameters": [ { "name": "subscription_id", "in": "path", "description": "A integer value identifying the subscription", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Subscription" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Daily and Custom Reports" ], "summary": "Update subscription", "description": "⚠️ Legacy feature. Android only. Daily and Custom Reports are a legacy feature. For current reporting needs, use the Reports API: GET /report/v0/report-types, POST /report/v0/reports, and GET /report/v0/reports/{report_id}.\n\nFully replaces an existing legacy report subscription with a new configuration, including an updated recipient list and subscription state.\nUse PUT when you need to overwrite the complete subscription record — supply email_ids (required) and optionally is_subscribed; omitted fields will be cleared.\n\n**About Update Report Subscription (Full)**\n\nPUT performs a full replacement of the subscription resource identified by subscription_id. Unlike PATCH (which supports partial updates), PUT requires email_ids and overwrites all editable fields. Subscriptions are part of the legacy Daily and Custom Reports system and do not exist in the current Reports API. Use PATCH if you only need to change a single field.\n", "operationId": "updateSubscriptionReport", "parameters": [ { "name": "subscription_id", "in": "path", "description": "A integer value identifying the subscription.", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "email_ids" ], "properties": { "email_ids": { "type": "array", "items": { "type": "string", "format": "email" } }, "is_subscribed": { "type": "boolean" } } } } }, "required": true }, "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Subscription" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "patch": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Daily and Custom Reports" ], "summary": "Partially update subscription", "description": "⚠️ Legacy feature. Android only. Daily and Custom Reports are a legacy feature, and report subscriptions are not part of the current reporting system. For current reporting needs, use the Reports API: GET /report/v0/report-types, POST /report/v0/reports, and GET /report/v0/reports/{report_id}.\n\nPartially updates a legacy report subscription, allowing changes to recipient email addresses or subscription state without replacing the full record.\nUse PATCH when you need to modify only email_ids or is_subscribed — fields omitted from the request body are left unchanged.\n\n**About Partial Update Report Subscription**\n\nPATCH supports sparse updates to a subscription record. Unlike PUT (full replacement), PATCH lets you supply only the fields to change, making it preferred for toggling is_subscribed or making targeted recipient list changes. Subscriptions are part of the legacy Daily and Custom Reports system and do not exist in the current Reports API.\n", "operationId": "patchSubscriptionReport", "parameters": [ { "name": "subscription_id", "in": "path", "description": "A integer value identifying the subscription.", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "email_ids": { "type": "array", "items": { "type": "string", "format": "email" } }, "is_subscribed": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Subscription" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Daily and Custom Reports" ], "summary": "Deletes instance of subscription", "description": "⚠️ Legacy feature. Android only. Daily and Custom Reports are a legacy feature, and report subscriptions are not part of the current reporting system. For current reporting needs, use the Reports API: GET /report/v0/report-types, POST /report/v0/reports, and GET /report/v0/reports/{report_id}.\n\nPermanently deletes a legacy report subscription, stopping all future scheduled report deliveries to its recipients.\nThis operation is irreversible; the subscription record and its recipient list are removed entirely. Returns HTTP 204 with no response body on success.\n\n**About Delete Report Subscription**\n\nDeleting a subscription removes the record and ends automated daily report delivery to all associated email addresses immediately. There is no soft-delete or recovery path. Subscriptions are part of the legacy Daily and Custom Reports system and do not exist in the current Reports API. If you only need to pause delivery temporarily, use PATCH with is_subscribed: false instead of deleting the record.\n", "operationId": "deleteSubscriptionReport", "parameters": [ { "name": "subscription_id", "in": "path", "description": "A integer value identifying the subscription.", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "The resource was deleted successfully." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v2/enterprise/{enterprise_id}/report/status-metrics": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Device Telemetry" ], "summary": "Get status metrics report for enterprise v2", "description": "Android only.\n\nReturns fleet-wide status metrics for the enterprise dashboard, broken down by device risk level, battery status, provisioning state, and last-seen recency.\n\nUse this endpoint to power dashboard summary tiles rather than per-device detail — it returns pre-aggregated counts, not a device list. This is the v2 replacement for the original status-metrics endpoint; the main functional change is that the flat active/in_active device counts from v1 are replaced here with a last_seen breakdown that buckets devices by how recently they last checked in.\n\n**About Get Status Metrics v2**\n\nThis endpoint backs the summary tiles on the Esper Console dashboard, giving a fleet-level snapshot without requiring a full device list pull. It's scoped to a single enterprise and returns a single aggregate object rather than a paginated collection. Compared to v1, it trades the simple active/inactive split for finer-grained recency buckets under last_seen, at the cost of losing the flat active-device total.\n\n**Key Fields**\n\n- last_seen — object bucketing devices by last check-in recency. The fields less_than_30_minutes, less_than_1_day, and greater_than_1_day, but a live correspond to first_period, second_period, third_period (same three buckets, different keys). \n- unprovisioned_devices — appears in live responses but is not documented in the current spec. In a sample response its value was identical to under_provisioning; treat these as possibly-duplicate until confirmed with the API team.\n- under_provisioning — count of devices that haven't completed provisioning.\n- unspecified — devices that don't fall into any named risk bucket. In practice this can dwarf every named risk bucket combined (98,595 unspecified vs. 0 across low_risk/medium_risk/high_risk/secure in a live sample) — don't assume the named buckets reflect real risk distribution.\n- total_devices_under_risk — aggregate count of devices flagged at risk across the named risk buckets.\n- low_risk / medium_risk / high_risk / secure — named security risk-level buckets.\n- low_battery — devices currently reporting low battery.\n- recently_added — devices added to the fleet recently.\n", "operationId": "getStatusMetricsV2", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_StatusMetricsV2" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v0/enterprise/{enterprise_id}/developerapp/{developerapp_id}/renew-token/": { "post": { "x-badges": [ { "name": "Deprecated", "color": "red" } ], "tags": [ "esper_cloud_api_Token (Deprecated)" ], "summary": "Renew Token", "description": "Renews an API token issued to a developer app.\n\n⚠️ **Deprecation Notice:** This endpoint is deprecated. Use personal access tokens instead. To extend a token's expiry, use `PUT /authn2/v0/personal-access-token/{personal_access_token_id}`.\n", "operationId": "renewToken", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "developerapp_id", "in": "path", "description": "A UUID string identifying the developerapp", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "access_token", "in": "query", "description": "Token to be renewed", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_TokenRenewV0" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v0/enterprise/{enterprise_id}/device/{device_id}/command-history/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Commands V2" ], "summary": "get command history for device", "description": "⚠️ Android only. This endpoint applies exclusively to Android-managed devices enrolled in Esper.\n\n**Alternative Available**\n\nUse https://api.esper.io/openapi/command-status/getcommandinbox for a device's queued commands.\n\nReturns the full command history for a specific device, filterable by execution state.\n\nReturns a paginated list of V0CommandStatus records scoped to the specified device, each including the command name, arguments, issuing user, current state, reason, requeue count, and timestamps. \n\nThis provides richer detail than the per-request status endpoint, making it the preferred choice for device-level command audit and troubleshooting.\n\n**About Device Command History**\n\nWhile GET .../command/{request_id}/status/ surfaces status for a specific command request across its target devices, the command-history endpoint inverts the view — returning all commands ever \nissued to a single device, regardless of which request they originated from. Each record includes the full command name, the command_args used, the issued_by user object, a requeue_value tracking how many times the command was retried, and the reason for the current state. This makes it the authoritative source for per-device command forensics.\n\n**Key Query Parameters / Fields**\n\nstate — optional filter; narrows results to a specific execution state (e.g. Command Failure, Command Success)\n\ncommand — the name of the operation that was issued (e.g. INSTALL, REBOOT)\n\ncommand_args — the arguments passed with the command\n\nissued_by — object containing id and username of the user who issued the command\n\nrequeue_value — number of times the command was requeued for this device \n\nreason — plain-language detail on why the command is in its current state\n\n**Common Use Cases**\n\nReview the full command history for a device during a support or compliance investigation.\n\nIdentify repeatedly failing commands and the arguments that were used.\nAudit which users issued which commands to a device over its lifecycle.\n\n**Best Practices**\n\nFilter by state=Command Failure or state=Command TimeOut to surface problem commands without reviewing the entire history.\n\nUse requeue_value to identify commands that were retried the maximum number of times — these are likely permanent failures requiring manual intervention.\n\nPair this endpoint with the event feed (GET .../report/eventfeed/) for a complete device activity picture: command history shows operational commands; the event feed shows broader device state transitions.\n\n**Workflow**\n\nObtain the device_id from a device list call or stored reference.\n\nCall this endpoint, optionally filtering by state, to retrieve the command history.\n\nInvestigate failures using the command, command_args, reason, and requeue_value fields.", "operationId": "getDeviceCommandHistory", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "Id of the enterprise", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "device_id", "in": "path", "description": "Id for the command request", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "state", "in": "query", "description": "Filter by command state", "schema": { "type": "string" } } ], "responses": { "200": { "description": "on successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "format": "int64" }, "next": { "type": "string", "format": "url" }, "previous": { "type": "string", "format": "url" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_V0CommandStatus" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v0/enterprise/{enterprise_id}/geofence/": { "get": { "x-badges": [ { "name": "Legacy", "color": "orange" } ], "tags": [ "esper_cloud_api_Geofence" ], "summary": "List Geofences in Enterprise", "description": "Legacy endpoint. Android only. Geofence configuration is now managed through blueprints. Use the blueprints endpoints (/api/v2/blueprints/) to create and manage geofences going forward.\n\n\nReturns a paginated list of all geofences defined within the enterprise.Use this endpoint to audit existing legacy geofence definitions — their coordinates, radii, and configured device actions — before migrating configurations to blueprints.\n\n**About List Geofences (Legacy)**\n\nA geofence in Esper defines a geographic boundary — specified by latitude, longitude, and a radius — that triggers device actions (such as lockdown or beep) when a device crosses it. This endpoint belongs to the original standalone geofence API, which has been superseded by geofence configuration within blueprints. New integrations should use /api/v2/blueprints/ rather than this legacy path.\n", "operationId": "getAllGeofences", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying the enterprise.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "description": "A search term.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_Geofence" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v0/enterprise/{enterprise_id}/geofence/{geofence_id}/": { "get": { "x-badges": [ { "name": "Legacy", "color": "orange" } ], "tags": [ "esper_cloud_api_Geofence" ], "summary": "Get geofence information", "description": "⚠️ Legacy endpoint. Geofence configuration is now managed through blueprints. Use the blueprints endpoints (/api/v2/blueprints/) to create and manage geofences going forward.\n\n Retrieves the full details of a single geofence by its UUID.Returns the complete Geofence object including coordinates, radius, configured device actions, device count, and audit timestamps; useful during migration to read the exact parameters of a legacy geofence before recreating it in a blueprint.\n \n **About Get Geofence (Legacy)**\n\n This endpoint fetches a single legacy geofence record by geofence_id. Geofences in this legacy system were standalone entities associated with an enterprise and optionally applied to individual devices. The current approach embeds geofence definitions within blueprints via /api/v2/blueprints/, enabling consistent application across device groups rather than per-device assignment.\n", "operationId": "getGeofence", "parameters": [ { "name": "geofence_id", "in": "path", "description": "A UUID string identifying the geofence.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying the enterprise.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Geofence" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "put": { "x-badges": [ { "name": "Legacy", "color": "orange" } ], "tags": [ "esper_cloud_api_Geofence" ], "summary": "Update geofence information", "description": "⚠️ Legacy endpoint. Android only. Geofence configuration is now managed through blueprints. Use the blueprints endpoints (/api/v2/blueprints/) to create and manage geofences going forward.\n\nPerforms a full replacement update on an existing legacy geofence record.All writable fields must be included in the request body; omitting a field will overwrite it with a null or default value. Returns the updated Geofence object on success.\n\n**About Update Geofence — Full (Legacy)**\n\nThis PUT endpoint replaces the entire geofence definition for the specified geofence_id. It operates on the same legacy standalone geofence system as the other /geofence/ path endpoints. Because geofences are now configured within blueprints via /api/v2/blueprints/, edits here will not affect blueprint-managed geofence behavior. Use blueprints for all active geofence configuration changes.\n", "operationId": "updateGeofence", "parameters": [ { "name": "geofence_id", "in": "path", "description": "A UUID string identifying the geofence.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying the enterprise.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Geofence" } } }, "required": true }, "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Geofence" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ], "x-codegen-request-body-name": "data" }, "delete": { "x-badges": [ { "name": "Legacy", "color": "orange" } ], "tags": [ "esper_cloud_api_Geofence" ], "summary": "Delete a geofence", "description": "⚠️ Legacy endpoint. Android only. Geofence configuration is now managed through blueprints. Use the blueprints endpoints (/api/v2/blueprints/) to create and manage geofences going forward.\n\nPermanently deletes a legacy geofence record by its UUID.Returns HTTP 204 with an empty body on success; the deletion is immediate and irreversible. Use this to remove legacy geofence records after their configurations have been migrated to blueprints.\n\n**About Delete Geofence (Legacy)**\n\nThis endpoint removes a single legacy geofence from the enterprise. Unlike the blueprints system, which ties geofence lifecycle to blueprint deployment, this standalone record can be deleted independently. Before deleting, check device_count via GET to confirm whether any devices are still referencing the legacy geofence.\n", "operationId": "deleteGeofence", "parameters": [ { "name": "geofence_id", "in": "path", "description": "A UUID string identifying the geofence.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying the enterprise.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "The resource was deleted successfully." }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "patch": { "x-badges": [ { "name": "Legacy", "color": "orange" } ], "tags": [ "esper_cloud_api_Geofence" ], "summary": "Partially updates geofence information", "description": "⚠️ Legacy endpoint. Android only. Geofence configuration is now managed through blueprints. Use the blueprints endpoints (/api/v2/blueprints/) to create and manage geofences going forward.\n\nPartially updates one or more fields on an existing legacy geofence record. Only the fields included in the request body are modified; all other fields retain their current values. Returns the full updated Geofence object on success.\n\n**About Update Geofence — Partial (Legacy)**\n\nThis PATCH endpoint applies partial updates to a legacy geofence definition using the GeofenceUpdate schema, which accepts name, description, latitude, longitude, radius, radius_unit, and device_actions. Unlike PUT, omitted fields are preserved. Changes made here do not affect blueprint-managed geofence behavior; use /api/v2/blueprints/ for all active configuration management.\n", "operationId": "partialUpdateGeofence", "parameters": [ { "name": "geofence_id", "in": "path", "description": "A UUID string identifying the geofence.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying the enterprise.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GeofenceUpdate" } } }, "required": true }, "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Geofence" } } } }, "400": { "description": "Bad Request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ], "x-codegen-request-body-name": "data" } }, "/v0/enterprise/{enterprise_id}/create-apply-geo-fence/": { "post": { "x-badges": [ { "name": "Legacy", "color": "orange" } ], "tags": [ "esper_cloud_api_Geofence" ], "summary": "Create a geofence", "description": "⚠️ Legacy endpoint. Android only. Geofence configuration is now managed through blueprints. Use the blueprints endpoints (/api/v2/blueprints/) to create and manage geofences going forward.\n\nCreates a new geofence and optionally applies it to a list of devices in a single request. Returns the newly created Geofence object (HTTP 201) with the assigned UUID; the devices field allows immediate application to specific devices at creation time, a capability not available through the separate /geofence/ path endpoints.\n", "operationId": "createGeofence", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying the enterprise.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GeofenceCreate" } } }, "required": true }, "responses": { "201": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Geofence" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ], "x-codegen-request-body-name": "data" }, "get": { "x-badges": [ { "name": "Legacy", "color": "orange" } ], "tags": [ "esper_cloud_api_Geofence" ], "summary": "List Geofences in Enterprise", "description": "⚠️ Legacy endpoint. Android only. Geofence configuration is now managed through blueprints. Use the blueprints endpoints (/api/v2/blueprints/) to create and manage geofences going forward.\n\nReturns a paginated list of all geofences in the enterprise via the legacy create-apply-geo-fence path.\n", "operationId": "getGeofenceList", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying the enterprise.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "description": "A search term.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_Geofence" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v0/enterprise/{enterprise_id}/create-apply-geofence/{geofence_id}/": { "get": { "x-badges": [ { "name": "Legacy", "color": "orange" } ], "tags": [ "esper_cloud_api_Geofence" ], "summary": "Get geofence information", "description": "⚠️ Legacy endpoint. Android only. Geofence configuration is now managed through blueprints. Use the blueprints endpoints (/api/v2/blueprints/) to create and manage geofences going forward.\n\nRetrieves the full details of a single geofence by UUID via the legacy create-apply-geofence detail path.\nReturns the same Geofence object as GET /v0/enterprise/{enterprise_id}/geofence/{geofence_id}/; this path is the detail counterpart to the create-apply-geo-fence creation endpoint, with the hyphenation normalized to create-apply-geofence.\n", "operationId": "getTheGeofence", "parameters": [ { "name": "geofence_id", "in": "path", "description": "A UUID string identifying the geofence.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying the enterprise.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Geofence" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "delete": { "x-badges": [ { "name": "Legacy", "color": "orange" } ], "tags": [ "esper_cloud_api_Geofence" ], "summary": "Delete a geofence", "description": "⚠️ Legacy endpoint. Android only. Geofence configuration is now managed through blueprints. Use the blueprints endpoints (/api/v2/blueprints/) to create and manage geofences going forward.\n\nPermanently deletes a legacy geofence record by UUID via the create-apply-geofence detail path.\n\nReturns HTTP 204 with an empty body on success. Remove devices from the geofence before deleting the geofence.\n", "operationId": "deleteTheGeofence", "parameters": [ { "name": "geofence_id", "in": "path", "description": "A UUID string identifying the geofence.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying the enterprise.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "The resource was deleted successfully." }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v1/enterprise/{enterprise_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Company Settings" ], "summary": "Get your company settings", "description": "Retrieves the current company settings for the specified enterprise.\n\nUse this endpoint to read enterprise-level configuration including contact information, location details, EMM enrollment status, and the enterprise's display name.\n\n**About Get Company Settings**\nThis endpoint (formerly \"Get Enterprise Information\") returns the EnterpriseV1 object for your enterprise — the root configuration record that identifies your organization within Esper. It includes both read-only system fields (id, short_code, created_on, updated_on, emm) and user-editable fields such as name, contact details, and location. The emm field surfaces whether the enterprise is enrolled in Google EMM and, if so, its google_enterprise_id. All editable fields can be updated via PATCH /v1/enterprise/{enterprise_id}/.\n\n**Key Fields**\n\nenterprise_id (path, required) — UUID of the enterprise to retrieve\n\nid (read-only) — UUID of the enterprise record\n\nshort_code (read-only) — Auto-generated 10-character identifier for the enterprise\n\nname — Display name of the enterprise\n\nregistered_name — Formal legal name of the organization\n\nregistered_address — Registered business address\n\nlocation — City, state, and country of the enterprise\n\ncontact_person / contact_number / contact_email — Primary point-of-contact details\n\nwifi_lte_toggle_flag — Whether the data saver mode feature is enabled (only present if the feature is active)\n\nemm — Google EMM enrollment details, including google_enterprise_id; null if not EMM-enrolled\n\n**Common Use Cases**\n\nReading enterprise metadata to populate an integration's configuration or audit log\n\nConfirming EMM enrollment status and retrieving the linked google_enterprise_id\n\nRetrieving the current values of all editable fields before issuing a PATCH update\n\n**Best Practices**\n\nUse this endpoint to read current state before calling PATCH — it ensures you don't unknowingly overwrite values you didn't intend to change\n\nTreat id, short_code, created_on, updated_on, and emm as read-only; they cannot be updated via PATCH\n\nCache the enterprise_id at integration setup time rather than fetching it on every request\n\n**Workflow**\n\nCall GET /v1/enterprise/{enterprise_id}/ with the enterprise UUID\n\nInspect the response for the fields relevant to your use case (e.g., emm for EMM enrollment status, contact_email for contact details)\n\nUse the returned field values as the baseline if you plan to follow up with a PATCH update\n", "operationId": "getEnterprise", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_EnterpriseV1" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "patch": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Company Settings" ], "summary": "Partially update company settings", "description": "Partially updates the company settings for the specified enterprise, returning the full updated record.\nSupply only the fields you want to change — all omitted fields retain their current values.\n\n**About Partial Update Company Settings**\n\nThis endpoint (formerly \"Partial Update Enterprise Information\") applies sparse updates to the EnterpriseV1 record using the EnterpriseUpdateV1 schema. All fields in the request body are optional; only those included will be changed. Read-only fields (id, short_code, created_on, updated_on, emm) cannot be modified and should be omitted from the request body. The response returns the complete updated EnterpriseV1 object. Call GET /v1/enterprise/{enterprise_id}/ first to retrieve current values before making changes.\n\n**Key Fields**\n\nenterprise_id (path, required) — UUID of the enterprise to update\n\nname (optional) — Display name of the enterprise (max 255 chars)\n\nregistered_name (optional) — Formal legal name of the organization\n\nregistered_address (optional) — Registered business address\n\nlocation (optional) — City, state, and country\n\nzipcode (optional) — Postal code for the enterprise location (max 8 chars)\n\ncontact_person (optional, nullable) — Primary point-of-contact name\n\ncontact_number (optional, nullable) — Contact phone number\n\ncontact_email (optional) — Contact email address\n\nwifi_lte_toggle_flag (optional) — Toggles data saver mode; only effective if the feature is enabled for the enterprise\n\n**Common Use Cases**\n\nUpdating enterprise contact details after an organizational change\n\nCorrecting the registered name or address on file\n\nToggling wifi_lte_toggle_flag when enabling or disabling data saver mode\n\n**Best Practices**\n\nCall GET /v1/enterprise/{enterprise_id}/ first to confirm current values before issuing a PATCH\n\nInclude only the fields you intend to change; PATCH is safe to use for single-field updates\n\nDo not include id, short_code, created_on, updated_on, or emm in the request body — they are read-only and will be ignored or may cause errors\n\nVerify the update took effect by inspecting the returned EnterpriseV1 object in the response\n\n**Workflow**\n\nCall GET /v1/enterprise/{enterprise_id}/ to retrieve the current enterprise record\n\nConstruct a partial payload containing only the fields to update\n\nCall PATCH /v1/enterprise/{enterprise_id}/ with the payload\n\nConfirm the changes in the returned EnterpriseV1 response object\n", "operationId": "partialUpdateEnterprise", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_EnterpriseUpdateV1" } } }, "required": true }, "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_EnterpriseV1" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ], "x-codegen-request-body-name": "data" } }, "/v1/enterprise/{enterprise_id}/application/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application V1" ], "summary": "List apps in enterprise", "description": "Returns a paginated list of all Android applications uploaded to the enterprise, with optional filters for name, package name, category, SDK version, and more.\n\nUse this endpoint to search and inventory the Android apps available in your enterprise before installing, managing, or auditing app versions across your fleet.\n\n**About List Applications**\n\nThis endpoint is part of the Application V1 family (/v1/enterprise/{enterprise_id}/application/...), which manages the enterprise's Android app library — uploaded APKs and Google Play-sourced apps. It is the V1 version of the unversioned GET /enterprise/{enterprise_id}/application/ endpoint; both share the same filter parameters and response shape but use different schema versions (ApplicationV1 vs Application).\n\nThere are two other application API families with distinct scopes\n\nTenant Apps (/v2/tenant-apps/...) — manages uploaded apps for iOS and Windows platforms (IPA files, Windows binaries). Use this family for non-Android app library management.\n\nDevice Apps (/v2/devices/{deviceId}/device-apps/ and GET /v2/device-apps) — queries apps installed on a specific device or finds devices with a given app installed, covering iOS and Windows app types (VPP, TENANT_IOS, ESPER_IOS, WEBCLIP, ESPER_WINDOWS, TENANT_WINDOWS). Use this family when you need device-level app inventory rather than the enterprise library.\n\nThis endpoint returns ApplicationV1 objects. Each result includes the app's UUID, display name, package name, and a nested latest_version object. Results are paginated with a default page size of 20. Use the application_id from results to target individual apps for deletion or version queries.\n\n**Key Fields / Query Parameters**\n\napplication_name — Filter by partial or full display name\n\npackage_name — Filter by Android package name (partial match)\n\npackage_name_exact — Filter by Android package name (exact match)\n\nhas_uploaded_version — When true, returns only apps with at least one uploaded version\n\ncategory — Filter by application category\n\nsupported_sdk — Filter by minimum Android SDK version supported\n\nis_active — Filter by active applications only\n\nis_hidden (default: false) — When true, includes Esper default system apps in results\n\ncreated_on_gt / created_on_lt — Filter by creation timestamp range\n\nupdated_on_gt / updated_on_lt — Filter by last-updated timestamp range\n\nlimit (default: 20) — Number of results per page\n\noffset (default: 0) — Starting index for pagination\n\n**Common Use Cases**\n\nSearching for an Android app by package name before retrieving its version list\n\nAuditing all apps registered to the enterprise\n\nBuilding a pre-install checklist by filtering for apps with has_uploaded_version: true\n\n**Best Practices**\n\nUse package_name_exact rather than package_name when you know the full package name — it avoids ambiguous partial matches\n\nFor iOS or Windows apps, use GET /v2/tenant-apps instead — this endpoint returns Android apps only\n\nFor per-device app inventory or to find which devices have a given app installed, use the Device Apps family (/v2/devices/{deviceId}/device-apps/ or GET /v2/device-apps) instead\n\nPaginate with limit and offset on large enterprises; use count from the response to determine total pages\n\nStore application_id values from results for use in version and install queries downstream\n\n**Workflow**\n\nCall GET /v1/enterprise/{enterprise_id}/application/ with relevant filters\n\nPaginate through results using next links or offset increments until next is null\n\nNote the id (application UUID) for any apps to inspect further\n\nUse the id to call GET /v1/enterprise/{enterprise_id}/application/{application_id}/ for full detail or proceed to version management", "operationId": "getAllApplicationsV1", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying this enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "application_name", "in": "query", "description": "filter by application name", "schema": { "type": "string" } }, { "name": "package_name", "in": "query", "description": "filter by package name", "schema": { "type": "string" } }, { "name": "package_name_exact", "in": "query", "description": "filter by package name (exact match)", "schema": { "type": "string" } }, { "name": "has_uploaded_version", "in": "query", "description": "Returns applications having at least one version uploaded", "schema": { "type": "boolean" } }, { "name": "category", "in": "query", "description": "filter by category", "schema": { "type": "string" } }, { "name": "supported_sdk", "in": "query", "description": "filter by supported sdk versions", "schema": { "type": "integer" } }, { "name": "is_active", "in": "query", "description": "filter by active applications", "schema": { "type": "boolean" } }, { "name": "is_hidden", "in": "query", "description": "filter default esper apps", "schema": { "type": "boolean", "default": false } }, { "name": "created_on_gt", "in": "query", "description": "filter applications created after a given timestamp", "schema": { "type": "string", "format": "datetime" } }, { "name": "created_on_lt", "in": "query", "description": "filter applications created before a given timestamp", "schema": { "type": "string", "format": "datetime" } }, { "name": "updated_on_gt", "in": "query", "description": "filter applications updated after a given timestamp", "schema": { "type": "string", "format": "datetime" } }, { "name": "updated_on_lt", "in": "query", "description": "filter applications updated before a given timestamp", "schema": { "type": "string", "format": "datetime" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "description": "Return results from this index.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_ApplicationV1" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v1/enterprise/{enterprise_id}/application/{application_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application V1" ], "summary": "Get application information", "description": "**Alternative Available** \nGET /enterprise/{enterprise_id}/application/{application_id}/\n\nTo retrieve an iOS or Windows application use GET /v2/tenant-apps/{appId}\n\nGet Android enterprise application details (V1). Retrieves application details including metadata and the latest version, such as version code, build number, minimum SDK version, package name, and visibility settings. Use this endpoint when working with blueprint configurations, as V1 application endpoints are used in blueprint **Workflow**s.\n\n**Common Use Cases** Retrieving application details before referencing an app in a blueprint, validating package name and version metadata prior to deployment, confirming app visibility (is_hidden) before assigning to devices or policies, and auditing SDK compatibility.\n\n**Best Practices** Use this endpoint when your **Workflow** involves blueprints — V1 application data is what blueprint configurations reference. For non-blueprint **Workflow**s, the non-versioned GET /enterprise/{enterprise_id}/application/{application_id}/ endpoint returns richer version detail. Confirm is_hidden status before assigning an app to a policy or device group to avoid silent failures.\n\n**Workflow**\n\n1. Use the List apps in enterprise (V1) endpoint to retrieve the application_id.\n2. Pass the application_id to this endpoint to retrieve full application details and latest version metadata.", "operationId": "getApplicationv1", "parameters": [ { "name": "application_id", "in": "path", "description": "A UUID string identifying this application.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ApplicationV1" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application V1" ], "summary": "Delete an application", "description": "Permanently deletes an Android application record and all of its associated versions from the enterprise.\n\nThis operation is irreversible; the application and every version uploaded under it are removed entirely. Returns HTTP 204 with no response body on success.\n\n**About Delete Application**\n\nThis endpoint is part of the Application V1 family, which manages the enterprise's Android app library. Deleting an application removes the top-level app record and cascades to all associated ApplicationVersionV1 records — every version uploaded under this application_id is deleted along with it. The app will no longer appear in the Android app inventory and cannot be targeted for installation or policy assignment. You must remove the application from all associated blueprints (and blueprint versions) before calling this endpoint.\n\nThere are two other application API families with distinct scopes:\n\nTenant Apps (/v2/tenant-apps/...) — manages uploaded apps for iOS and Windows platforms. Deletions of iOS or Windows apps are handled there.\nDevice Apps (/v2/devices/{deviceId}/device-apps/ and GET /v2/device-apps) — queries app install state on devices for iOS and Windows app types. This family does not perform deletions from the app library.\n\nIf you only need to remove a specific version rather than the entire app, use the version-level delete endpoint instead. There is no soft-delete or recovery path for this operation.\n\n**Key Fields**\n\nenterprise_id (path, required) — UUID of the enterprise\napplication_id (path, required) — UUID of the Android application to delete\n\n**Common Use Cases**\n\nRemoving an Android app that was uploaded in error or is no longer relevant to the fleet\n\nCleaning up the Android app library during a fleet restructure or platform migration\n\nPurging outdated or retired apps that should not be available for future installation\n\n**Best Practice**\n\nVerify the correct application_id using GET /v1/enterprise/{enterprise_id}/application/{application_id}/ before issuing DELETE — there is no undo\n\nCheck whether any devices still have the app installed before deleting; use GET /v1/enterprise/{enterprise_id}/application/{application_id}/version/{version_id}/installdevices per version to audit coverage\n\nTo delete iOS or Windows apps, use the Tenant Apps family (DELETE /v2/tenant-apps/{appId}) instead — this endpoint only covers the Android app library\n\nIf you only want to remove a specific version, use the version-level delete endpoint rather than deleting the entire application record\n\n**Workflow**\n\nConfirm the target app with GET /v1/enterprise/{enterprise_id}/application/{application_id}/\n\nOptionally audit installed devices per version using the installdevices endpoint\n\nCall DELETE /v1/enterprise/{enterprise_id}/application/{application_id}/\n\nExpect a 204 response with an empty body confirming deletion", "operationId": "deleteApplicationV1", "parameters": [ { "name": "application_id", "in": "path", "description": "A UUID string identifying this application.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The resource was deleted successfully." }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v1/enterprise/{enterprise_id}/application/{application_id}/version/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application V1" ], "summary": "List App versions", "description": "Lists all versions of a specific application using the V1 schema, which includes direct file and icon URLs, release date, and file size.\n\nReturns a paginated AppVersionV1 collection for the specified application, with the same filter set as the base version list plus timestamp filters. Unlike the base version endpoint, results include app_file (direct APK download URL), app_icon (icon URL), size_in_mb, and release_date. \n\n**About List App Versions (V1)**\n\nThe V1 version list returns the same logical set of version records as GET .../application/{application_id}/version/ but uses the AppVersionV1 schema, which surfaces additional fields that are absent from the base AppVersion schema: a direct download URL for the APK (app_file), an icon URL (app_icon), the file size in megabytes (size_in_mb), and a release_date timestamp. Use the V1 endpoint when your integration needs to display or verify file-level metadata without making additional requests. Note that release_track and target_sdk_version, present in the base schema, are not returned by AppVersionV1.\n\n**Key Query Parameters**\n\nversion_code — filter by version code string\n\nbuild_number — filter by build number\n\nis_g_play — true returns versions sourced from the Console Google Play Store\n\napproval_status — filter by AVAILABLE, ACCEPTED, APPROVED, or REJECTED\n\nis_enabled — filter for enabled versions\n\nis_default — filter for the default version\n\ncreated_on_gt / created_on_lt / updated_on_gt / updated_on_lt — timestamp range filters\n\nordering — sort by installed_count (ascending) or -installed_count (descending)\n\n**Common Use Cases**\n\nList versions when your integration needs direct APK download URLs or icon URLs without a separate lookup.\n\nRetrieve size_in_mb to estimate storage requirements before deploying a version to a fleet.\n\nUse timestamp filters for incremental sync **Workflow**s that track newly uploaded or updated versions.\n\n**Best Practices**\n\nPrefer the V1 endpoint over the base version list when you need app_file, app_icon, or size_in_mb — it avoids redundant per-version detail calls.\n\nNote that release_track and target_sdk_version are not available in the V1 schema; use the base version endpoint if those fields are required.\n\nFilter by approval_status=APPROVED and is_enabled=true to limit results to deployment-ready versions.\n\n**Workflow**\n\nCall this endpoint with the target application_id and relevant filters.\n\nUse app_file and app_icon URLs directly in your integration for display or download.\n\nRecord version_id values for use in install commands or V1 version detail lookups.", "operationId": "getAppVersionsV1", "parameters": [ { "name": "application_id", "in": "path", "description": "A UUID string identifying this application.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "version_code", "in": "query", "description": "filter by version code", "schema": { "type": "string" } }, { "name": "build_number", "in": "query", "description": "filter by build number", "schema": { "type": "string" } }, { "name": "is_g_play", "in": "query", "description": "filter google play applications", "schema": { "type": "boolean" } }, { "name": "approval_status", "in": "query", "description": "filter by approval status", "schema": { "type": "string", "enum": [ "AVAILABLE", "ACCEPTED", "APPROVED", "REJECTED" ] } }, { "name": "is_enabled", "in": "query", "description": "filter by enabled versions", "schema": { "type": "boolean" } }, { "name": "is_default", "in": "query", "description": "filter by default versions", "schema": { "type": "boolean" } }, { "name": "created_on_gt", "in": "query", "description": "filter applications created after a given timestamp", "schema": { "type": "string", "format": "datetime" } }, { "name": "created_on_lt", "in": "query", "description": "filter applications created before a given timestamp", "schema": { "type": "string", "format": "datetime" } }, { "name": "updated_on_gt", "in": "query", "description": "filter applications updated after a given timestamp", "schema": { "type": "string", "format": "datetime" } }, { "name": "updated_on_lt", "in": "query", "description": "filter applications updated before a given timestamp", "schema": { "type": "string", "format": "datetime" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "Return results from this index.", "schema": { "type": "integer", "default": 0 } }, { "name": "ordering", "in": "query", "schema": { "type": "string" }, "description": "Order result set by field name.\n* installed_count: order by asc\n* -installed_count: order by desc\n" } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_AppVersionV1" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v1/enterprise/{enterprise_id}/application/{application_id}/version/{version_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application V1" ], "summary": "Get app version information", "description": "Retrieves full V1 details for a single application version by its UUID, including direct APK and icon URLs, file size, and release date.\n\nReturns the AppVersionV1 object for the specified version. Use this endpoint over the base version detail when your integration needs app_file, app_icon, size_in_mb, or release_date without the overhead of iterating through a list.\n\n**About Get App Version (V1)**\n\nThe V1 version detail endpoint returns the same core version metadata as GET .../application/{application_id}/version/{version_id}/ but uses the AppVersionV1 schema. Key additions over the base schema include: app_file (a direct URL to the APK binary), app_icon (a direct URL to the version's icon), size_in_mb (file size), and release_date. These additions are particularly useful for integrations that surface version detail in a UI or need to trigger downloads. Note that release_track and target_sdk_version from the base schema are absent in V1 — use the base endpoint if those fields are needed.\n\n**Key Fields**\n\napp_file — direct URL to download the APK binary for this version\n\napp_icon — direct URL to the version's app icon image\n\nsize_in_mb — file size of the APK in megabytes\n\nrelease_date — timestamp of when this version was released\n\nrelease_comments — freeform notes about this release\n\napproval_status — current lifecycle status: AVAILABLE, ACCEPTED, APPROVED, or REJECTED (defaults to APPROVED)\n\nis_default — whether this version is the designated default for the application (defaults to false)\n\ninstalled_count — number of devices with this version currently installed\n\n**Common Use Cases**\n\nRetrieve a direct APK download URL for a specific version without listing all versions.\n\nDisplay version detail (icon, size, release date, release comments) in a custom management UI.\n\nConfirm installed_count before deprecating or removing a version.\n\n**Best Practices**\n\nUse this endpoint instead of the base version detail when app_file, app_icon, or size_in_mb are needed — it avoids a redundant follow-up call.\n\nIf release_track or target_sdk_version are required, fall back to the base GET .../application/{application_id}/version/{version_id}/ endpoint.\n\nVerify approval_status=APPROVED and is_default=true or is_enabled (check base schema) before using this version in an install command.\n\n**Workflow**\n\nObtain the version_id from a V1 version list call or stored reference\n\nCall this endpoint to retrieve full V1 version detail including file and icon URLs\n\nUse app_file for download or display; confirm approval_status before referencing in an install command", "operationId": "getAppVersionV1", "parameters": [ { "name": "version_id", "in": "path", "description": "A UUID string identifying this app version.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "application_id", "in": "path", "description": "A UUID string identifying this application.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_AppVersionV1" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application V1" ], "summary": "Delete app version", "description": "Permanently removes a specific version of an enterprise application from Esper. If the target version is currently referenced by one or more blueprints, the version must be removed from the blueprint before the version can be deleted. If no blueprint references exist, the version is deleted outright and the endpoint returns HTTP 204.\n\nAbout Delete App Version\n\nEach application in Esper can have multiple uploaded versions, and individual versions can be removed without deleting the parent application. The blueprint authors must explicitly confirm intent to orphan those references.\n\nKey Fields / Query Parameters\n\nversion_id — UUID of the specific app version to delete; required path parameter\n\napplication_id — UUID of the parent application; required path parameter\n\nenterprise_id — UUID of the enterprise; required path parameter\n\nrequest_id — Query parameter; if a prior call returned a request_id (because the version is in use by blueprints), pass it here to confirm deletion and clear the cache entry\n\n**Common Use Cases**\n\nRemoving a recalled or defective APK version that should no longer be deployable.\nCleaning up old test builds or pre-release versions after a stable version is promoted.\nFreeing storage and reducing version clutter in the application library.\n\n**Best Practices**\n\nAlways check the response code on the first call — a 200 with a request_id body means the version is blueprint-referenced and requires a second confirmation call; a 204 means it was deleted immediately.\nAudit which blueprints reference the version before deleting to avoid breaking active device configurations.\nCoordinate with teams managing blueprints before removing versions that may be in production use.\n\n**Workflow**\n\nCall DELETE /api/v1/enterprise/{enterprise_id}/application/{application_id}/version/{version_id}/ with path parameters only.\nIf response is 204, deletion is complete — no further action needed.\nIf response is 200 with a request_id, resubmit the same request appending ?request_id={returned_id} to confirm the deletion.", "operationId": "deleteAppVersionV1", "parameters": [ { "name": "version_id", "in": "path", "description": "A UUID string identifying this app version.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "application_id", "in": "path", "description": "A UUID string identifying this application.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "request_id", "in": "query", "description": "If this value exists in cache, delete the application and cache entry.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "No request id is provided and the application is linked to one or more templates. Returns a request_id. Call with this request id to delete the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_AppVersionDelete" } } } }, "204": { "description": "The resource was deleted successfully." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] }, "patch": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application V1" ], "summary": "Patch an App version instance", "description": "Partially updates the metadata of a specific application version without modifying its APK or binary content.Use this endpoint to update human-readable labels. Only the fields included in the request body are modified; omitted fields remain unchanged.\n\nAbout Patch App Version\n\nApplication versions in Esper carry both technical metadata (version code, minimum SDK, build number) and management metadata (release name, default flag, approval status). The PATCH operation enables targeted updates to either set without re-uploading the binary.\n\nKey Fields / Query Parameters\n\nrelease_name — Human-readable label for this version (e.g., \"Q2 Release - Stable\")\n\n\n**Common Use Cases**\n\nUpdating a version description\n\n**Best Practices**\n\nUse version description such as PROD or DEV to differentiate between production and development builds\n\n**Workflow**\n\nRetrieve the current version details using GET /api/v1/enterprise/{enterprise_id}/application/{application_id}/version/{version_id}/ to confirm current field values.\nConstruct a PATCH request body with only the fields to update.\nSubmit the request and confirm the returned AppVersionV1 object reflects the expected changes.", "operationId": "patchAppVersionV1", "parameters": [ { "name": "version_id", "in": "path", "description": "A UUID string identifying this app version.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "application_id", "in": "path", "description": "A UUID string identifying this application.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "*/*": { "schema": { "type": "object", "properties": { "release_name": { "title": "Release name", "type": "string", "description": "Name of the Release" }, "is_default": { "title": "Is Default", "type": "boolean", "description": "Is the app version the default" }, "min_sdk_version": { "title": "Minimum SDK version", "type": "string", "description": "Version number of minimum SDK version that supports this app version" }, "build_number": { "title": "Build Number", "type": "string", "description": "Build number of this app version" }, "version_code": { "title": "Version Code", "type": "string", "description": "Version code of this app version" }, "approval_status": { "title": "Approval Status", "type": "string", "description": "Approval status of this app version", "enum": [ "AVAILABLE", "ACCEPTED", "APPROVED", "REJECTED" ] } } } } }, "required": false }, "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_AppVersionV1" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ], "x-codegen-request-body-name": "data" } }, "/v1/enterprise/{enterprise_id}/application/{application_id}/version/{version_id}/installdevices": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Application V1" ], "summary": "List install devices", "description": "Returns a paginated list of devices that have a specific Android application version installed.\n\nUse this endpoint to audit the install coverage of a particular app version across your fleet, searchable by device name, alias, or group name.\n\nAbout List Install Devices\n\nThis endpoint is part of the Application V1 family, which manages the enterprise's Android app library. It answers the question \"which devices have version X of this Android app installed?\" for a specific application_id and version_id pair. Each result is an InstallDevices object containing the device UUID, device name, alias name, and group name — enough context to identify and locate devices without a separate device lookup.\nThere are two other application API families with distinct scopes:\n\nTenant Apps (/v2/tenant-apps/...) — manages uploaded apps for iOS and Windows. This family does not have a device-level install query endpoint.\nDevice Apps (/v2/devices/{deviceId}/device-apps/ and GET /v2/device-apps) — is the correct family for install queries involving iOS and Windows app types (VPP, TENANT_IOS, ESPER_IOS, WEBCLIP, ESPER_WINDOWS, TENANT_WINDOWS). Use GET /v2/device-apps?app_id=...&app_version_id=... for the equivalent cross-device install query on non-Android apps.\n\nFor Android apps, this endpoint is the right tool. Results are paginated; use limit and offset to page through large fleets.\n\nKey Fields\n\nenterprise_id (path, required) — UUID of the enterprise\n\napplication_id (path, required) — UUID of the Android application\n\nversion_id (path, required) — UUID of the specific app version to query\n\nsearch (optional) — Free-text search across device name, alias name, and group name\n\nlimit (optional) — Number of results per page\n\noffset (optional) — Starting index for pagination\n\nid (response) — UUID of the device\n\ndevice_name — System-assigned device name\n\nalias_name — Human-friendly alias for the device; may be null\n\ngroup_name — Name of the device group the device belongs to\n\n**Common Use Cases**\n\nVerifying that an Android app deployment reached all intended devices\nIdentifying which devices still have an outdated version installed before pushing an update\nAuditing install coverage before deleting an app version to confirm no devices will be left in an unexpected state\n\n**Best Practices**\n\nFor iOS or Windows app install queries, use GET /v2/device-apps?app_id=...&app_version_id=... from the Device Apps family instead — this endpoint covers Android only\nRun this query per version before calling the application or version-level delete endpoint to avoid removing a version still in active use\nUse search to narrow results to a specific group or device without paginating through the entire fleet\nCross-reference group_name with your intended deployment targets to catch devices in unexpected groups\n\n**Workflow**\n\nObtain application_id from GET /v1/enterprise/{enterprise_id}/application/ and version_id from GET /v1/enterprise/{enterprise_id}/application/{application_id}/version/\nCall GET .../version/{version_id}/installdevices, optionally with search and pagination params\nPaginate through results until next is null\nUse the device UUIDs (id) or group_name to identify devices for follow-up actions such as issuing an update command or flagging stragglers", "operationId": "getInstallDevicesV1", "parameters": [ { "name": "version_id", "in": "path", "description": "A UUID string identifying this app version.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "application_id", "in": "path", "description": "A UUID string identifying this application.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enterprise_id", "in": "path", "description": "A UUID string identifying enterprise.", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "A search term, search based on device name, device alias_name, group name", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "The initial index from which to return the results", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "format": "url", "nullable": true }, "previous": { "type": "string", "format": "url", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_InstallDevices" } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/v1/token-info/": { "get": { "x-badges": [ { "name": "Deprecated", "color": "red" } ], "tags": [ "esper_cloud_api_Token (Deprecated)" ], "summary": "Token Information", "description": "Returns the enterprise, user, and other resource information associated with your API token.\n\n⚠️ **Deprecation Notice:** This endpoint is deprecated. To confirm the user and enterprise bound to your credentials, use `GET /user_info/`.\n", "operationId": "getTokenInfo", "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_TokenInfoV1" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } }, "security": [ { "esper_cloud_api_apiKey": [] } ] } }, "/user_info/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_User" ], "summary": "User information", "description": "Retrieves the profile and account details of the authenticated user associated with the current API key.\n\nUse this endpoint to confirm which user identity is bound to your API credentials — useful for debugging access issues, verifying role assignments, or bootstrapping workflows that need to know the acting user's context before proceeding.\n\n**About Get User Info**\nEvery Esper API key is tied to a specific user account within a tenant. This endpoint surfaces that user's full profile, including their role, group memberships, EMM linkage, and account status. It requires no path parameters — the response is scoped entirely to the authenticated caller. This is the canonical way to confirm \"who am I?\" in the Esper API context.\n\nKey Fields\n\nusername — the login identifier for this user\n\nprofile.role — the user's assigned role (e.g., Enterprise Admin, Viewer, Group Admin)\n\nprofile.enterprise — the enterprise UUID this user belongs to\n\nemm — linked EMM account details, if applicable\n\nis_active — whether this user account is currently enabled\n\nlast_login — timestamp of the most recent authenticated session\n\n**Common Use Cases**\n\nConfirming which user identity is in use before executing sensitive operations\n\nRetrieving the caller's enterprise ID for use in subsequent API calls\n\nAuditing role assignments for an API key owner\n\n**Best Practices**\n\nCall this endpoint at the start of integrations to validate API key identity and capture the enterprise ID, rather than hardcoding it\n\nCheck is_active to ensure the account hasn't been deactivated before proceeding with bulk operations\n\nUse profile.role to conditionally adapt your integration's behavior based on permission level\n\n**Workflow**\n\nAuthenticate with your API key\n\nCall GET /user_info/ to retrieve the caller's identity, enterprise ID, and role\n\nStore profile.enterprise for use as enterprise_id in downstream API calls\n", "operationId": "userInfo", "security": [ { "esper_cloud_api_apiKey": [] } ], "responses": { "200": { "description": "User Info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_User" } } } }, "401": { "description": "Authorization information is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } } } }, "/authn2/v0/tenant/{enterprise_id}/invite": { "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_User" ], "summary": "Invite a user", "description": "Sends an invitation email to a new user, provisioning their role and group access within the specified tenant before they have an Esper account.\n\nUse this endpoint to onboard new team members to an Esper enterprise programmatically — the invite flow handles identity provider registration via the connection_id and assigns the user's role and group scope in a single step.\n\nAbout Invite a User\n\nEsper's invite system separates access provisioning from account creation. When you call this endpoint, Esper generates an invitation record in the tenant and can optionally trigger an invitation email via the identity provider. The invited user receives a link to complete registration; upon acceptance, their account is created with the role and group access defined in the meta.profile block. This is the recommended way to add users to a tenant in preference to direct user creation.\n\n**Key Fields / Request Body**\n\nemail — (required) the email address of the person being invited\n\nmeta.profile.role — (required) the role to assign: Enterprise Admin, Viewer, Group Admin, Group Viewer, or AuthZ Role User. Use AuthZ Role User when assigning a custom RBAC role defined in Esper's authorization service — this role type enables fine-grained scope control tied to a specific authz_role_id\n\nmeta.profile.enterprise — (required) the tenant UUID; must match enterprise_id in the path\n\nmeta.profile.groups — list of group UUIDs to scope access; required for Group Admin and Group Viewer roles\n\nmeta.profile.authz_role_id — UUID of the custom RBAC role to assign; required when role is AuthZ Role User. This binds the user to a specific scope set managed by Esper's AuthZ service, allowing more granular access control than the built-in fixed roles\n\nconnection_id — the identity provider connection to use for the invite flow\n\ninvitation_url — returned in the response; the link the user follows to complete registration\n\n**Common Use Cases**\n\nOnboarding a new IT admin or support engineer to a tenant\n\nGranting a new Group Admin scoped access to a specific device group\n\nAutomating user provisioning workflows where users are invited in bulk from an HR or directory system\n\n**Best Practices**\n\nAlways set meta.profile.groups when the role is Group Admin or Group Viewer — the invite will be created but access will be undefined without it\n\nValidate that meta.profile.enterprise matches the enterprise_id path parameter before submitting\n\nStore the returned id (invite ID) immediately; you will need it to cancel the invite via DELETE /authn2/v0/tenant/{enterprise_id}/invite/{invite_id} if the user shouldn't have been invited\n\nUse GET /authn2/v0/tenant/{enterprise_id}/invite to check whether a pending invite for an email already exists before re-sending\n\n**Workflow**\n\nDetermine the new user's email, intended role, and group scope\n\nPOST to this endpoint with the meta.profile block fully populated\n\nStore the returned invite id for auditing or future cancellation\n\nThe user receives an email and follows the invitation_url to complete account creation\n", "operationId": "tenantUserInvite", "security": [ { "esper_cloud_api_apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_TenantUserInviteRequest" } } } }, "responses": { "201": { "description": "Invite sent to user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_TenantUserInviteCreateResponse" } } } }, "400": { "description": "tenant user invite create error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } } } }, "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_User" ], "summary": "List user invites", "description": "Returns all pending user invitations for the specified tenant, including each invite's status, metadata, and assigned role.\n\nUse this endpoint to audit outstanding invitations, detect stale or duplicate invites, or build an admin UI that surfaces which users have been invited but have not yet completed registration.\n\n**About List User Invites**\n\nWhen a user is invited via POST /authn2/v0/tenant/{enterprise_id}/invite, an invite record is created and persists until the user accepts it or it is explicitly deleted. This endpoint returns the full list of those records for the tenant, including the role and group assignments encoded in the meta field, the associated identity provider invite ID (idp_invite_id), and timestamps. The response structure wraps results in a userinvites array alongside a count field.\n\n**Key Fields (Response)**\n\nid — the Esper invite UUID; use this with the DELETE endpoint to cancel an invite\n\nemail — the email address the invite was sent to\n\nmeta — the role and group assignment payload set at invite creation time, including any custom RBAC role binding\n\nidp_invite_id — the identity provider's reference ID for this invite\n\nsend_invitation_email — whether an email was triggered for this invite\n\ncreated_at / updated_at — timestamps for tracking invite age\n\n**Common Use Cases**\n\nAuditing which users have pending (unaccepted) invitations\n\nIdentifying and cleaning up stale invites before re-inviting a user\n\nBuilding an admin console view of the invite queue\n\n**Best Practices**\n\nCross-reference email values against your user directory to identify invites sent to addresses that have since changed\n\nUse created_at to flag invites that have been pending longer than your organization's acceptable window, then cancel and re-invite as needed\n\nCheck this endpoint before calling POST .../invite to avoid duplicate invitations to the same email\n\n**Workflow**\n\nCall GET /authn2/v0/tenant/{enterprise_id}/invite to retrieve all pending invites\n\nReview the userinvites array for emails, roles, and invite age\n\nFor any stale or incorrect invites, note the id and call DELETE /authn2/v0/tenant/{enterprise_id}/invite/{invite_id} to cancel\n", "operationId": "getTenantUserInvites", "security": [ { "esper_cloud_api_apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" } ], "responses": { "201": { "description": "Tenant user invites", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "userinvites": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_TenantUserInviteResponse" } } } } } } }, "400": { "description": "List tenant user invites error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } } } } }, "/authn2/v0/tenant/{enterprise_id}/invite/{invite_id}": { "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_User" ], "summary": "Delete an invite", "description": "Cancels and removes a specific pending user invitation from the tenant, preventing the invited user from completing registration with that invite link.\n\nUse this endpoint when an invitation was sent in error, the intended recipient's role or email has changed, or the invite has expired and needs to be reissued.\n\n**About Delete a User Invite**\nInvite records in Esper remain active until the user accepts them or they are explicitly deleted. User invitations are valid for seven days — after that window, the invite link expires and the user must be re-invited. Deleting an invite does not remove or affect any existing user account — it only invalidates the pending invite record and its associated identity provider invitation. Once deleted, the invitation_url from the original invite will no longer be valid. Returns HTTP 204 on success with no response body.\n\n**Key Parameters**\n\nenterprise_id — the UUID of the tenant the invite belongs to\n\ninvite_id — the UUID of the invite record to cancel, obtained from POST /authn2/v0/tenant/{enterprise_id}/invite (create response) or GET /authn2/v0/tenant/{enterprise_id}/invite (list)\n\n**Common Use Cases**\n\nRevoking an invitation sent to the wrong email address\n\nClearing expired or stale invites before re-issuing a fresh invitation with updated role or group assignments\n\nCleaning up the invite queue as part of periodic tenant access audits\n\n**Best Practices**\n\nAlways retrieve the invite_id from the list endpoint (GET .../invite) rather than storing it externally, to ensure you're targeting the correct and current record\n\nUse created_at from the list response to identify invites approaching or past the 7-day expiry window — delete and re-invite rather than waiting for the user to report a broken link\n\nAfter deletion, re-invite the user immediately if access is still intended — the previous invitation_url is no longer valid\n\nIf the re-invite requires a different role, including switching to or from AuthZ Role User, prepare the correct authz_role_id before calling the invite endpoint again\n\nConfirm deletion success via the 204 response before notifying stakeholders that the invite has been revoked\n\n**Workflow**\n\nCall GET /authn2/v0/tenant/{enterprise_id}/invite to identify the target invite and retrieve its id\n\nCall DELETE /authn2/v0/tenant/{enterprise_id}/invite/{invite_id} with the correct invite_id\n\nConfirm the 204 response indicating successful deletion\n\nRe-invite the user via POST /authn2/v0/tenant/{enterprise_id}/invite if access is still required\n", "operationId": "deleteTenantUserInvite", "security": [ { "esper_cloud_api_apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" }, { "$ref": "#/components/parameters/esper_cloud_api_InviteID" } ], "responses": { "204": { "description": "Deleted tenant user invite" }, "400": { "description": "Tenant user invite delete error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } } } } }, "/user/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_User" ], "summary": "Get Users", "description": "Returns a paginated list of all users in the tenant, including their profile details, role assignments, and account status.\n\nUse this endpoint to enumerate current tenant members, audit role distributions, or build user-management tooling on top of the Esper platform.\n\n**About Get Users**\n\nThis endpoint retrieves the full set of user records within the authenticated enterprise, returning each user's name, email, role, group memberships, active status, and EMM linkage. Results are paginated with count, next, and previous fields for traversal. Note that POST /user/ (user creation at this same path) is tagged User (Deprecated) — for adding new users, use the invite flow via POST /authn2/v0/tenant/{enterprise_id}/invite instead.\n\n**Key Fields (Response)**\n\nid — integer ID for the user record\n\nusername — the user's login identifier\n\nemail — the user's email address\n\nprofile.role — assigned role within the enterprise (Enterprise Admin, Viewer, Group Admin, Group Viewer, or AuthZ Role User for custom RBAC assignments)\n\nprofile.groups — group UUIDs the user has access to\n\nis_active — whether the account is currently enabled\n\nlast_login — most recent authenticated session timestamp\n\nhas_emm — whether the user has an associated EMM account\n\n**Common Use Cases**\n\nAuditing all users and their role assignments across a tenant\n\nIdentifying inactive accounts (is_active: false) for deprovisioning\n\nMapping user IDs to usernames for use in other API calls (e.g., event logs, audit records)\n\n**Best Practices**\n\nUse this endpoint for read-only enumeration; use the invite endpoint (POST /authn2/v0/tenant/{enterprise_id}/invite) to add new users rather than the deprecated POST /user/\n\nPaginate through next links when the tenant has a large number of users rather than assuming all users appear in the first response\n\nFor users with profile.role of AuthZ Role User, their effective permissions are governed by their custom RBAC scope rather than the fixed role set — account for this when building access audits\n\n**Workflow**\n\nCall GET /user/ to retrieve the first page of tenant users\n\nFollow the next URL in the response until next is null to retrieve all users\n\nInspect each user's profile.role, is_active, and last_login for access auditing or downstream processing\n", "operationId": "getUsers", "security": [ { "esper_cloud_api_apiKey": [] } ], "responses": { "200": { "description": "Users List", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_UserList" } } } } } } }, "401": { "description": "Authorization information is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } } }, "post": { "x-badges": [ { "name": "Deprecated", "color": "red" } ], "tags": [ "esper_cloud_api_User (Deprecated)" ], "summary": "Create a new User", "description": "Creates a new user in the enterprise.\n\n⚠️ **Deprecation Notice:** This endpoint is deprecated. To add a user, invite them with `POST /authn2/v0/tenant/{enterprise_id}/invite`.\n", "operationId": "createUser", "security": [ { "esper_cloud_api_apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_UserCreate" } } } }, "responses": { "201": { "description": "User Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_User" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } } } }, "/user/{user_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_User" ], "summary": "Get User Information", "description": "Retrieves the full profile and account details for a specific user by their integer user ID.\n\nUse this endpoint to look up an individual tenant member's role, group assignments, account status, and EMM linkage without fetching the full user list.\n\n**About Get User Information**\n\nThis endpoint returns a single user record from the authenticated enterprise, identified by their integer user_id. The response uses the same User schema returned by GET /user/, covering identity, role, group memberships, active status, and EMM association. Note that other methods at this path — PUT, PATCH, and DELETE — are tagged User (Deprecated); for updating a user's role use PUT /authz2/v1/users/{user_id}, and for removing a user use DELETE /authn2/v0/tenant/{enterprise_id}/user/{user_id}/.\n\n**Key Fields (Response)**\n\nid — the integer user ID (matches the path parameter)\n\nusername — the user's login identifier\n\nemail — the user's email address\n\nprofile.role — assigned role within the enterprise (Enterprise Admin, Viewer, Group Admin, Group Viewer, or AuthZ Role User for custom RBAC assignments)\n\nprofile.groups — group UUIDs the user has access to\n\nis_active — whether the account is currently enabled\n\nlast_login — most recent authenticated session timestamp\n\nhas_emm — whether the user has an associated EMM account\n\nis_email_verified — whether the user has completed email verification\n\n**Common Use Cases**\n\nLooking up a specific user's role and group scope before modifying their access\n\nVerifying account status (is_active, is_email_verified) for a user who is reporting access problems\n\nRetrieving a user's EMM linkage details for troubleshooting enrollment issues\n\n**Best Practices**\n\nObtain user_id from GET /user/ — it is an integer, distinct from the UUID-format authn_user_id used by other endpoints such as DELETE /authn2/v0/tenant/{enterprise_id}/user/{user_id}/\n\nFor users with profile.role of AuthZ Role User, their effective permissions are governed by their custom RBAC scope — check their role assignment via GET /authz2/v1/users/{user_id}/groups for a complete picture of their access\n\nUse GET /user_info/ instead if you need details about the currently authenticated caller rather than a specific user by ID\n\n**Workflow**\n\nCall GET /user/ to enumerate tenant users and identify the target user's integer id\n\nCall GET /user/{user_id}/ with that id to retrieve the full user record\n\nInspect profile.role, is_active, and is_email_verified for the information needed\n", "operationId": "getUser", "security": [ { "esper_cloud_api_apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_UserID" } ], "responses": { "200": { "description": "User Details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_User" } } } }, "401": { "description": "Authorization information is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } } }, "put": { "x-badges": [ { "name": "Deprecated", "color": "red" } ], "tags": [ "esper_cloud_api_User (Deprecated)" ], "summary": "Update a User", "description": "Updates a user.\n\n⚠️ **Deprecation Notice:** This endpoint is deprecated. To change a user's role or group access, use `PUT /authz2/v1/users/{user_id}`. To update profile details, use `PUT /authn2/v0/user/{user_id}`. Both expect the UUID `authn_user_id` from `GET /authn2/v1/users/`, not the integer `id` from `GET /user/`.\n", "operationId": "updateUser", "security": [ { "esper_cloud_api_apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_UserID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_UserCreate" } } } }, "responses": { "200": { "description": "Updated User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_User" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } } }, "patch": { "x-badges": [ { "name": "Deprecated", "color": "red" } ], "tags": [ "esper_cloud_api_User (Deprecated)" ], "summary": "Partial update a User", "description": "Partially updates a user.\n\n⚠️ **Deprecation Notice:** This endpoint is deprecated. To change a user's role or group access, use `PUT /authz2/v1/users/{user_id}`. To update profile details, use `PUT /authn2/v0/user/{user_id}`. Both expect the UUID `authn_user_id` from `GET /authn2/v1/users/`, not the integer `id` from `GET /user/`.\n", "operationId": "partialUpdateUser", "security": [ { "esper_cloud_api_apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_UserID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_UserUpdate" } } } }, "responses": { "200": { "description": "Partial updated User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_User" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Authorization information is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } } }, "delete": { "x-badges": [ { "name": "Deprecated", "color": "red" } ], "tags": [ "esper_cloud_api_User (Deprecated)" ], "summary": "Delete a user", "description": "Deletes a user.\n\n⚠️ **Deprecation Notice:** This endpoint is deprecated. To remove a user from the enterprise, use `DELETE /authn2/v0/tenant/{enterprise_id}/user/{user_id}/`. It expects the UUID `authn_user_id` from `GET /authn2/v1/users/`, not the integer `id` from `GET /user/`.\n", "operationId": "userDelete", "security": [ { "esper_cloud_api_apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_UserID" } ], "responses": { "204": { "description": "Deleted User" }, "401": { "description": "Authorization information is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } } } }, "/authz2/v1/users/{user_id}": { "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_User" ], "summary": "Update user role", "description": "Updates the role, group assignments, and access scope for a specific user within the tenant.\n\nUse this endpoint when a user's responsibilities change and their permissions need to be adjusted — including switching between fixed roles, scoping group access, or assigning a custom RBAC role via AuthZ Role User.\n\nAbout Update User Role\nThis is the current, supported endpoint for modifying another user's role and access within Esper. It operates on the authn_user_id (UUID format), which is distinct from the integer id returned by GET /user/ — use GET /authn2/v1/users/ to retrieve the correct UUID. The request replaces the user's current role and group assignment in full; partial updates are not supported. Returns the updated User object on success.\n**Key Fields / Request Body**\n\nrole — (required) the role to assign: Enterprise Admin, Viewer, Group Admin, Group Viewer, or AuthZ Role User\n\ngroups — (required) list of group UUIDs to scope access; can be empty if has_all_group_access is true or the role does not require group scoping\n\nauthz_role_id — UUID of the custom RBAC role; required when role is AuthZ Role User\n\nhas_all_group_access — set to true to grant access to all groups; required only for AuthZ Role User role type\n\ncan_factory_reset — whether the user should be permitted to factory reset devices\n\n**Common Use Cases**\n\nPromoting a Viewer to Enterprise Admin after a role change\n\nScoping a user to specific device groups by switching them to Group Admin or Group Viewer\n\nAssigning a custom RBAC role for fine-grained permission control\n\nRevoking broad access by narrowing a user's group list\n\n**Best Practices**\n\nUse GET /authn2/v1/users/ to retrieve the user's UUID (authn_user_id) before calling this endpoint — the integer id from GET /user/ will not work here\n\nWhen setting role to AuthZ Role User, always provide both authz_role_id and either a populated groups list or has_all_group_access: true\n\nTreat this as a full replacement of the user's role record — always include all intended group assignments in a single call rather than assuming previous values are preserved\n\n**Workflow**\n\nCall GET /authn2/v1/users/ to retrieve the target user's UUID (authn_user_id)\n\nDetermine the new role, group scope, and any custom RBAC role ID\n\nPUT to this endpoint with the fully populated request body\n\nConfirm the updated role and group assignments in the returned User object\n", "operationId": "updateDifferentUser", "security": [ { "esper_cloud_api_apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_AuthNUserID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_UpdateDifferentUserRequest" } } } }, "responses": { "200": { "description": "User Updated Successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_User" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } } } } }, "/authn2/v0/user/{user_id}": { "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_User" ], "summary": "Update user profile", "description": "Updates the authenticated user's own profile details.\n\nUse this endpoint when the currently authenticated user needs to update their own display name. This endpoint is scoped to self-service profile edits only and cannot be used to modify another user's account or change role and group assignments.\nAbout Update User Profile\nThis endpoint allows a user to update their own profile via the authn2 identity service. The request body accepts only first_name — role changes, group reassignments, and other administrative updates must be performed by an Enterprise Admin via PUT /authz2/v1/users/{user_id}. The user_id parameter expects the UUID-format authn_user_id, not the integer id from GET /user/.\n**Key Fields / Request Body**\n\nfirst_name — (required) the updated first name for the authenticated user\n\n**Common Use Cases**\n\nAllowing a user to correct or update their display name after account creation\n\n**Best Practices**\n\nUse GET /user_info/ to confirm the current user's authn_user_id before calling this endpoint\n\nFor role or group changes, use PUT /authz2/v1/users/{user_id} — this endpoint cannot modify access permissions\n\n**Workflow**\n\nCall GET /user_info/ to retrieve the authenticated user's authn_user_id\n\nPUT to this endpoint with the updated first_name\n\nConfirm the change in the returned User object\n", "operationId": "updateOwnUser", "security": [ { "esper_cloud_api_apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" }, { "$ref": "#/components/parameters/esper_cloud_api_AuthNUserID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_UpdateOwnUserRequest" } } } }, "responses": { "200": { "description": "User Updated Successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_User" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } } } } }, "/authz2/v1/users/{user_id}/groups": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_User" ], "summary": "Get user groups", "description": "Returns the device groups a specific user has access to, based on their role and group assignments.\n\nUse this endpoint to audit a user's group-level access scope, or to determine which subgroups they can reach before assigning device commands or bulk operations.\n\n**About Get User Groups**\n\nThis endpoint retrieves the group membership for a given user from Esper's authorization service, returning a list of group UUIDs and a flag indicating whether the user has access to all groups in the tenant. The user_id parameter expects the UUID-format authn_user_id. The optional sub_groups query parameter expands the response to include subgroups the user can reach through their group assignments, since users with access to a parent group automatically have access to its subgroups.\n\n**Key Fields**\n\nuser_id — the UUID-format authn_user_id of the target user; obtain from GET /authn2/v1/users/\n\nsub_groups — (query param, boolean) set to true to include subgroup access in the response\n\ngroup_ids — returned array of group UUIDs the user has access to\n\nhas_all_group_access — if true, the user has access to all tenant groups regardless of the group_ids list\n\n**Common Use Cases**\n\nAuditing which device groups a user can manage before issuing group-level commands\n\nVerifying group scope for AuthZ Role User accounts where access is controlled by a custom RBAC role\n\nConfirming subgroup access inheritance when planning nested group structures\n\n**Best Practices**\n\nUse GET /authn2/v1/users/ to retrieve the target user's authn_user_id (UUID) before calling this endpoint — the integer id from GET /user/ will not work\n\nAlways call with sub_groups=true when you need a complete picture of a user's reachable device scope, not just their directly assigned groups\n\nIf has_all_group_access is true, the group_ids list is not the full scope — the user can access every group in the tenant\n\n**Workflow**\n\nCall GET /authn2/v1/users/ to retrieve the target user's authn_user_id\n\nCall GET /authz2/v1/users/{user_id}/groups with sub_groups=true if subgroup access is relevant\n\nInspect group_ids and has_all_group_access to determine the user's full device group scope\n", "operationId": "getUserGroups", "security": [ { "esper_cloud_api_apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_AuthNUserID" }, { "in": "query", "name": "sub_groups", "description": "Set to true to get a list of the user’s subgroup access. Users have access to their group’s subgroups.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "User Groups", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_UserGroups" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } } } } }, "/authn2/v0/tenant/{enterprise_id}/user/{user_id}/": { "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_User" ], "summary": "Delete a user from Enterprise", "description": "Removes a specific user from the tenant, revoking their access to all Esper resources within that enterprise.\n\nUse this endpoint to deprovision a user when they leave the organization, change roles outside the tenant, or have their access revoked as part of an access audit.\nAbout Delete a User from Enterprise\nThis is the current, supported endpoint for removing a user from an Esper tenant. It operates on the authn_user_id (UUID format) rather than the integer id — use GET /authn2/v1/users/ to retrieve the correct identifier. Deletion is immediate and permanent; the user will lose all access to the enterprise upon removal. Returns HTTP 204 on success with no response body. This endpoint replaces the deprecated DELETE /user/{user_id}/.\n\n**Key Parameters**\n\nenterprise_id — the UUID of the tenant to remove the user from\n\nuser_id — the UUID-format authn_user_id of the user to remove; obtain from GET /authn2/v1/users/\n\n**Common Use Cases**\n\nOffboarding a team member who has left the organization\n\nRemoving a user whose access was granted in error\n\nCleaning up inactive or unverified accounts as part of a periodic access audit\n\n**Best Practices**\n\nUse GET /authn2/v1/users/ to confirm the correct authn_user_id before calling — deleting the wrong user is not reversible\n\nVerify the user has no active device operations or pending commands in flight before removing them\n\nIf the user should retain access in a reduced capacity rather than being fully removed, use PUT /authz2/v1/users/{user_id} to downgrade their role instead\n\n**Workflow**\n\nCall GET /authn2/v1/users/ to retrieve the target user's authn_user_id\n\nCall DELETE /authn2/v0/tenant/{enterprise_id}/user/{user_id}/ with the correct UUIDs\n\nConfirm the 204 response indicating successful removal\n\nIf re-access is needed in future, re-invite the user via POST /authn2/v0/tenant/{enterprise_id}/invite\n", "operationId": "deleteTenantUser", "security": [ { "esper_cloud_api_apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" }, { "$ref": "#/components/parameters/esper_cloud_api_AuthNUserID" } ], "responses": { "204": { "description": "Deleted enterprise user" }, "400": { "description": "Enterprise user delete error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } } } } }, "/enterprise/{enterprise_id}/devicegroup/{group_id}/blueprint/": { "get": { "x-badges": [ { "name": "Deprecated", "color": "red" } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" }, { "$ref": "#/components/parameters/esper_cloud_api_GroupID" }, { "in": "query", "name": "without_details", "schema": { "type": "boolean" } } ], "tags": [ "esper_cloud_api_Blueprint (Deprecated)" ], "summary": "Get list of Blueprints for the group", "description": "Return list of Blueprint instances for the group.\n\n⚠️ **Deprecation Notice:** This endpoint will soon be deprecated. Use [Blueprints API](https://api.esper.io/tag/Blueprints-API) instead.\n", "operationId": "listBlueprint", "security": [ { "esper_cloud_api_apiKey": [] } ], "responses": { "200": { "description": "Blueprint detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string" }, "previous": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_Blueprint" } } } } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } } }, "post": { "x-badges": [ { "name": "Deprecated", "color": "red" } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" }, { "$ref": "#/components/parameters/esper_cloud_api_GroupID" }, { "in": "query", "name": "without_details", "schema": { "type": "boolean" } } ], "tags": [ "esper_cloud_api_Blueprint (Deprecated)" ], "summary": "Create a Blueprint", "description": "Returns the created Blueprint instance.\n\n⚠️ **Deprecation Notice:** This endpoint will soon be deprecated. Use [Blueprints API](https://api.esper.io/tag/Blueprints-API) instead.\n", "operationId": "createBlueprint", "security": [ { "esper_cloud_api_apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Blueprint" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Blueprint" } } } }, "400": { "description": "Blueprint create error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Blueprint create error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } } } }, "/enterprise/{enterprise_id}/devicegroup/{group_id}/blueprint/{blueprint_id}/": { "get": { "x-badges": [ { "name": "Deprecated", "color": "red" } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" }, { "$ref": "#/components/parameters/esper_cloud_api_GroupID" }, { "$ref": "#/components/parameters/esper_cloud_api_BlueprintID" }, { "in": "query", "name": "without_details", "schema": { "type": "boolean" } } ], "tags": [ "esper_cloud_api_Blueprint (Deprecated)" ], "summary": "Get Blueprint detail", "description": "Returns the details of a Blueprint instance.\n\n⚠️ **Deprecation Notice:** This endpoint will soon be deprecated. Use [Blueprints API](https://api.esper.io/tag/Blueprints-API) instead.\n", "operationId": "getBlueprint", "security": [ { "esper_cloud_api_apiKey": [] } ], "responses": { "200": { "description": "Blueprint detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Blueprint" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } } }, "patch": { "x-badges": [ { "name": "Deprecated", "color": "red" } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" }, { "$ref": "#/components/parameters/esper_cloud_api_GroupID" }, { "$ref": "#/components/parameters/esper_cloud_api_BlueprintID" }, { "in": "query", "name": "without_details", "schema": { "type": "boolean" } } ], "tags": [ "esper_cloud_api_Blueprint (Deprecated)" ], "summary": "Partial update a Blueprint", "description": "Returns the details of the updated Blueprint instance.\n\n⚠️ **Deprecation Notice:** This endpoint will soon be deprecated. Use [Blueprints API](https://api.esper.io/tag/Blueprints-API) instead.\n", "operationId": "partialUpdateBlueprint", "security": [ { "esper_cloud_api_apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Blueprint" } } } }, "responses": { "200": { "description": "Partially updated Blueprint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Blueprint" } } } }, "400": { "description": "Blueprint update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Blueprint update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } } }, "delete": { "x-badges": [ { "name": "Deprecated", "color": "red" } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" }, { "$ref": "#/components/parameters/esper_cloud_api_GroupID" }, { "$ref": "#/components/parameters/esper_cloud_api_BlueprintID" }, { "in": "query", "name": "without_details", "schema": { "type": "boolean" } } ], "tags": [ "esper_cloud_api_Blueprint (Deprecated)" ], "summary": "Delete a Blueprint", "description": "Deletes the requested Blueprint instance.\n\n⚠️ **Deprecation Notice:** This endpoint will soon be deprecated. Use [Blueprints API](https://api.esper.io/tag/Blueprints-API) instead.\n", "operationId": "deleteBlueprint", "security": [ { "esper_cloud_api_apiKey": [] } ], "responses": { "204": { "description": "Deleted Blueprint" }, "401": { "description": "Blueprint delete error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } } } }, "/enterprise/{enterprise_id}/devicegroup/{group_id}/blueprint/{blueprint_id}/revisions/": { "get": { "x-badges": [ { "name": "Deprecated", "color": "red" } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" }, { "$ref": "#/components/parameters/esper_cloud_api_GroupID" }, { "$ref": "#/components/parameters/esper_cloud_api_BlueprintID" }, { "in": "query", "name": "without_details", "schema": { "type": "boolean" } } ], "tags": [ "esper_cloud_api_Blueprint (Deprecated)" ], "summary": "Get list of Blueprint Revisions", "description": "Returns a list of Blueprint Revisions instances for the given Blueprint.\n\n⚠️ **Deprecation Notice:** This endpoint will soon be deprecated. Use [Blueprints API](https://api.esper.io/tag/Blueprints-API) instead.\n", "operationId": "listBlueprintRevisions", "security": [ { "esper_cloud_api_apiKey": [] } ], "responses": { "200": { "description": "Blueprint revision list", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string" }, "previous": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_BlueprintRevision" } } } } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } } } }, "/enterprise/{enterprise_id}/devicegroup/{group_id}/blueprint/{blueprint_id}/revisions/{revision_id}/": { "get": { "x-badges": [ { "name": "Deprecated", "color": "red" } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" }, { "$ref": "#/components/parameters/esper_cloud_api_GroupID" }, { "$ref": "#/components/parameters/esper_cloud_api_BlueprintID" }, { "$ref": "#/components/parameters/esper_cloud_api_BlueprintRevisionID" }, { "in": "query", "name": "without_details", "schema": { "type": "boolean" } } ], "tags": [ "esper_cloud_api_Blueprint (Deprecated)" ], "summary": "Get Blueprint Revision detail", "description": "Returns the detail of Blueprint Revision instance.\n\n⚠️ **Deprecation Notice:** This endpoint will soon be deprecated. Use [Blueprints API](https://api.esper.io/tag/Blueprints-API) instead.\n", "operationId": "getBlueprintRevision", "security": [ { "esper_cloud_api_apiKey": [] } ], "responses": { "200": { "description": "Blueprint revision detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_BlueprintRevision" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } } } }, "/enterprise/{enterprise_id}/devicegroup/{group_id}/blueprint/restore/": { "post": { "x-badges": [ { "name": "Deprecated", "color": "red" } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" }, { "$ref": "#/components/parameters/esper_cloud_api_GroupID" } ], "tags": [ "esper_cloud_api_Blueprint (Deprecated)" ], "summary": "Restore a Blueprint", "description": "Returns the Blueprint instance restored to the requested Blueprint Revision.\n\n⚠️ **Deprecation Notice:** This endpoint will soon be deprecated. Use [Blueprints API](https://api.esper.io/tag/Blueprints-API) instead.\n", "operationId": "restoreBlueprintRevision", "security": [ { "esper_cloud_api_apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revision_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "description": "Restored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Blueprint" } } } }, "400": { "description": "Blueprint restore error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Blueprint restore error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } } } }, "/enterprise/{enterprise_id}/devicegroup/{group_id}/blueprint/upload/": { "post": { "x-badges": [ { "name": "Deprecated", "color": "red" } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" }, { "$ref": "#/components/parameters/esper_cloud_api_GroupID" } ], "tags": [ "esper_cloud_api_Blueprint (Deprecated)" ], "summary": "Upload a Blueprint", "description": "Create a Blueprint by uploading a json file.\n\n⚠️ **Deprecation Notice:** This endpoint will soon be deprecated. Use [Blueprints API](https://api.esper.io/tag/Blueprints-API) instead.\n", "operationId": "uploadBlueprint", "security": [ { "esper_cloud_api_apiKey": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "Uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Blueprint" } } } }, "400": { "description": "Blueprint upload error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Blueprint upload error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } } } }, "/v1/enterprise/{enterprise_id}/directory_record/": { "get": { "x-badges": [ { "name": "Deprecated", "color": "red" } ], "tags": [ "esper_cloud_api_Directory Record" ], "summary": "Get all Directory Records", "description": "⚠️ **Deprecation Notice:** The following endpoint is deprecated. \n\nLists all Directory Record instances for an enterprise.\n\nReturns a paginated list (count/next/previous/results) of Directory Records, which are used for device registration and approval workflows before a device is fully onboarded.\n\n**About Directory Records**\n\nA Directory Record represents a device that has been identified for onboarding via a unique identifier (IMEI, serial number, MEI, or MAC address) before or during enrollment, tracking its approval status as it moves toward being provisioned. Each record can be linked to a device group and carries its own online status, alias, and tags.\n", "operationId": "getDirectoryRecords", "security": [ { "esper_cloud_api_apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" } ], "responses": { "200": { "description": "Directory records", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_DirectoryRecord" } } } } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } } }, "post": { "x-badges": [ { "name": "Deprecated", "color": "red" } ], "tags": [ "esper_cloud_api_Directory Record" ], "summary": "Create a new Directory Record", "description": "⚠️ **Deprecation Notice:** The following endpoint is deprecated. \n\nCreates a new Directory Record for an enterprise.\n\nRegisters a device ahead of enrollment by submitting its unique identifiers, and returns the created Directory Record instance including its assigned approval status.\n\n**About Directory Records**\n\nA Directory Record represents a device identified for onboarding, typically before it has completed enrollment, and is used to drive device registration/approval workflows. Creating one associates one or more unique identifiers with an optional device group, alias, and tags.\n", "operationId": "createDirectoryRecord", "security": [ { "esper_cloud_api_apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_DirectoryRecordCreate" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_DirectoryRecord" } } } }, "400": { "description": "Directory record create error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Directory record create error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } } } }, "/v1/enterprise/{enterprise_id}/directory_record/{directory_record_id}/": { "get": { "x-badges": [ { "name": "Deprecated", "color": "red" } ], "tags": [ "esper_cloud_api_Directory Record" ], "summary": "Get details about a Directory Record", "description": "⚠️ **Deprecation Notice:** The following endpoint is deprecated. \n\nRetrieves the details of a single Directory Record.\n\nReturns the full Directory Record instance for the given ID, including its approval status, unique identifiers, and linked device (if any).\n\n**About Directory Records**\n\nA Directory Record represents a device tracked through the registration/approval workflow ahead of or during enrollment. Once approved and enrolled, the record's device_id field links it to the corresponding device.\n", "operationId": "getDirectoryRecord", "security": [ { "esper_cloud_api_apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" }, { "$ref": "#/components/parameters/esper_cloud_api_DirectoryRecordID" } ], "responses": { "200": { "description": "Directory record information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_DirectoryRecord" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } } }, "put": { "x-badges": [ { "name": "Deprecated", "color": "red" } ], "tags": [ "esper_cloud_api_Directory Record" ], "summary": "Update a Directory Record", "description": "⚠️ **Deprecation Notice:** The following endpoint is deprecated. \n\nUpdates an existing Directory Record.\n\nReplaces the editable fields (unique identifiers, group assignment, alias, tags) on a Directory Record and returns the updated instance.\n\n**About Directory Records**\n\nA Directory Record tracks a device through the registration/approval workflow. Updating one is typically used to change its unique identifiers, reassign it to a different device group, or update its alias/tags — it does not directly change approval_status, which is system-managed.\n", "operationId": "updateDirectoryRecord", "security": [ { "esper_cloud_api_apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" }, { "$ref": "#/components/parameters/esper_cloud_api_DirectoryRecordID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_DirectoryRecordUpdate" } } } }, "responses": { "200": { "description": "Updated Directory Record Information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_DirectoryRecord" } } } }, "400": { "description": "Directory record update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } }, "401": { "description": "Directory record update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } } }, "delete": { "x-badges": [ { "name": "Deprecated", "color": "red" } ], "tags": [ "esper_cloud_api_Directory Record" ], "summary": "Delete a Directory Record", "description": "⚠️ **Deprecation Notice:** The following endpoint is deprecated. \n\nDeletes a specific Directory Record.\n\nPermanently removes the identified Directory Record from the enterprise; returns a 204 with no content on success.\n\n**About Directory Records**\n\nA Directory Record tracks a device through the registration/approval process ahead of or during enrollment. Deleting one removes that pending or historical registration entry — it does not, by itself, delete an already-enrolled device.\n", "operationId": "deleteDirectoryRecord", "security": [ { "esper_cloud_api_apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" }, { "$ref": "#/components/parameters/esper_cloud_api_DirectoryRecordID" } ], "responses": { "204": { "description": "Deleted Directory Record" }, "401": { "description": "Directory record delete error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } } } }, "/authn2/v0/tenant/{enterprise_id}/connection": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_SSO Connections" ], "summary": "List SSO connections", "description": "Lists the SSO connections configured for a tenant. Use it to see every SAML or OIDC identity provider connection set up for the enterprise, along with which one is marked as default.\n\nReturns a count and an array of connections, each with its connection ID and connection details (name, strategy, is_default). Supports filtering by is_default.\n\n**About SSO Connections**\n\nSSO connections let a tenant authenticate users through an external identity provider using SAML (samlp) or OIDC (oidc) rather than Esper's native login. A tenant can have multiple connections configured, with one designated as the default. [Learn more](https://help.esper.io/hc/en-us/articles/14266541959569-Introduction-to-User-Authentication).\n\n**Key Fields / Query Parameters**\n\n- is_default — optional query filter to return only the connection marked as default\n- strategy — indicates whether a connection is samlp (SAML) or oidc (OIDC)\n\n**Common Use Cases**\n\n- Auditing which identity providers are connected to a tenant\n- Looking up a connection_id before calling the edit-connection endpoint\nList SSO connections of a tenant. Learn more about SSO Connections.\n", "operationId": "getConnections", "security": [ { "esper_cloud_api_apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" }, { "$ref": "#/components/parameters/esper_cloud_api_IsDefault" } ], "responses": { "200": { "description": "Tenant connections", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "connections": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_CustomConnectionsListResponse" } } } } } } }, "400": { "description": "List custom connections error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } } } } }, "/authn2/v0/tenant/{enterprise_id}/connection/{connection_id}": { "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_SSO Connections" ], "summary": "Edit SSO connections", "description": "Updates an existing SSO connection for a tenant, identified by connection_id. Use it to change a connection's display name, strategy, or provider configuration (SAML or OIDC settings) after it's been created.\n\nRequires a full request body (display_name, strategy, and the strategy-specific config block); returns the updated connection, including its service provider ACS URL, entity ID, logout URL, and signing certificate link where applicable.\n\n**About SSO Connections**\n\nSSO connections let a tenant authenticate users through an external identity provider using SAML (samlp) or OIDC (oidc). Editing a connection updates the underlying provider configuration Esper uses to negotiate SSO logins for that tenant. [Learn more](https://help.esper.io/hc/en-us/articles/14266541959569-Introduction-to-User-Authentication).\n\n**Key Fields / Query Parameters**\n\n- strategy — samlp or oidc, determines which config fields apply\n- config.sign_in_url / config.x509_certificate — required for SAML connections\n- config.issuer_url / config.client_id — required for OIDC connections\n\n**Common Use Cases**\n\n- Rotating a SAML signing certificate or updating an OIDC client ID\n- Renaming a connection's display name\n\n**Best Practices**\n\n- Confirm which strategy (samlp vs oidc) the connection uses before submitting config fields, since each strategy requires different config properties\n", "operationId": "editCustomConnection", "security": [ { "esper_cloud_api_apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_EnterpriseID" }, { "$ref": "#/components/parameters/esper_cloud_api_ConnectionID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_CustomConnectionRequest" } } } }, "responses": { "200": { "description": "Updated connection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_CustomConnectionResponse" } } } }, "400": { "description": "custom connection update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "403": { "description": "Forbidden, no permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_ErrorResponse" } } } } } } }, "/authz2/v1/roles/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Roles" ], "summary": "List Roles API", "description": "Returns all custom RBAC roles defined for the tenant.\n\nUse this endpoint to enumerate available roles before assigning one to a user, or to audit the set of custom roles that have been created for fine-grained access control.\n\n**About List Roles**\n\nEsper's authorization service supports custom roles as an alternative to the built-in fixed roles. Each custom role has a name, description, and a set of scopes that define what actions users assigned to that role can perform. This endpoint returns all custom roles for the tenant as a roles array alongside a count field. Role IDs returned here are used with PUT /authz2/v1/users/{user_id} when assigning an AuthZ Role User and with the role detail and scopes endpoints for management.\n\n****Key Fields (Response)****\n\nid — the UUID of the role; used in all subsequent role management and user assignment calls\n\nname — the display name of the role\n\ndescription — a human-readable description of the role's intended purpose\n\nrole_type — integer indicating the type of role\n\n**Common Use Cases**\n\nEnumerating available custom roles before assigning one to a newly invited user\n\nAuditing role names and IDs as part of an access management review\n\nRetrieving role_id values to then call GET /authz2/v1/roles/{role_id}/scopes to inspect what each role permits\n\n**Best Practices**\n\nCache role IDs in automation **Workflow**s rather than calling this endpoint on every user assignment — custom roles change infrequently\n\nUse role description fields consistently when creating roles to make this list actionable during audits\n\nCross-reference role assignments against GET /user/ to identify users assigned to each custom role\n\n**Workflow**\n\nCall GET /authz2/v1/roles/ to retrieve all custom roles and their IDs\n\nIdentify the target role by name or description\n\nCall GET /authz2/v1/roles/{role_id}/scopes with the role's id to inspect its permission set\n\nUse the role id in user assignments (PUT /authz2/v1/users/{user_id}) as needed\n", "operationId": "GetRoleURL", "security": [ { "esper_cloud_api_apiKey": [] } ], "responses": { "200": { "description": "Request Succeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_RoleResponse" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "401": { "description": "Unauthorized request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } } } }, "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Roles" ], "summary": "Create a new role. Then optionally add scopes by using the Update Role Scopes API. No scopes are added by default.", "description": "Creates a new custom RBAC role for the tenant with a specified name and description.\n\nUse this endpoint to define a new role as part of setting up fine-grained access control — then assign scopes to it via PUT /authz2/v1/roles/{role_id}/scopes before assigning it to users.\n\n**About Create Role**\n\nCustom roles in Esper allow Enterprise Admins(and other users with certain permissions) to define permission sets that are more granular than the built-in fixed roles. A newly created role has no scopes by default — it must be populated with the desired action permissions via PUT /authz2/v1/roles/{role_id}/scopes before it grants any meaningful access. Once scoped, the role can be assigned to users by setting their role to AuthZ Role User and providing the role's UUID as authz_role_id via PUT /authz2/v1/users/{user_id}.\n\n****Key Fields / Request Body****\n\nname — the display name for the new role\n\ndescription — a human-readable description of the role's intended purpose and scope of access\n\n****Key Fields (Response)****\n\nid — the UUID of the newly created role; store this immediately for use in scope assignment and user assignment calls\n\nname — the name as set in the request\n\ndescription — the description as set in the request\n\nrole_type — integer indicating the type of role\n\n**Common Use Cases**\n\nCreating a read-only role for auditors that grants only read:device and read:group scopes\n\nDefining a role for field technicians with a limited set of device command permissions\n\nBuilding a role hierarchy for multi-team fleet management\n\n**Best Practices**\n\nAlways follow role creation immediately with PUT /authz2/v1/roles/{role_id}/scopes — a role with no scopes assigned will not grant users any access\nUse clear, descriptive name and description values that reflect the intended job function, not the technical scope list, to keep the role list auditable\nStore the returned id before making any further calls — it is required for scope assignment and cannot be retrieved from this response again without calling GET /authz2/v1/roles/\n\n**Workflow**\n\nPOST to this endpoint with a name and description for the new role\n\nStore the returned role id\n\nCall PUT /authz2/v1/roles/{role_id}/scopes to assign the desired permission scopes to the role\n\nAssign the role to users via PUT /authz2/v1/users/{user_id} with role: AuthZ Role User and the role UUID as authz_role_id\n", "operationId": "PostRoleURL", "security": [ { "esper_cloud_api_apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Role" } } } }, "responses": { "200": { "description": "Request Succeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_RoleResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "401": { "description": "Unauthorized request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } } } } }, "/authz2/v1/roles/{role_id}": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Roles" ], "summary": "Get Role API", "description": "Retrieves the details of a specific custom RBAC role by its ID.\n\nUse this endpoint to confirm a role's name, description, and type before updating it or assigning it to a user.\n\n**About Get Role**\n\nThis endpoint returns the metadata for a single custom role — name, description, and role_type — identified by its UUID. It does not return the role's associated scopes; use GET /authz2/v1/roles/{role_id}/scopes to retrieve the permission set. This endpoint is useful for validating role details before making updates via PATCH /authz2/v1/roles/{role_id}.\n\n****Key Fields (Response)****\n\nid — the UUID of the role\n\nname — the display name of the role\n\ndescription — the human-readable description of the role's intended purpose\n\nrole_type — integer indicating the type of role\n\n**Common Use Cases**\n\nConfirming role details before assigning it to a user via PUT /authz2/v1/users/{user_id}\n\nVerifying that a role's name and description are accurate before referencing it in documentation or automation\n\nRetrieving role metadata as a precursor to updating it via PATCH /authz2/v1/roles/{role_id}\n\n**Best Practices**\n\nUse GET /authz2/v1/roles/ first if you don't have the role_id — this endpoint requires it as a path parameter\n\nPair this with GET /authz2/v1/roles/{role_id}/scopes to get a complete picture of what a role does before assigning it to users\n\n**Workflow**\n\nObtain the role_id from GET /authz2/v1/roles/\n\nCall GET /authz2/v1/roles/{role_id} to confirm the role's name and description\n\nProceed with user assignment or update as needed\n", "operationId": "GetRoleIdURL", "security": [ { "esper_cloud_api_apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_RoleID" } ], "responses": { "200": { "description": "Request Succeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_RoleResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "401": { "description": "Unauthorized request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } } } }, "patch": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Roles" ], "summary": "Patch Role API", "description": "Updates the name and/or description of an existing custom RBAC role.\n\nUse this endpoint to correct a role's display name or description without affecting the scopes or user assignments associated with that role.\n\n**About Patch Role**\n\nThis endpoint modifies the metadata of an existing custom role — its name and description — and leaves the role's assigned scopes and user assignments unchanged. It accepts the same Role schema as POST /authz2/v1/roles/. To modify the permissions a role grants, use PUT /authz2/v1/roles/{role_id}/scopes instead.\n\n**Key Fields / Request Body**\n\nname — the updated display name for the role\n\ndescription — the updated description for the role\n\n**Common Use Cases**\n\nRenaming a role after a team restructure or job function change\n\nCorrecting a typo or clarifying a role description to make the role list more auditable\n\n**Best Practices**\n\nNotify any Enterprise Admins or automation that reference this role by name that it has been renamed — role_id is stable across renames but human-readable references in scripts or documentation are not\n\nUse GET /authz2/v1/roles/{role_id} to confirm the current name and description before updating\n\n**Workflow**\n\nCall GET /authz2/v1/roles/{role_id} to confirm the current role metadata\n\nPATCH to this endpoint with the updated name and/or description\n\nConfirm the changes in the returned RoleResponse\n", "operationId": "UpdateRoleIdURL", "security": [ { "esper_cloud_api_apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_RoleID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_Role" } } } }, "responses": { "200": { "description": "Request Succeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_RoleResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "401": { "description": "Unauthorized request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } } } }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Roles" ], "summary": "Delete Role API", "description": "Permanently deletes a custom RBAC role from the tenant.\n\nUse this endpoint to remove a role that is no longer needed — all users currently assigned to it must be reassigned to a different role before deletion will succeed.\n\n**About Delete Role**\n\nDeleting a custom role removes it from the tenant permanently. Any users currently assigned to this role via AuthZ Role User must be reassigned to a different role before this endpoint can be called — attempting to delete a role with active user assignments will fail. Returns HTTP 204 on success with no response body.\n\n****Key Parameters****\n\nrole_id — the UUID of the role to delete; obtain from GET /authz2/v1/roles/\n\n**Common Use Cases**\n\nRemoving a role that was created for a temporary project or team that no longer exists\n\nCleaning up duplicate or incorrectly configured roles during an access audit\n\n**Best Practices**\n\nBefore deleting, call GET /user/ and cross-reference profile.authz_role_id to identify any users still assigned to this role — you must reassign or remove them before deletion will succeed\n\nConfirm deletion success via the 204 response before removing the role from any internal documentation or automation\n\n**Workflow**\n\nCall GET /authz2/v1/roles/ to confirm the target role's role_id\n\nCall GET /user/ and cross-reference profile.authz_role_id to identify all users assigned to this role\n\nCall PUT /authz2/v1/users/{user_id} for each assigned user to reassign them to a different role\n\nCall DELETE /authz2/v1/roles/{role_id} once no users remain assigned to the role\n\nConfirm the 204 response indicating successful deletion\n", "operationId": "DeleteRoleIdURL", "security": [ { "esper_cloud_api_apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_RoleID" } ], "responses": { "204": { "description": "Deleted successfully" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "401": { "description": "Unauthorized request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } } } } }, "/authz2/v1/roles/{role_id}/scopes": { "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Roles" ], "summary": "Update Role Scopes API", "description": "Replaces the full set of permission scopes assigned to a custom RBAC role.\n\nUse this endpoint after creating a new role to add its initial scopes, or to update an existing role's permissions when access requirements change.\n\n**About Update Role Scopes**\n\nScopes define the specific actions a custom role grants — such as reading device data, issuing commands, or managing groups. This endpoint performs a full replacement of a role's scope set; any scopes not included in the request will be removed. Scopes can be specified either by UUID (scope_ids) or by name string (scope_names). A newly created role has no scopes by default and must be populated via this endpoint before it grants meaningful access to assigned users.\n\n****Key Fields / Request Body****\n\nscope_ids — array of scope UUIDs to assign to the role\n\nscope_names — array of scope name strings to assign; valid values include read:device, read:group, read:blueprint, read:directory_record, and a range of create:device_command:* and create:group_command:* action scopes\n\n**Common Use Cases**\n\nPopulating a newly created role with its initial permission set\n\nExpanding a role's permissions after a team's responsibilities grow\n\nNarrowing a role's permissions during an access review by replacing the scope set with a reduced list\n\n**Best Practices**\n\nTreat every call to this endpoint as a full replacement — always include the complete intended scope set, not just the scopes you want to add\n\nUse GET /authz2/v1/roles/{role_id}/scopes first to retrieve the current scope set before making changes, to avoid accidentally removing permissions\n\nUse scope_names rather than scope_ids in automation where possible — names are stable and human-readable, making scripts easier to maintain\n\nAfter updating scopes, verify the change took effect via GET /authz2/v1/roles/{role_id}/scopes\n\n**Workflow**\n\nCall GET /authz2/v1/roles/{role_id}/scopes to retrieve the current scope set\n\nBuild the updated scope list, including all scopes that should remain plus any new additions\n\nPUT to this endpoint with the full intended scope set as scope_names or scope_ids\n\nConfirm the updated scopes via GET /authz2/v1/roles/{role_id}/scopes\n", "operationId": "PutRoleScopeURL", "security": [ { "esper_cloud_api_apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope_ids": { "type": "array", "items": { "type": "string" } }, "scope_names": { "type": "array", "items": { "type": "string", "enum": [ "read:device", "read:group", "read:blueprint", "read:directory_record", "create:device_command:SET_DEVICE_LOCKDOWN_STATE", "create:device_command:REBOOT", "create:device_command:BEEP_DEVICE", "create:device_command:WIPE", "create:device_command:UPDATE_HEARTBEAT", "create:device_command:NOTIFY_DEVICE", "create:device_command:LOCK", "create:device_command:SET_KIOSK_APP", "update:device:group", "create:device:tag", "update:device:tag", "delete:device:tag", "update:device:alias", "create:template_upgrade", "create:device_command:SET_STREAM_VOLUME", "create:device_command:SET_BRIGHTNESS_SCALE", "create:device_command:SET_ROTATION_STATE", "create:device_command:SET_SCREEN_OFF_TIMEOUT", "create:device_command:SET_WALLPAPER", "create:device_command:SET_WIFI_STATE", "create:device_command:ADD_WIFI_AP", "create:device_command:REMOVE_WIFI_AP", "create:device_command:UPDATE_WIFI_AP", "create:device_command:SET_STATIC_IP", "create:device_command:SET_ETHERNET_SETTINGS", "create:device_command:SET_GPS_STATE", "create:device_command:SET_BLUETOOTH_STATE", "create:device_command:SET_TIMEZONE", "create:device_command:SET_ADB_STATE", "create:device_command:UPDATE_DEVICE_CONFIG", "create:device_command:UPDATE_BLUEPRINT", "create:device_command:SHUT_DOWN", "create:device_command:CLEAR_PASSCODE", "create:device_command:LOST_MODE", "read:device_app", "create:device_command:REFRESH_APPLIST", "create:device_command:INSTALL", "create:device_command:INSTALL_APP", "create:device_command:UNINSTALL", "create:device_command:UNINSTALL_APP", "create:device_command:SET_APP_STATE", "create:device_command:CLEAR_APP_DATA", "create:device_command:CLEAR_APP_CACHE", "create:device_command:SET_APP_PERMISSION", "create:device_command:REQUEST_BUGREPORT", "create:device_command:SET_NEW_POLICY", "create:group_command:SET_NEW_POLICY", "create:group", "create:group_command:REBOOT", "create:group_command:LOCK", "create:group_command:UPDATE_HEARTBEAT", "create:group_command:WIPE", "create:group_command:NOTIFY_DEVICE", "create:group_command:SET_KIOSK_APP", "create:group_command:SET_STREAM_VOLUME", "create:group_command:SET_BRIGHTNESS_SCALE", "create:group_command:SET_ROTATION_STATE", "create:group_command:SET_SCREEN_OFF_TIMEOUT", "create:group_command:SET_WALLPAPER", "create:group_command:SET_WIFI_STATE", "create:group_command:ADD_WIFI_AP", "create:group_command:REMOVE_WIFI_AP", "create:group_command:UPDATE_WIFI_AP", "create:group_command:SET_STATIC_IP", "create:group_command:SET_ETHERNET_SETTINGS", "create:group_command:SET_GPS_STATE", "create:group_command:SET_BLUETOOTH_STATE", "create:group_command:SET_TIMEZONE", "create:group_command:SET_ADB_STATE", "create:group_command:UPDATE_DEVICE_CONFIG", "create:group_command:UPDATE_BLUEPRINT", "create:group_command:INSTALL", "create:group_command:INSTALL_APP", "create:group_command:UNINSTALL", "create:group_command:UNINSTALL_APP", "create:group_command:SET_APP_STATE", "create:device_command:INITIATE_OFFER", "read:device_screenshot", "create:device_command:CAPTURE_SCREENSHOT", "create:device_screenshot", "read:device_graph", "read:event_feed", "create:blueprint", "update:blueprint", "delete:blueprint", "create:device_command:CONVERGE", "update:device:blueprint", "update:group:blueprint", "provision:device", "read:compliance_policy", "create:compliance_policy", "update:compliance_policy", "delete:compliance_policy", "read:provisioning_template", "create:provisioning_template", "update:provisioning_template", "delete:provisioning_template", "create:provisioning_template:imei_serial", "update:provisioning_template:imei_serial", "delete:provisioning_template:imei_serial", "update:provisioning_template:wifi_management", "read:app", "read:emm", "create:emm", "update:emm", "create:app:esper_android", "update:app:esper_android", "delete:app:esper_android", "read:alert", "read:pipeline", "read:geofence", "read:report", "create:report", "read:personal_access_token", "create:personal_access_token", "update:personal_access_token", "delete:personal_access_token", "read:foundation_build", "read:foundation_device_model", "update:foundation_build", "update:foundation_device_model", "read:foundry_event", "update:command", "read:user:group", "create:app:esper_ios", "update:app:esper_ios", "delete:app:esper_ios", "create:operation:CONVERGE", "create:operation:REBOOT", "create:operation:INSTALL", "create:operation:UNINSTALL", "create:operation:APP_INSTALL", "create:operation:APP_UNINSTALL", "read:operation", "update:operation", "read:operation:devices", "read:device:operations", "update:operation:devices", "create:device_command:RUN_SHELL_SCRIPT", "create:remote_terminal", "read:report:query", "create:report:query", "read:report:saved_query", "create:report:saved_query", "update:report:saved_query", "delete:report:saved_query", "create:device_command:REMOVE_DEVICE", "read:report:ingest", "create:report:ingest", "read:esper_apps", "create:device_command:RUN_CUSTOM_ACTION", "create:device_command:LIST_RESTRICTED_PROFILES", "create:device_command:LIST_PROVISIONING_PROFILES", "create:group_command:SYNC_CONTENT", "create:device_command:SYNC_CONTENT" ] } } } } } } }, "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_RoleID" } ], "responses": { "200": { "description": "Request Succeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_ScopeResponse" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "401": { "description": "Unauthorized request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } } } }, "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Roles" ], "summary": "List Role Scopes API", "description": "Returns the permission scopes currently assigned to a specific custom RBAC role.\n\nUse this endpoint to inspect what actions a role grants before assigning it to a user, or to retrieve the current scope set before making updates.\n\n**About List Role Scopes**\n\nEach custom role in Esper has a set of scopes that define the actions users assigned to that role are permitted to perform — such as reading device data, issuing specific commands, or managing group membership. This endpoint returns those scopes as a scopes array alongside a count field. Results include each scope's UUID, name, description, and type. This is the reference endpoint to call before using PUT /authz2/v1/roles/{role_id}/scopes to modify a role's permissions.\n\n****Key Fields (Response)****\n\nid — the UUID of the scope; used with PUT /authz2/v1/roles/{role_id}/scopes when updating via scope_ids\n\nname — the scope name string (e.g., read:device, create:device_command:REBOOT)\n\ndescription — a human-readable description of what the scope permits\n\nscope_type — integer indicating the type of scope\n\n**Common Use Cases**\n\nAuditing what permissions a role grants before assigning it to a user\n\nRetrieving the current scope set as a baseline before updating it via PUT /authz2/v1/roles/{role_id}/scopes\n\nVerifying that a scope update was applied correctly after calling the update endpoint\n\n**Best Practices**\n\nAlways call this endpoint before PUT /authz2/v1/roles/{role_id}/scopes — since that endpoint performs a full replacement, knowing the current set prevents accidental permission removal\n\nUse scope name values from the response to build human-readable access summaries for audit reports\n\n**Workflow**\n\nCall GET /authz2/v1/roles/{role_id}/scopes to retrieve all scopes currently assigned to the role\n\nReview the name and description of each scope to confirm the role's permission set\n\nUse the results as the baseline when preparing an update via PUT /authz2/v1/roles/{role_id}/scopes\n", "operationId": "GetRoleScopeURL", "security": [ { "esper_cloud_api_apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_RoleID" } ], "responses": { "200": { "description": "Request Succeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_ScopeResponse" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "401": { "description": "Unauthorized request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } } } } }, "/authn2/v0/personal-access-token/": { "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Personal Access Token" ], "summary": "Generate a new personal access token", "description": "Generates a new personal access token (API key) for the authenticated user, scoped to the current tenant.\nUse this endpoint to create a named, expiry-controlled API key for programmatic access to the Esper API.\n\n**About Generate Personal Access Token**\n\nPersonal access tokens are named, expiry-controlled API keys tied to a specific user and tenant. They replace the legacy developer app token system (see POST /v0/enterprise/{enterprise_id}/developerapp/{developerapp_id}/renew-token/, which is deprecated). Personal access tokens are scoped to the authenticated caller — this endpoint generates an API key for the user associated with the API key making the request, and cannot be used to create API keys on behalf of other users. The full API key value is returned only in the response to this create call — it is not retrievable again via the list endpoint, which returns only the key prefix. Store the API key value securely immediately after creation.\n\n**Key Fields / Request Body**\n\nname — (required) a human-readable label for the API key, used to identify it in the token list\n\ndescription — (required) a description of the API key's intended use\n\nexpiry_at — (required) the expiry date as a Unix timestamp integer; set to -1 for a non-expiring API key\n\n**Key Fields (Response)**\n\nid — the UUID of the newly created token record; store this for use in renewal and deletion calls\n\ntoken — the full API key value; this is the only time it is returned — store it securely immediately\n\nprefix — a short prefix of the API key, used to identify it in future list responses\n\nexpiry_at — the expiry timestamp as set in the request\n\n**Common Use Cases**\n\nCreating an API key for a CI/CD pipeline or automated script\n\nGenerating a long-lived API key for an integration that cannot handle session-based authentication\n\nIssuing a dedicated API key for a specific integration or team member\n\n**Best Practices**\n\nStore the token value from the response immediately and securely — it cannot be retrieved again after this call\n\nStore the id alongside the API key value for future renewal or deletion via PUT and DELETE /authn2/v0/personal-access-token/{personal_access_token_id}\n\nSet a meaningful expiry_at value rather than using -1 (no expiry) wherever possible — expiring API keys reduce the blast radius of credential leaks\n\nUse distinct name and description values per API key to make the list endpoint actionable during audits\n\n**Workflow**\n\nPOST to this endpoint with a name, description, and expiry_at\n\nImmediately store the returned token value and id securely\n\nUse the API key value in subsequent Esper API calls\n\nTrack the expiry_at and renew via PUT /authn2/v0/personal-access-token/{personal_access_token_id} before expiry\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "name for the token." }, "description": { "type": "string", "description": "description for the token." }, "expiry_at": { "type": "integer", "description": "exipy date for token." } }, "required": [ "name", "description", "expiry_at" ] } } } }, "responses": { "200": { "description": "Token successfully generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_PersonalAccessTokenCreateResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } } } }, "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Personal Access Token" ], "summary": "Get tokens for corresponding user and tenant", "description": "Returns the full list of tokens for the current user and tenant. Tokens are scoped to the authenticated caller. This endpoint only returns tokens belonging to the user associated with the API key making the request, not tokens for other users in the tenant. Use this endpoint to locate the id of a specific token for use with the renew (PUT) or delete (DELETE) endpoints.\n\nUse this endpoint to audit active API keys, identify keys approaching expiry, or retrieve token IDs for renewal or deletion.\n\n**About Get Personal Access Tokens**\n\nReturns the full list of personal access tokens for the current user and tenant. Personal access tokens are scoped to the authenticated caller. This endpoint only returns API keys belonging to the user associated with the API key making the request, not those belonging to other users in the tenant. Use this endpoint to locate the id of a specific token for use with the renew (PUT) or delete (DELETE) endpoints.\n\n**Key Fields (Response)**\n\nid — the UUID of the token record; use with PUT and DELETE /authn2/v0/personal-access-token/{personal_access_token_id}\n\nname — the human-readable label assigned at creation\n\ndescription — the description assigned at creation\n\nprefix — a short prefix of the API key; use this to identify which key corresponds to a known credential without exposing the secret\n\nexpiry_at — the expiry as a Unix timestamp; -1 indicates no expiry\n\ncreated_at / updated_at — timestamps for the token record\n\nlegacy_token_id / legacy_developer_app_id — references to the legacy token system, if applicable\n\n**Common Use Cases**\n\nAuditing which API keys are active for the current user\n\nIdentifying API keys approaching expiry so they can be renewed before they stop working\n\nRetrieving the id of a specific token for renewal or deletion when the ID was not stored at creation time\n\n**Best Practices**\n\nUse prefix values to match list entries to known API keys in your secrets store — the full key value is never returned here\n\nRegularly review expiry_at values and renew any API keys that will expire before your next maintenance window\n\nTreat any token with a legacy_token_id as a migration candidate — consider replacing it with a new personal access token and retiring the legacy credential\n\n**Workflow**\n\nCall GET /authn2/v0/personal-access-token/ to retrieve all API keys for the current user\n\nIdentify the target token by name, prefix, or expiry_at\n\nUse the token id with PUT .../personal-access-token/{personal_access_token_id} to renew, or DELETE to revoke\n", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_PersonalAccessTokenGetResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } } } } }, "/authn2/v0/personal-access-token/{personal_access_token_id}": { "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Personal Access Token" ], "summary": "Renew personal access token", "description": "Renews a personal access token by updating its expiry date.\n\nUse this endpoint to extend the validity of an existing API key before it expires, without needing to generate a new key and update credentials in all systems that use it.\n\n**About Renew Personal Access Token**\n\nPersonal access tokens are API keys with an expiry date set at creation. This endpoint extends the expiry in place — the API key value itself does not change, only the expiry_at timestamp is updated. Personal access tokens are scoped to the authenticated caller — only API keys belonging to the user associated with the API key making the request can be renewed; those belonging to other users cannot be managed here. The API key value is returned in the response. API keys created with expiry_at: -1 (no expiry) can also be updated to add an expiry via this endpoint.\n\n**Key Fields / Request Body**\n\nexpiry_at — (required) the new expiry date as a Unix timestamp integer; set to -1 for no expiry\n\n**Key Fields (Response)**\n\nid — the UUID of the token record\n\ntoken — the API key value (unchanged); returned here for convenience\n\nexpiry_at — the updated expiry timestamp as set in the request\n\nupdated_at — timestamp confirming when the renewal was applied\n\n**Common Use Cases**\n\nExtending an API key's validity before it expires to avoid service interruption in automated integrations\n\nConverting an API key from a fixed expiry to no expiry (or vice versa) by updating expiry_at\n\nRenewing an API key as part of a scheduled credential rotation policy\n\n**Best Practices**\n\nUse GET /authn2/v0/personal-access-token/ to retrieve the personal_access_token_id if it was not stored at creation time — match by name or prefix\n\nRenew API keys before they expire rather than after — a lapsed key will cause API calls to fail until renewed or replaced\n\nKeep a record of each API key's expiry_at in your secrets management system so renewals can be scheduled proactively\n\n**Workflow**\n\nCall GET /authn2/v0/personal-access-token/ to identify the target token and retrieve its id if needed\n\nPUT to this endpoint with the new expiry_at value\n\nConfirm the updated expiry_at in the response\n", "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_PersonalAccessTokenID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expiry_at": { "type": "integer", "description": "exipy date for token." } }, "required": [ "expiry_at" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_PersonalAccessTokenUpdateResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } } } }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_Personal Access Token" ], "summary": "Delete personal access token", "description": "Permanently revokes a personal access token (API key), immediately invalidating any API calls that use it.\n\nUse this endpoint to decommission an API key that is no longer needed, has been compromised, or belongs to a user who is leaving the organization.\n\n**About Delete Personal Access Token**\n\nDeleting a personal access token permanently revokes the API key — any integration or script using it will receive authentication errors on its next call. Personal access tokens are scoped to the authenticated caller — only API keys belonging to the user associated with the API key making the request can be deleted; those belonging to other users cannot be managed here. Deletion is immediate with no grace period. Returns HTTP 204 on success with no response body. If an API key needs to be replaced rather than simply revoked, generate a new one via POST /authn2/v0/personal-access-token/ and update all dependent systems before deleting the old key.\n**Key Parameters**\n\npersonal_access_token_id — the UUID of the token record to revoke; obtain from GET /authn2/v0/personal-access-token/\n\n**Common Use Cases**\n\nRevoking an API key that may have been exposed or compromised\n\nDecommissioning an API key used by a departing team member or retired integration\n\nCleaning up unused or expired API keys during a credential audit\n\n**Best Practices**\n\nIf the API key is in active use, generate and deploy a replacement via POST /authn2/v0/personal-access-token/ before deleting the old one to avoid service interruption\n\nUse GET /authn2/v0/personal-access-token/ to confirm the correct personal_access_token_id by matching on name or prefix before deleting — revocation is immediate and irreversible\n\nConfirm the 204 response before notifying stakeholders that the API key has been revoked\n\n**Workflow**\n\nCall GET /authn2/v0/personal-access-token/ to identify the target token and retrieve its id\n\nIf the API key is in active use, generate and deploy a replacement first\n\nCall DELETE /authn2/v0/personal-access-token/{personal_access_token_id}\n\nConfirm the 204 response indicating successful revocation\n", "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_PersonalAccessTokenID" } ], "responses": { "204": { "description": "OK" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } } } } }, "/authn2/v1/users/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "esper_cloud_api_User" ], "summary": "Get Users details", "description": "Retrieves the list of users belonging to the tenant.\n\nReturns each user's UsersListResponse record, including their UUID-format user_id, email, name, and the connection they authenticated through. Optionally filter by a legacy integer user ID for cross-referencing against older user records.\n\n**About Get Users**\n\nThis is the current, supported endpoint for listing users in a tenant, and it returns the UUID-format identifier (user_id) needed for other user-management endpoints such as Update User Role, which requires an authn_user_id in UUID format. This UUID is distinct from the integer id returned by the older GET /user/ endpoint; use this endpoint whenever a downstream call requires the UUID form.\n\n**Key Fields / Query Parameters**\n\nlegacy_user_id — an optional integer filter for cross-referencing against the older, integer-based user id from GET /user/\n\n**Common Use Cases**\n\nRetrieving a user's UUID before calling Update User Role or another endpoint that requires authn_user_id\n\nAuditing the full list of users in a tenant along with their email and connection\n\nCross-referencing a legacy integer user id against its corresponding UUID\n\n**Best Practices**\n\nAlways retrieve the UUID form of a user's id from this endpoint before calling endpoints that require authn_user_id, rather than assuming the integer id from GET /user/ will work\n\nUse legacy_user_id when migrating scripts that were written against the older integer-based user id\n\n**Workflow**\n\nCall this endpoint to list users, optionally filtering by legacy_user_id\n\nCapture the user_id (UUID) for the target user\n\nUse that UUID in downstream calls such as Update User Role\nThis endpoint allows to fetch user list of a tenant\n", "parameters": [ { "$ref": "#/components/parameters/esper_cloud_api_LegacyUserID" } ], "responses": { "200": { "description": "Users fetched successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_UsersListResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/esper_cloud_api_GenericErrorResponse" } } } } } } }, "/v2/blueprints/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "blueprints_Blueprints API" ], "description": "Retrieves a paginated list of all Blueprint V2 blueprints in the enterprise, with optional filtering and sorting.\nReturns an array of BlueprintV2 objects matching the provided filters; supports filtering by name (case-insensitive or exact), by app or app version IDs across Android, iOS, and Windows, by file or Wi-Fi network references, and by iOS provisioning profile. Results can be ordered by any supported field using the ordering parameter.\n\n**About List Blueprints (V2)**\n\nBlueprints in Esper define the desired state for managed devices — grouping app assignments, device settings, policies, and content into a reusable configuration template. Blueprint V2 is the current, supported version of the blueprint system; Blueprint V1 is deprecated. This endpoint lists all blueprints scoped to the enterprise, enabling integrators to build UIs, trigger automated deployments, or audit which blueprints reference a given app, file, or network configuration.\n\n**Key Fields / Query Parameters**\n\nname — Filter by blueprint name, case-insensitive partial match\n\nname_exact — Filter by exact name, case-sensitive\n\nordering — Sort results by a field (prefix with - for descending); combine multiple fields with commas (e.g., -created_at,-updated_at)\n\nsettings__android__app_id — Filter to blueprints that include a specific Android app (by Esper app UUID)\n\nsettings__android__app_version_id — Filter to blueprints that include a specific Android app version\n\nsettings__ios__app_id / settings__ios__app_version_id — Same as above for iOS apps\n\nsettings__windows__app_id / settings__windows__app_version_id — Same as above for Windows apps\n\nsettings__android__file_id — Filter to blueprints that reference a specific managed file\n\nsettings__android__wifi_network_id — Filter to blueprints that include a specific Wi-Fi network profile\n\nsettings__ios__provisioning_profile_id / settings__ios__provisioning_profile_version_id — Filter by iOS provisioning profile or profile version\n\n**Common Use Cases**\n\nListing all blueprints to populate a blueprint selection UI or dashboard\n\nFinding which blueprints reference a specific app version before pushing an update or deprecating a version\n\nAuditing all blueprints that use a particular Wi-Fi network or managed file\n\nRetrieving all iOS blueprints that include a specific provisioning profile\n\n**Best Practices**\n\nUse settings__* filter parameters when tracing blueprint dependencies on a specific resource — this is faster than fetching all blueprints and filtering client-side\n\nUse name for fuzzy search and name_exact when integrating with systems that require precise name matching\n\nPaginate results using next and previous links in the response for large blueprint libraries\n\n**Workflow**\n\nCall GET /api/v2/blueprints/ with any relevant filter parameters\n\nInspect the count field in the response to determine if pagination is needed\n\nIterate through next links to retrieve subsequent pages if next is non-null\n", "parameters": [ { "in": "query", "name": "ordering", "schema": { "type": "string" }, "description": "Order the results by a specific field (-field for descending order), Combine Multiple with , like -created_at,-updated_at.\n" }, { "in": "query", "name": "name", "schema": { "type": "string" }, "description": "Filter the results by name, case insensitive\n" }, { "in": "query", "name": "name_exact", "schema": { "type": "string" }, "description": "Filter the results by name, case sensitive and matches exact name\n" }, { "in": "query", "name": "settings__android__app_id", "schema": { "type": "string", "format": "uuid" }, "description": "List the blueprints which have given app_id in any of the versions for android apps.\n" }, { "in": "query", "name": "settings__android__app_version_id", "schema": { "type": "string", "format": "uuid" }, "description": "List the blueprints which have given app_version_id in any of the versions for android apps.\n" }, { "in": "query", "name": "settings__ios__app_id", "schema": { "type": "string", "format": "uuid" }, "description": "List the blueprints which have given app_id in any of the versions for ios apps.\n" }, { "in": "query", "name": "settings__ios__app_version_id", "schema": { "type": "string", "format": "uuid" }, "description": "List the blueprints which have given app_version_id in any of the versions for ios apps.\n" }, { "in": "query", "name": "settings__windows__app_id", "schema": { "type": "string", "format": "uuid" }, "description": "List the blueprints which have given app_id in any of the versions for windows apps.\n" }, { "in": "query", "name": "settings__windows__app_version_id", "schema": { "type": "string", "format": "uuid" }, "description": "List the blueprints which have given app_version_id in any of the versions for windows apps.\n" }, { "in": "query", "name": "settings__android__file_id", "schema": { "type": "string", "format": "uuid" }, "description": "List the blueprints which have given file_id in any of the versions.\n" }, { "in": "query", "name": "settings__android__wifi_network_id", "schema": { "type": "string", "format": "uuid" }, "description": "List the blueprints which have given wifi_network_id in any of the versions.\n" }, { "in": "query", "name": "settings__ios__provisioning_profile_id", "schema": { "type": "string", "format": "uuid" }, "description": "Filter blueprints that have the given provisioning profile ID in any version.\n" }, { "in": "query", "name": "settings__ios__provisioning_profile_version_id", "schema": { "type": "string", "format": "uuid" }, "description": "Filter blueprints that have the given provisioning profile version ID in any version.\n" }, { "in": "query", "name": "settings__tvos__app_id", "schema": { "type": "string", "format": "uuid" }, "description": "List the blueprints which have given app_id in any of the versions for tvos apps.\n" }, { "in": "query", "name": "settings__tvos__app_version_id", "schema": { "type": "string", "format": "uuid" }, "description": "List the blueprints which have given app_version_id in any of the versions for tvos apps.\n" }, { "in": "query", "name": "settings__tvos__provisioning_profile_id", "schema": { "type": "string", "format": "uuid" }, "description": "Filter blueprints that have the given provisioning profile ID in any version for tvos.\n" }, { "in": "query", "name": "settings__tvos__provisioning_profile_version_id", "schema": { "type": "string", "format": "uuid" }, "description": "Filter blueprints that have the given provisioning profile version ID in any version for tvos.\n" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "count": { "type": "integer", "format": "int64", "description": "The number of objects in the result set" }, "next": { "type": "string", "description": "The link to retrieve the next set of objects in the result set" }, "previous": { "type": "string", "description": "The link to retrieve the previous set of objects in the result set" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/blueprints_BlueprintV2" } }, "message": { "type": "string" }, "code": { "type": "integer" } } } } } } } } } }, "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "blueprints_Blueprints API" ], "description": "Creates a new blueprint in the enterprise. Blueprints define device configuration and management rules (for example, kiosk/device mode settings, app/file payloads, Wi-Fi networks, and OS-specific restrictions). After you create a blueprint, you can publish versions and then assign/apply it to devices through separate workflows. Creating a blueprint doesn’t affect devices by itself. Devices won’t change until the blueprint (and typically a specific version) is assigned/applied via a separate endpoint/workflow. Because the create response is list-shaped, you should read the new blueprint ID from content.results[0].id. If your workflow relies on versioning, capture both the blueprint id and the returned version_id (if present in your create response), since later calls may require one or the other. Workflow: After creating a blueprint, assign a device or group to it using POST https://{foo}-api.esper.cloud/api/v2/converge\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/blueprints_BlueprintV2" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/blueprints_BlueprintV2" }, "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 201 ] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 400 ] } } } } } } } } }, "/v2/blueprints/{blueprint_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "blueprints_Blueprints API" ], "description": "Retrieves the full configuration for a single blueprint by its ID.\n\nReturns the BlueprintV2 object representing the blueprint's current configuration and metadata. This does not return version-specific settings on its own; use the versions endpoints to retrieve a specific published version's configuration.\n\n**About Get Blueprint**\n\nBlueprints define device configuration and management rules, including kiosk and device mode settings, app and file payloads, Wi-Fi networks, and OS-specific restrictions. This endpoint returns the blueprint record itself; the actual configuration a device receives comes from a specific version of the blueprint, retrieved separately through the versions endpoints. Blueprint V2 is the current version of this system and should be used for all new integrations; Blueprint V1 (the older devicegroup-scoped blueprint endpoints) is deprecated.\n\n**Common Use Cases**\n\nLooking up a blueprint's current metadata before publishing a new version\n\nConfirming a blueprint exists and is accessible before assigning it to a device or group through Converge\n\n**Best Practices**\n\nUse the returned id together with the versions endpoints to retrieve the specific configuration a device will receive\n\nTreat a 404 response as meaning the blueprint_id does not exist or was deleted, not as a transient error\n\n**Workflow**\n\nObtain the blueprint_id from a blueprint list or from POST /v2/blueprints/\n\nCall this endpoint to retrieve the blueprint record\n\nCall GET /v2/blueprints/{blueprint_id}/versions/ to see its published versions\n", "parameters": [ { "in": "path", "name": "blueprint_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/blueprints_BlueprintV2" }, "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 201 ] } } } } } }, "404": { "description": "Content not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object" }, "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 404 ] } } } } } } } }, "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "blueprints_Blueprints API" ], "description": "Updates a blueprint's top-level record by ID.\n\nThis performs a full replacement of the blueprint's editable fields using the BlueprintV2Put schema. It updates the blueprint record itself, not a specific version; to change the configuration devices actually receive, publish a new version instead.\n\n**About Update Blueprint**\nBecause Converge applies a specific version rather than the blueprint record directly, updating the blueprint itself is typically limited to metadata-level changes rather than configuration changes. If the goal is to change what devices receive (apps, files, restrictions, and so on), the correct approach is to create a new blueprint version rather than editing the existing blueprint record.\n\n**Common Use Cases**\n\nRenaming a blueprint or updating its top-level metadata\n\nCorrecting a blueprint record without affecting any of its published versions\n\n**Best Practices**\n\nConfirm whether the change belongs on the blueprint record or on a new version before calling this endpoint; device-facing configuration changes belong on a version\n\nProvide the full set of editable fields in the request body, since this is a full replacement rather than a partial update\n\n**Workflow**\n\nCall GET /v2/blueprints/{blueprint_id}/ to review the current record\n\nPrepare the full BlueprintV2Put payload with the updated fields\n\nPUT to this endpoint to apply the update\n\nConfirm the change with a follow-up GET\n", "parameters": [ { "in": "path", "name": "blueprint_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/blueprints_BlueprintV2Put" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/blueprints_BlueprintV2" }, "message": { "type": "string" }, "code": { "type": "string", "enum": [ 201 ] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string", "enum": [ 3456 ] } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object" }, "message": { "type": "string" }, "code": { "type": "string", "enum": [ 3456 ] } } } } } } } }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "blueprints_Blueprints API" ], "description": "Deletes a Blueprint by its ID.\n\nPermanently removes the specified Blueprint V2 (the current Blueprints API) instance; returns a 204 on success or a 404 if the blueprint isn't found.\n\n**About Blueprints**\n\nBlueprints define the configuration state (apps, settings, files, Wi-Fi networks, etc.) that Esper applies to devices or groups. This is the current Blueprints API (V2) — distinct from the deprecated Blueprint V1 endpoints, which point back to this API as their replacement.\n\n**Key Fields / Query Parameters**\n\n- blueprint_id — UUID of the blueprint to delete, passed in the path\n\n**Common Use Cases**\n\n- Removing an obsolete or unused blueprint configuration\n- Cleaning up blueprints after consolidating device policies\n\n**Best Practices**\n\n- Confirm no active device groups still reference the blueprint before deleting it, since deletion is permanent\n", "parameters": [ { "in": "path", "name": "blueprint_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/blueprints_BlueprintV2" }, "message": { "type": "string" }, "code": { "type": "string", "enum": [ 201 ] } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object" }, "message": { "type": "string" }, "code": { "type": "string", "enum": [ 201 ] } } } } } } } } }, "/v2/blueprints/{blueprint_id}/versions/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "blueprints_Blueprints API" ], "description": "Retrieves a paginated list of every version created for a specific blueprint.\n\nEach blueprint can have multiple versions as its configuration evolves over time; this endpoint returns them all, with filters available for version number, publish status, and specific apps, files, or Wi-Fi networks referenced within a version's settings.\n\n**About Blueprint Versions**\n\nA blueprint's actual device configuration lives on its versions, not on the blueprint record itself. Versions let you iterate on a blueprint's settings (apps, files, restrictions, and so on) while keeping a history of what changed and when. Devices are converged to a specific blueprint_version_id, not just a blueprint_id, so this endpoint is the standard way to find the version currently in use or the version you intend to publish next.\n\n**Key Fields / Query Parameters**\n\nversion_number — filters results to a specific version number\n\npublish — filters by publish status\n\nsettings__android__app_id — returns versions that include the given app in their settings\n\nordering — orders results by one or more fields such as version_number or minor_version_number; prefix a field with a minus sign to reverse order, combine multiple fields with a comma\n\n**Common Use Cases**\n\nFinding the latest published version of a blueprint before converging devices to it\n\nAuditing how a blueprint's app or Wi-Fi network settings have changed across versions\n\nConfirming which blueprint versions reference a specific app before removing that app from the tenant\n\n**Best Practices**\n\nFilter by publish to distinguish draft versions from versions that are live and available for Converge\n\nUse the settings__android__app_id and similar filters to find every version affected before making a breaking change to a shared resource\n\n**Workflow**\n\nCall this endpoint with the blueprint_id to list its versions\n\nIdentify the version_id of the version you need, typically the latest published one\n\nCall GET /v2/blueprints/{blueprint_id}/versions/{version_id}/ for that version's full settings\n\nUse the version_id in a Converge request to apply it to devices\n", "parameters": [ { "in": "path", "name": "blueprint_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "ordering", "schema": { "type": "string" }, "description": "Order the results by a specific field (-field for descending order), Combine Multiple with , like -version_number,-minor_version_number.\n" }, { "in": "query", "name": "version_number", "schema": { "type": "string" }, "description": "Filter the results by version_number\n" }, { "in": "query", "name": "publish", "schema": { "type": "string" }, "description": "Filter the results by publish\n" }, { "in": "query", "name": "settings__android__app_id", "schema": { "type": "string", "format": "uuid" }, "description": "List the versions which have given app_id.\n" }, { "in": "query", "name": "settings__android__app_version_id", "schema": { "type": "string", "format": "uuid" }, "description": "List the versions which have given app_version_id.\n" }, { "in": "query", "name": "settings__android__file_id", "schema": { "type": "string", "format": "uuid" }, "description": "List the blueprints which have given file_id.\n" }, { "in": "query", "name": "settings__android__wifi_network_id", "schema": { "type": "string", "format": "uuid" }, "description": "List the blueprints which have given wifi_network_id.\n" }, { "in": "query", "name": "settings__ios__provisioning_profile_id", "schema": { "type": "string", "format": "uuid" }, "description": "Filter versions that have the given provisioning profile ID for iOS.\n" }, { "in": "query", "name": "settings__ios__provisioning_profile_version_id", "schema": { "type": "string", "format": "uuid" }, "description": "Filter versions that have the given provisioning profile version ID for iOS.\n" }, { "in": "query", "name": "settings__tvos__provisioning_profile_id", "schema": { "type": "string", "format": "uuid" }, "description": "Filter versions that have the given provisioning profile ID for tvos.\n" }, { "in": "query", "name": "settings__tvos__provisioning_profile_version_id", "schema": { "type": "string", "format": "uuid" }, "description": "Filter versions that have the given provisioning profile version ID for tvos.\n" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "count": { "type": "integer", "format": "int64", "description": "The number of objects in the result set" }, "next": { "type": "string", "description": "The link to retrieve the next set of objects in the result set" }, "previous": { "type": "string", "description": "The link to retrieve the previous set of objects in the result set" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/blueprints_BlueprintV2" } }, "message": { "type": "string" }, "code": { "type": "integer" } } } } } } } } } } }, "/v2/blueprints/{blueprint_id}/versions/{version_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "blueprints_Blueprints API" ], "description": "Retrieves the full configuration for a single, specific version of a blueprint.\n\nReturns the complete settings payload for the given version_id, including whatever apps, files, Wi-Fi networks, and platform-specific restrictions were defined at that point in the blueprint's history.\n\n**About Get Blueprint Version**\nThis is the endpoint that returns the actual configuration a device receives when converged to a blueprint, since Converge applies a specific blueprint_version_id rather than just a blueprint_id. Use it to inspect exactly what a version will change on a device before rolling it out broadly.\n\n**Common Use Cases**\n\nReviewing a version's full settings before using it in a Converge action\n\nComparing two versions of the same blueprint to understand what changed between them\n\n**Best Practices**\n\nAlways confirm the version_id belongs to the expected blueprint_id, since version IDs are not unique across blueprints in isolation\n\nReview a version's settings in full before converging a large device group to it, since Converge applies the configuration broadly and does not offer a partial rollback\n\n**Workflow**\n\nCall GET /v2/blueprints/{blueprint_id}/versions/ to find the version_id you need\n\nCall this endpoint with both blueprint_id and version_id to retrieve the full settings\n\nUse the blueprint_id and blueprint_version_id together in a POST to /v2/converge to apply this version to a device\n", "parameters": [ { "in": "path", "name": "blueprint_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "version_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/blueprints_BlueprintV2" }, "message": { "type": "string" }, "code": { "type": "string", "enum": [ 201 ] } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object" }, "message": { "type": "string" }, "code": { "type": "string", "enum": [ 201 ] } } } } } } } } }, "/v2/custom-actions/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "blueprints_Custom Actions API" ], "description": "⚠️ Linux only. Custom actions apply exclusively to Linux-managed devices. This endpoint is not applicable to Android, iOS, or Windows devices.\n\nRetrieves all custom actions defined for the tenant.\nReturns a list of CustomActionRead objects representing every custom action in the tenant, including their name, type, state, position settings, options, and audit metadata. Supports ordering to control the sort order of results. Use this endpoint to enumerate available custom actions before assigning them to a Blueprint or deploying them to Linux devices.\n\n**About Custom Actions**\n\nCustom actions allow operators to define custom scripts and commands that can be surfaced on Linux devices, either within a Blueprint's settings sections or as device Quick Actions. Each custom action has a type (button, toggle, radio, or dropdown), a state (draft, active, or inactive), and one or more options, each of which contains a Linux platform script. Only active custom actions can be deployed to devices. Custom actions are managed separately from blueprints but referenced within Blueprint settings via position_in_blueprints.\n\n**Key Query Parameters**\n\nordering — Sort results by a specified field; prefix with - for descending order (e.g., -created_at for newest first)\n\n**Common Use Cases**\n\nList all custom actions before deciding which to include in a Blueprint V2 configuration\n\nAudit the state of all custom actions to identify which are active vs. draft or inactive\n\nRetrieve id values for use in subsequent GET, PUT, or DELETE calls on specific custom actions\n\n**Best Practices**\n\nFilter mentally by state in your integration logic: only active custom actions can be deployed to devices; drafts are not eligible\n\nUse ordering=-created_at to surface recently created or modified actions first\n\nPair with GET /v2/custom-actions/{custom_action_id}/ when you need the full option and script payload for a specific action\n\n**Workflow**\n\nCall GET /v2/custom-actions/ to retrieve the full list of tenant custom actions\n\nReview the state and position_in_blueprints fields to identify which actions are deployment-ready\n\nUse the returned id values to fetch, update, or delete individual custom actions as needed\n", "parameters": [ { "in": "query", "name": "ordering", "schema": { "type": "string" }, "description": "Order the results by a specific field (-field for descending order). Valid fields are 'name', 'created_at', 'updated_at', 'created_by', 'updated_by'.\n" }, { "in": "query", "name": "name", "schema": { "type": "string" }, "description": "Filter the results by name (partial match, case insensitive).\n" }, { "in": "query", "name": "type", "schema": { "type": "string" }, "description": "Filter by action type. Comma-separated list. Valid values: button, toggle, radio, dropdown.\n" }, { "in": "query", "name": "state", "schema": { "type": "string" }, "description": "Filter by action state. Comma-separated list. Valid values: draft, active, inactive.\n" }, { "in": "query", "name": "position_in_blueprints", "schema": { "type": "string" }, "description": "Filter by blueprint position. Comma-separated list. Valid values: none, blueprints_apps_and_configuration, blueprints_connectivity, blueprints_device_security, blueprints_display_and_branding, blueprints_esper_settings, blueprints_scripts, blueprints_files, blueprints_platform_services, blueprints_hardware_settings, blueprints_sound, blueprints_system_updates, blueprints_time_and_date.\n" }, { "in": "query", "name": "position_in_device_settings", "schema": { "type": "string" }, "description": "Filter by device settings position. Comma-separated list. Valid values: none, device_quick_settings.\n" }, { "in": "query", "name": "created_by", "schema": { "type": "integer" }, "description": "Filter by user ID who created the action.\n" }, { "in": "query", "name": "updated_by", "schema": { "type": "integer" }, "description": "Filter by user ID who last updated the action.\n" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Number of results to return per page.\n" }, { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "The initial index from which to return the results.\n" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "count": { "type": "integer", "format": "int64", "description": "The total number of custom actions" }, "next": { "type": "string", "nullable": true, "description": "The link to retrieve the next set of objects in the result set" }, "previous": { "type": "string", "nullable": true, "description": "The link to retrieve the previous set of objects in the result set" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/blueprints_CustomActionRead" } } } }, "message": { "type": "string" }, "code": { "type": "integer" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 400 ] } } } } } } } }, "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "blueprints_Custom Actions API" ], "description": "⚠️ Linux only. Custom actions apply exclusively to Linux-managed devices. This endpoint is not applicable to Android, iOS, or Windows devices.\n\nCreates a new custom action for the tenant.\n\nAccepts a CustomActionCreate body defining the action's name, UI component type, lifecycle state, blueprint and device placement, display properties, and one or more options — each option containing a Linux platform script with its interpreter. Returns the created CustomActionRead object on success. Returns 409 if a custom action with the same name already exists.\n\n**About Create Custom Action**\n\nCustom actions are operator-defined interactive controls that execute scripts on Linux devices. When created, a custom action is placed in a specified section of a Blueprint V2 (via position_in_blueprints) and/or surfaced in the device's Quick Actions panel (via position_in_device_settings). Each option within the action maps a UI label to a script that runs on the device when the user triggers that option. Only active custom actions are eligible for deployment; new actions can be created in draft state for review before activation.\n\n**Key Fields**\n\nname — Unique display name for the custom action (1–50 characters; must be unique within the tenant)\n\ntype — UI component type: button, toggle, radio, or dropdown\n\nstate — Lifecycle state: draft, active, or inactive; only active actions can be deployed\n\nposition_in_blueprints — The Blueprint section where this action will appear (e.g., blueprints_scripts, blueprints_apps_and_configuration, or none)\n\nposition_in_device_settings — Device-side placement: device_quick_settings or none\n\nproperties — Object containing description, info_message, and tooltip_message for the UI\n\noptions — Array of option objects, each with a label, a unique key UUID, and a scripts.linux object containing script (the script content), interpreter (e.g., bash, python3; defaults to bash), and an optional timeout_in_mins (integer, 2–35791394) specifying the maximum runtime in minutes before the script is terminated\n\n**Common Use Cases**\n\nCreate a button-type action that runs a diagnostic script on Linux devices from the Blueprint settings\n\nDefine a toggle-type action that enables or disables a system feature via a shell script\n\nBuild a dropdown-type action with multiple options, each mapping to a different script\n\n**Best Practices**\n\nCreate custom actions in draft state first; activate them only after validating the script logic\n\nEnsure name is unique within the tenant — the API returns 409 on conflict\n\nProvide meaningful label values in each option so device operators can identify which script they are triggering\n\nSpecify the interpreter explicitly (e.g., python3) rather than relying on the bash default when your script requires a different runtime\n\n**Workflow**\n\nDesign your script content and identify which Blueprint section or Quick Actions position the action should occupy\n\nBuild the CustomActionCreate payload: set name, type, state: \"draft\", positions, properties, and options with embedded scripts\n\nSubmit POST /v2/custom-actions/\n\nCapture the returned id and options[*].scripts.linux.script_id for future reference\n\nWhen ready, update the action to state: \"active\" via PUT /v2/custom-actions/{custom_action_id}/ to make it deployable\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/blueprints_CustomActionCreate" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/blueprints_CustomActionRead" }, "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 201 ] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" } }, "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 400 ] } } } } } }, "409": { "description": "Conflict - Custom Action name already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 409 ] } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 500 ] } } } } } } } } }, "/v2/custom-actions/{custom_action_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "blueprints_Custom Actions API" ], "description": "⚠️ Linux only. Custom actions apply exclusively to Linux-managed devices. This endpoint is not applicable to Android, iOS, or Windows devices.\n\nRetrieves the full details of a specific custom action by its unique ID.\nReturns a CustomActionRead object containing the action's name, type, state, blueprint and device placement, display properties, options (with script references), and audit fields including created_by, updated_by, created_at, and updated_at. Use this endpoint to inspect a custom action's current configuration and retrieve its associated script_id values before modifying or deploying it.\n\n**About Retrieve Custom Action**\n\nCustom actions are operator-defined scripts surfaced on Linux devices through Blueprint settings or device Quick Actions. The CustomActionRead response includes each option's scripts.linux.script_id — a UUID referencing the script content stored externally. To retrieve the actual script content, use GET /v2/scripts/{script_id}/ with that UUID.\n\n**Key Fields**\n\ncustom_action_id — UUID of the custom action to retrieve (path parameter, required)\n\nid — UUID of the custom action in the response body\n\nstate — Current lifecycle state: draft, active, or inactive\n\noptions[*].scripts.linux.script_id — UUID reference to the script content; use with GET /v2/scripts/{script_id}/ to fetch the actual script\n\nposition_in_blueprints / position_in_device_settings — Where this action is surfaced in Blueprint and device UI\n\ncreated_at / updated_at — Audit timestamps\n\n**Common Use Cases**\n\nInspect a custom action's current state and placement before deciding to activate or deactivate it\n\nRetrieve script_id values from the options to fetch and review the associated scripts\n\nConfirm that a custom action's properties labels and messages are correctly set before deploying it in a Blueprint\n\n**Best Practices**\n\nUse this endpoint before calling PUT /v2/custom-actions/{custom_action_id}/ to understand the current state of the action\n\nCross-reference script_id values with GET /v2/scripts/{script_id}/ to verify script content is correct before activating the action\n\nCheck the state field to confirm whether the action is eligible for deployment (active) before including it in a Blueprint\n\n**Workflow**\n\nObtain the custom_action_id from GET /v2/custom-actions/ or from the Console\n\nCall GET /v2/custom-actions/{custom_action_id}/ to retrieve the full action object\n\nReview state, options, and placement fields\n\nIf needed, use the script_id from each option's scripts.linux object to inspect the script content via GET /v2/scripts/{script_id}/\n", "parameters": [ { "in": "path", "name": "custom_action_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/blueprints_CustomActionRead" }, "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 200 ] } } } } } }, "404": { "description": "Custom Action not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 404 ] } } } } } } } }, "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "blueprints_Custom Actions API" ], "description": "⚠️ Linux only. Custom actions apply exclusively to Linux-managed devices. This endpoint is not applicable to Android, iOS, or Windows devices.\n\nUpdates an existing custom action by ID, modifying any combination of its name, type, state, placement, properties, and options.\nAccepts a CustomActionUpdate body where all fields are optional — only the fields provided will be updated. If options is included, it fully replaces the existing options list. Returns the updated CustomActionRead object on success. Returns 400 if the update is invalid (e.g., an invalid state transition) or 409 if the new name conflicts with an existing custom action.\n\n**About Update Custom Action**\n\nCustom action updates follow partial-update semantics for most fields, but options is a full replacement — supplying it overwrites all existing options and their associated scripts. State transitions follow lifecycle rules: only active custom actions can be deployed to Linux devices. Moving an action from active to inactive or draft will prevent it from being used in new Blueprint deployments.\n\n**Key Fields**\n\ncustom_action_id — UUID of the custom action to update (path parameter, required)\n\nname — Updated display name (1–50 characters; must remain unique within the tenant)\n\ntype — Updated UI component type: button, toggle, radio, or dropdown\n\nstate — Updated lifecycle state: draft, active, or inactive; only active actions are deployable\n\nposition_in_blueprints — Updated Blueprint section placement\n\nposition_in_device_settings — Updated device Quick Actions placement\n\nproperties — Replacement object for description, info_message, and tooltip_message\n\noptions — Replacement list of options; each option requires label, key UUID, and scripts.linux with script and interpreter; timeout_in_mins (integer, 2–35791394) is optional and sets the maximum script runtime in minutes\n\n**Common Use Cases**\n\nActivate a draft custom action by updating state to active when it's ready for deployment\n\nUpdate script content by supplying a new options array with revised scripts\n\nRename or reposition a custom action within Blueprint sections\n\n**Best Practices**\n\nRetrieve the current state of the action with GET /v2/custom-actions/{custom_action_id}/ before updating to avoid unintentional changes\n\nWhen updating options, include all options you want to retain — the list is fully replaced, not merged\n\nValidate state transitions: moving from active to inactive may affect Blueprints currently referencing this action\n\n**Workflow**\n\nRetrieve the current action with GET /v2/custom-actions/{custom_action_id}/\n\nBuild a CustomActionUpdate payload with only the fields you intend to change (or a full options replacement if updating scripts)\n\nSubmit PUT /v2/custom-actions/{custom_action_id}/\n\nConfirm the response reflects the updated fields and review the new updated_at timestamp\n", "parameters": [ { "in": "path", "name": "custom_action_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/blueprints_CustomActionUpdate" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/blueprints_CustomActionRead" }, "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 200 ] } } } } } }, "400": { "description": "Bad Request (validation error or invalid state transition)", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 400 ] } } } } } }, "404": { "description": "Custom Action not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 404 ] } } } } } }, "409": { "description": "Conflict - Custom Action name already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 409 ] } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 500 ] } } } } } } } }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "blueprints_Custom Actions API" ], "description": "⚠️ Linux only. Custom actions apply exclusively to Linux-managed devices. This endpoint is not applicable to Android, iOS, or Windows devices.\n\nPermanently deletes a custom action by its unique ID.\nReturns HTTP 200 on success. Returns 400 if the custom action is currently in an active state — active custom actions must be deactivated before they can be deleted. Returns 404 if the custom action does not exist. Deletion is irreversible and removes the action and all its associated option scripts.\n\n**About Delete Custom Action**\n\nCustom actions define scripts that can be embedded in Blueprint V2 configurations and deployed to Linux devices. Deleting an active custom action is blocked to prevent accidental removal of actions currently referenced in live blueprints. Before deleting, transition the action to inactive or draft state using PUT /v2/custom-actions/{custom_action_id}/, then verify it is not referenced by any active blueprints.\n\n**Key Fields**\n\ncustom_action_id — UUID of the custom action to delete (path parameter, required)\n\n**Common Use Cases**\n\nRemove a deprecated or unused custom action after it has been replaced by a newer one\n\nClean up test or draft custom actions that are no longer needed\n\nDecommission a custom action tied to a retired Linux device workflow\n\n**Best Practices**\n\nBefore deleting, update the action's state to inactive via PUT /v2/custom-actions/{custom_action_id}/ — the API blocks deletion of active actions (returns 400)\n\nConfirm that no active Blueprint V2 configurations reference this custom action before deleting\n\nArchive the script content by calling GET /v2/scripts/{script_id}/ for each option's script if you may need it later\n\n**Workflow**\n\nIf the action is active, update it to state: \"inactive\" via PUT /v2/custom-actions/{custom_action_id}/\n\nVerify that no live Blueprints reference this custom action\n\nCall DELETE /v2/custom-actions/{custom_action_id}/\n\nConfirm HTTP 200 response; the action will no longer appear in GET /v2/custom-actions/ results\n", "parameters": [ { "in": "path", "name": "custom_action_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 200 ] } } } } } }, "400": { "description": "Bad Request - Cannot delete active custom action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 400 ] } } } } } }, "404": { "description": "Custom Action not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 404 ] } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 500 ] } } } } } } } } }, "/v2/scripts/{script_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "blueprints_Custom Actions API" ], "description": "⚠️ Linux only. Scripts retrieved by this endpoint are associated with custom actions that run exclusively on Linux-managed devices.\n\nRetrieves the content of a specific script by its unique script ID.\nReturns a platformScript object containing the raw script content, the interpreter used to execute it (e.g., bash, python3), and — when configured — the optional timeout_in_mins. Script IDs are generated when a custom action is created and are referenced within the options[*].scripts.linux.script_id field of a CustomActionRead response. Use this endpoint to inspect or archive the exact script code associated with a custom action option before modifying or deleting it.\n\n**About Retrieve Script**\n\nScripts in Esper's custom actions system are stored as discrete objects in external storage, each identified by a UUID script_id. They are not directly editable in place — to update a script, you must supply a replacement options array in PUT /v2/custom-actions/{custom_action_id}/, which generates a new script_id. This endpoint provides read-only access to the raw script content, its interpreter metadata, and the timeout configuration.\n\n**Key Fields**\n\nscript_id — UUID of the script to retrieve (path parameter, required); obtained from a custom action's options[*].scripts.linux.script_id\n\nscript — The raw script content (string)\n\ninterpreter — The runtime used to execute the script (e.g., bash, sh, python, python3; defaults to bash)\n\ntimeout_in_mins — Optional maximum runtime in minutes before the script is terminated (integer, 2–35791394). Field is absent when not configured — existing scripts created before this field was introduced will not have it.\n\n**Common Use Cases**\n\nRetrieve and review script content before activating a custom action or including it in a Blueprint\n\nArchive the script code of a custom action option before replacing it with an updated version\n\nAudit which interpreter is configured for a script to ensure compatibility with the target Linux environment\n\n**Best Practices**\n\nObtain script_id values from the options array returned by GET /v2/custom-actions/{custom_action_id}/ — they are not independently discoverable\n\nScripts are immutable once created; to change script content, update the parent custom action via PUT /v2/custom-actions/{custom_action_id}/ with a new options array\n\nStore the retrieved script content in version control if the script logic is critical to your deployment workflow\n\n**Workflow**\n\nCall GET /v2/custom-actions/{custom_action_id}/ to retrieve the custom action and locate script_id values in options[*].scripts.linux.script_id\n\nCall GET /v2/scripts/{script_id}/ for each script you want to inspect\n\nReview the script content and interpreter field\n\nTo update the script, build a new options array and submit it via PUT /v2/custom-actions/{custom_action_id}/\n", "parameters": [ { "in": "path", "name": "script_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/blueprints_platformScript" }, "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 200 ] } } } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 403 ] } } } } } }, "404": { "description": "Script not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 404 ] } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 500 ] } } } } } } } } }, "/v2/background-scripts/": { "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "blueprints_Background Scripts API" ], "description": "Creates a new background script for the tenant.\n\nUploads a PowerShell script that Esper will execute on devices, depending on the always_run and frequency_in_mins fields.\n\n**About Background Scripts**\nBackground Scripts let a tenant run custom automation directly on managed devices (currently Windows, via the powershell interpreter) outside of Esper's built-in commands — for example, custom health checks, remediation logic, or integration with third-party tooling.\n\n**Key Fields / Query Parameters**\n- `script` — The script content to execute on devices\n- `interpreter` — Interpreter used to run the script — currently only powershell is supported\n- `always_run` — Whether the script runs continuously; when true, frequency_in_mins must be null\n- `frequency_in_mins` — Interval in minutes between executions; required when always_run is false\n- `timeout_in_mins` — Maximum runtime before the script is terminated; must be > 0, defaults to 60\n\n**Common Use Cases**\n- Running a custom health check or diagnostic script on a recurring schedule across a device fleet\n- Automating a remediation step that built-in commands don't cover\n- Integrating with a third-party monitoring or compliance tool via a script\n\n**Best Practices**\n- Set an appropriate timeout_in_mins so a misbehaving script doesn't run indefinitely on a device\n- Test a new script on a small blueprint/device scope before deploying broadly\n- Use always_run only for scripts genuinely meant to run continuously — otherwise set a frequency_in_mins to control execution cadence\n\n**Workflow**\n1. Write and test the PowerShell script content\n2. POST it to this endpoint with the desired always_run/frequency_in_mins/timeout_in_mins settings\n3. Reference the created background script from a Blueprint to deploy it to devices\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/blueprints_BackgroundScriptCreate" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/blueprints_BackgroundScriptRead" }, "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 201 ] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" } }, "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 400 ] } } } } } }, "409": { "description": "Conflict - Background Script name already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 409 ] } } } } } } } }, "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "blueprints_Background Scripts API" ], "description": "Retrieves all background scripts configured for the tenant.\n\nReturns the tenant's background scripts with optional filtering by name and always_run, and standard pagination.\n\n**About Background Scripts**\nBackground Scripts let a tenant run custom PowerShell automation on managed devices. This list endpoint is the primary way to review what scripts already exist before creating or reusing one.\n\n**Key Fields / Query Parameters**\n- `name` — Filter scripts by name\n- `always_run` — Filter to only continuously-running (or scheduled) scripts\n- `ordering` — Field to sort results by\n- `limit / offset` — Pagination controls\n\n**Common Use Cases**\n- Auditing all background scripts currently configured for the tenant\n- Finding an existing script to reuse or update rather than duplicating it\n- Reviewing which scripts are set to always_run versus scheduled\n\n**Best Practices**\n- Check this list before creating a new script to avoid duplicating existing automation\n- Filter by always_run when reviewing continuously-running scripts specifically, since these have the broadest device impact\n- Periodically review script content for scripts no longer in use\n\n**Workflow**\n1. GET this endpoint to review existing background scripts\n2. GET a specific script by ID to view its full content\n3. Create a new script via POST if none of the existing ones fit\n", "parameters": [ { "in": "query", "name": "ordering", "schema": { "type": "string" }, "description": "Order the results by a specific field (-field for descending order). Valid fields are 'name', 'created_at', 'updated_at', 'created_by', 'updated_by'.\n" }, { "in": "query", "name": "name", "schema": { "type": "string" }, "description": "Filter the results by name (partial match, case insensitive).\n" }, { "in": "query", "name": "always_run", "schema": { "type": "boolean" }, "description": "Filter the results by always_run flag.\n" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Number of results to return per page.\n" }, { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "The initial index from which to return the results.\n" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "count": { "type": "integer", "format": "int64", "description": "The total number of background scripts" }, "next": { "type": "string", "nullable": true, "description": "The link to retrieve the next set of objects in the result set" }, "previous": { "type": "string", "nullable": true, "description": "The link to retrieve the previous set of objects in the result set" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/blueprints_BackgroundScriptRead" } } } }, "message": { "type": "string" }, "code": { "type": "integer" } } } } } } } } }, "/v2/background-scripts/{background_script_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "blueprints_Background Scripts API" ], "description": "Retrieves a single background script by ID, including its full content.\n\nReturns the background script's metadata along with its full script content.\n\n**About Background Scripts**\nBackground Scripts let a tenant run custom PowerShell automation on managed devices. This detail endpoint is the only way to retrieve the actual script content, as opposed to the list endpoint which returns metadata only.\n\n**Key Fields / Query Parameters**\n- `background_script_id` — ID of the background script to retrieve\n\n**Common Use Cases**\n- Reviewing a script's full content before modifying or reusing it\n- Auditing exactly what code is running on devices via a specific background script\n- Confirming script content after an update to ensure it matches what was intended\n\n**Best Practices**\n- Use the list endpoint to find the background_script_id first, since it returns metadata only\n- Review full script content here before assigning it to additional Blueprints, especially for scripts you didn't author\n- Treat script content as sensitive if it includes credentials or internal configuration\n\n**Workflow**\n1. List background scripts to find the target background_script_id\n2. GET this endpoint to retrieve full script content\n3. Assign the script to a Blueprint to deploy it to devices\n", "parameters": [ { "in": "path", "name": "background_script_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/blueprints_BackgroundScriptDetailRead" }, "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 200 ] } } } } } }, "404": { "description": "Background Script not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer", "enum": [ 404 ] } } } } } } } } }, "/pipelines/v0/pipelines/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get all Pipelines for the Enterprise", "description": "List all pipelines for the enterprise. Retrieves all active (non-deleted) pipelines configured for the enterprise, including metadata such as name, description, active and validity status, archive state, timeout configuration, and whether the pipeline is set as the default. Results can be filtered by name or sorted alphabetically.\n\nAbout Pipelines\n\nA pipeline is a multi-stage workflow that executes a sequence of operations — such as app installs, configuration changes, or commands — across targeted device groups. Each pipeline consists of one or more stages, each with its own target list and operation list. Pipelines allow you to coordinate staged rollouts with configurable timeouts and sequencing across your device fleet.\n\nCommon use cases\n\nAuditing all pipelines configured for an enterprise, retrieving pipeline_id values needed to manage stages, target lists, or pipeline runs, identifying which pipelines are active or archived before triggering a run, and confirming the default pipeline configuration.\n\nBest Practices\n\nUse the name query parameter to filter results when working in enterprises with many pipelines. Use is_active and is_archived in the response to confirm a pipeline is in a runnable state before triggering a run. Always retrieve a pipeline_id from this endpoint before calling pipeline stage, target list, or run endpoints.\n\nWorkflow\n\n1. Call this endpoint to retrieve all pipelines and identify the pipeline_id for the pipeline you want to work with.\n2. Use GET /pipelines/v0/pipelines/{pipeline_id}/ to retrieve full details for a specific pipeline.\n3. Use GET /pipelines/v0/pipelines/{pipeline_id}/stages/ to inspect or modify the stages within a pipeline.", "operationId": "getPipelines", "tags": [ "pipelines_Pipelines" ], "parameters": [ { "in": "query", "name": "default", "schema": { "type": "boolean", "enum": [ true, false ] } }, { "in": "query", "name": "name", "description": "Filter by name", "schema": { "type": "string" } }, { "in": "query", "name": "ordering", "description": "Sorting pipelines based on the field name", "schema": { "type": "string", "enum": [ "name", "-name" ] } } ], "security": [ { "pipelines_SCAPIAuthToken": [] } ], "responses": { "200": { "description": "Pipelines list for the Enterprise", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/pipelines_Pipeline" } } } } } } } } } } }, "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Create a new Pipeline", "description": "Creates a new Pipeline for the calling enterprise, using the logged-in user's token.\n\nRequires a name in the request body; optional fields include description, is_default (default false), is_active (default true), and timeout_seconds (default 86400, i.e. 24 hours). Returns the created Pipeline object.\n\n**About Pipelines**\n\nA Pipeline is the top-level container in Esper's Pipelines system for orchestrating multi-step device operations. It's made up of ordered Stages, each with its own Target Lists (devices and/or Device Groups) and Operation Lists (the actions to perform); executing a Pipeline produces a Pipeline Run that tracks progress through statuses such as PENDING, QUEUED, PROCESSING, RUNNING, WAITING, COMPLETE, and finally SUCCESS or FAILURE.\n\n**Key Fields / Query Parameters**\n\n- name — required pipeline name\n- timeout_seconds — overall timeout for runs of this pipeline, in seconds, default 86400\n- is_default — marks this as the enterprise's default pipeline, default false\n- is_active — whether the pipeline is active, default true\n", "operationId": "createPipeline", "tags": [ "pipelines_Pipelines" ], "security": [ { "pipelines_SCAPIAuthToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Pipeline_POST" } } } }, "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_Pipeline" } } } } } }, "400": { "description": "Pipelines create error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_400_Bad_Data" } } } }, "401": { "description": "Pipelines create error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/pipelines/{pipeline_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get a Pipeline", "description": "Retrieves the details of a single Pipeline by ID.\n\nReturns the Pipeline's name, description, status flags (is_active, is_valid, is_visible, is_archived, is_default), and timeout_seconds for the given pipeline_id.\n\n**About Pipelines**\n\nA Pipeline is the top-level container in Esper's Pipelines system for orchestrating multi-step device operations, made up of ordered Stages, each with Target Lists and Operation Lists.\n", "operationId": "getPipeline", "tags": [ "pipelines_Pipelines" ], "security": [ { "pipelines_SCAPIAuthToken": [] } ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pipeline information", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_Pipeline" } } } } } } } }, "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Update a Pipeline", "description": "Updates an existing Pipeline's configuration.\n\nAll fields — name, description, is_active, is_default, and timeout_seconds — are optional in the request body, so only the fields you provide are changed on the Pipeline identified by pipeline_id.\n\n**About Pipelines**\n\nA Pipeline is the top-level container in Esper's Pipelines system for orchestrating multi-step device operations, made up of ordered Stages, each with Target Lists and Operation Lists.\n", "operationId": "updatePipeline", "tags": [ "pipelines_Pipelines" ], "security": [ { "pipelines_SCAPIAuthToken": [] } ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Pipeline_PUT" } } } }, "responses": { "200": { "description": "Updated Pipeline Information", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_Pipeline" } } } } } }, "400": { "description": "Pipelines update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_400_Bad_Data" } } } }, "401": { "description": "Pipelines update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Delete a Pipeline", "description": "Deletes a Pipeline by ID.\n\nPermanently removes the Pipeline identified by pipeline_id for the calling enterprise.\n\n**About Pipelines**\n\nA Pipeline is the top-level container in Esper's Pipelines system for orchestrating multi-step device operations, made up of ordered Stages, each with Target Lists and Operation Lists.\n", "operationId": "deletePipeline", "tags": [ "pipelines_Pipelines" ], "security": [ { "pipelines_SCAPIAuthToken": [] } ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted Pipeline Information", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_Pipeline" } } } } } }, "401": { "description": "Pipelines delete error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/pipelines/{pipeline_id}/stages/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get all Pipeline stages", "description": "Retrieves all Stages configured for a Pipeline.\n\nReturns a paginated list of Stage objects belonging to the specified pipeline, in the order they run; use this to inspect a pipeline's structure before triggering or editing it.\n\n**About Stages**\n\nA Stage is an ordered step within a Pipeline. Each Stage has Target Lists (defining which devices or Device Groups it targets) and Operation Lists (the actions it performs), and when a Pipeline Run executes, each Stage produces one Stage Run.\n", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "getPipelineStages", "tags": [ "pipelines_Stages" ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pipelines stages response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/pipelines_Stage" } } } } } } } } } } }, "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Create a Pipeline stage", "description": "Adds a new Stage to a Pipeline.\n\nSend a POST request with the Stage's details to append a new ordered step to the pipeline; the response returns the created Stage object, which you then attach Target Lists and Operation Lists to.\n\n**About Stages**\n\nA Stage represents one ordered step in a Pipeline's execution. A newly created Stage has no Target Lists or Operation Lists attached by default, so a Stage Run produced from it would be marked INVALID (no targets or no operations) until those are added.\n\n**Workflow**\n\n1. Create the Stage\n2. Attach one or more Target Lists (directly or via Device Groups) to define which devices it targets\n3. Attach one or more Operation Lists to define what actions it performs\n", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "createPipelineStage", "tags": [ "pipelines_Stages" ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Stage_POST" } } } }, "responses": { "200": { "description": "Pipelines stages create response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_Stage" } } } } } }, "400": { "description": "Stage create error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_400_Bad_Data" } } } } } } }, "/pipelines/v0/pipelines/{pipeline_id}/stages/{stage_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get a Pipeline Stage", "description": "Retrieves the details of a single Pipeline Stage by ID.\n\nReturns the full Stage object for the specified pipeline and stage; use this to inspect a specific step's configuration within a pipeline's execution order.\n\n**About Stages**\n\nA Stage is one ordered step within a Pipeline, holding the Target Lists (devices and/or Device Groups) and Operation Lists (actions) that run when the pipeline is executed.\n", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "getPipelineStage", "tags": [ "pipelines_Stages" ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string" } }, { "name": "stage_id", "in": "path", "description": "ID of the Stage", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pipelines stage get response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_Stage" } } } } } } } }, "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Update a Pipeline Stage", "description": "Updates the details of an existing Pipeline Stage.\n\nSend a PUT request with the updated Stage fields to modify a step in the pipeline; the response returns the updated Stage object.\n\n**About Stages**\n\nA Stage is one ordered step in a Pipeline. Its own configuration is managed separately from the Target Lists and Operation Lists attached to it, which are updated through their own dedicated endpoints.\n", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "updatePipelineStage", "tags": [ "pipelines_Stages" ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string" } }, { "name": "stage_id", "in": "path", "description": "ID of the Stage", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Stage_PUT" } } } }, "responses": { "200": { "description": "Updated Stage Information", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_Stage" } } } } } }, "400": { "description": "Stage update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_400_Bad_Data" } } } }, "401": { "description": "Stage update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Delete a pipeline stage", "description": "Deletes a Stage from a Pipeline.\n\nPermanently removes the specified Stage, along with its association to any attached Target Lists and Operation Lists, from the pipeline; the response returns the deleted Stage object.\n\n**About Stages**\n\nA Stage is one ordered step in a Pipeline's execution, containing the Target Lists and Operation Lists that define what devices it targets and what actions it runs as part of the pipeline's overall orchestration flow.\n", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "deletePipelineStage", "tags": [ "pipelines_Stages" ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string" } }, { "name": "stage_id", "in": "path", "description": "ID of the Stage", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted Stage Information", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_Stage" } } } } } }, "401": { "description": "Stage delete error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/stages/{stage_id}/targetlists/": { "get": { "description": "Retrieves all Target Lists currently attached to a Pipeline stage.\n\nReturns the Target Lists linked to the specified stage, which determine which devices or device groups the stage will act on when the pipeline runs.\n\n**About Stage Target Lists**\nPipelines orchestrate multi-step device operations through Stages, each of which executes against one or more Target Lists (collections of devices or device groups). Attaching a Target List to a Stage is what tells that step of the pipeline which devices to target.\n\n**Key Fields / Query Parameters**\n- `stage_id` — UUID of the Stage whose attached Target Lists you want to retrieve\n- `type` — Optional query filter to scope the returned Target Lists by type\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get all Target Lists attached to the Stage", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "getStageTargetLists", "tags": [ "pipelines_Stages" ], "parameters": [ { "name": "stage_id", "in": "path", "description": "ID of the Stage", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "type", "schema": { "type": "string", "enum": [ "groups", "devices", "collections" ] } } ], "responses": { "200": { "description": "All Targets Lists attached to the Stage", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/pipelines_TargetList" } } } } } } } } }, "401": { "description": "Target List get error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } }, "post": { "description": "Attaches an existing Target List to a Pipeline stage.\n\nLinks a Target List (identified by target_list_id) to the specified stage, so that the stage will act on the devices or device groups contained in that list when the pipeline runs.\n\n**About Stage Target Lists**\nPipelines orchestrate multi-step device operations through Stages, each of which executes against one or more Target Lists. This endpoint is how a Target List that already exists on the pipeline gets scoped to a specific stage.\n\n**Key Fields / Query Parameters**\n- `stage_id` — UUID of the Stage to attach the Target List to\n- `target_list_id` — Required — UUID of an existing Target List to attach\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Attach the Target List to the Stage", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "addStageTargetList", "tags": [ "pipelines_Stages" ], "parameters": [ { "name": "stage_id", "in": "path", "description": "ID of the Stage", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_StageTargetList_POST" } } } }, "responses": { "200": { "description": "Attach target list to a Stage", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_TargetList" } } } } } }, "401": { "description": "Target list attach error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/stages/{stage_id}/targetlists/{targetlist_id}/": { "delete": { "description": "Detaches a Target List from a Pipeline stage.\n\nRemoves the association between the specified Target List and stage; the Target List itself is not deleted, only its attachment to this stage.\n\n**About Stage Target Lists**\nDetaching a Target List from a stage changes which devices that stage acts on for future pipeline runs — it does not affect runs that have already executed, and the Target List remains available to attach elsewhere.\n\n**Key Fields / Query Parameters**\n- `stage_id` — UUID of the Stage\n- `targetlist_id` — UUID of the Target List to detach from the stage\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Detach the Target List from the Stage", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "deleteStageTargetList", "tags": [ "pipelines_Stages" ], "parameters": [ { "name": "stage_id", "in": "path", "description": "ID of the Stage", "required": true, "schema": { "type": "string" } }, { "name": "targetlist_id", "in": "path", "description": "ID of the Target List", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Detach target list from stage", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_TargetList" } } } } } }, "401": { "description": "Target list attach error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/stages/{stage_id}/operationlists/": { "get": { "description": "Retrieves all Operation Lists attached to a Pipeline stage.\n\nReturns the Operation Lists linked to the specified stage — these define the sequence of actions (Operations) that the stage performs on its Target Lists during a pipeline run.\n\n**About Operation Lists**\nAn Operation List groups the individual Operations that a Stage executes. Pipelines are built from Stages, and each Stage's behavior is defined by the Operation List(s) attached to it.\n\n**Key Fields / Query Parameters**\n- `stage_id` — UUID of the Stage whose Operation Lists you want to retrieve\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get all Operation Lists attached to the Stage", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "getStageOperationLists", "tags": [ "pipelines_Operation Lists" ], "parameters": [ { "name": "stage_id", "in": "path", "description": "ID of the Stage", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "All Operation Lists attached to the Stage", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/pipelines_OperationList" } } } } } } } } }, "401": { "description": "Operation List get error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } }, "post": { "description": "Creates a new Operation List for a Pipeline stage.\n\nCreates an Operation List scoped to the specified stage and pipeline, which will hold the ordered set of Operations that stage executes during a pipeline run.\n\n**About Operation Lists**\nAn Operation List groups the individual Operations that a Stage executes. Creating one is typically the first step in defining what a new pipeline stage actually does.\n\n**Key Fields / Query Parameters**\n- `stage_id` — UUID of the Stage this Operation List belongs to (path parameter)\n- `name` — Name of the Operation List\n- `description` — Free-text description of the Operation List's purpose\n- `pipeline_id` — UUID of the parent Pipeline\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Create an Operation list for the Stage", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "addStageOperationList", "tags": [ "pipelines_Operation Lists" ], "parameters": [ { "name": "stage_id", "in": "path", "description": "ID of the Stage", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_OperationList_POST" } } } }, "responses": { "200": { "description": "Attach Operation list to a Stage", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_OperationList" } } } } } }, "401": { "description": "Operation list attach error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/stages/{stage_id}/operationlists/{operationlist_id}/": { "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Update an Operation List", "description": "⚠️ **Android only.** Pipelines run on Android devices only.\n\nFully updates an existing Operation List for a Pipeline stage.\n\nReplaces the Operation List's metadata (name and description) for the specified stage. This is a full-replacement update, so include all writable fields in the request body. Returns the updated Operation List.\n\n**About Operation Lists**\nAn Operation List groups the individual Operations that a Stage executes. Updating it changes how the list is named and described, but it doesn't reorder or change the Operations inside it. Use the Operations endpoints for that.\n\n**Key Fields / Query Parameters**\n- `stage_id` — UUID of the Stage (path parameter)\n- `operationlist_id` — UUID of the Operation List to update (path parameter)\n- `name` — Updated name of the Operation List\n- `description` — Updated description\n\n**Common Use Cases**\n- Renaming an Operation List after a stage's purpose changes\n- Updating descriptions so pipeline runs are easier to read in reporting\n\n**Best Practices**\n- Read the current Operation List first so you don't overwrite fields you meant to keep\n- Use the Operations endpoints, not this one, to add, remove, or change actions\n\n**Workflow**\n1. Call `GET /pipelines/v0/stages/{stage_id}/operationlists/` to find the Operation List\n2. Build the full request body with your changes\n3. Call this endpoint and confirm the returned values\n", "operationId": "updatePipelineOperationList", "tags": [ "pipelines_Operation Lists" ], "security": [ { "pipelines_SCAPIAuthToken": [] } ], "parameters": [ { "name": "stage_id", "in": "path", "description": "ID of the Stage", "required": true, "schema": { "type": "string" } }, { "name": "operationlist_id", "in": "path", "description": "ID of the Operation List", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_OperationList" } } } }, "responses": { "200": { "description": "Updated Operation List Information", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_OperationList" } } } } } }, "400": { "description": "Operation List update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_400_Bad_Data" } } } }, "401": { "description": "Operation List update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Delete stage operation list", "description": "⚠️ **Android only.** Pipelines run on Android devices only.\n\nRemoves an Operation List from a Pipeline stage.\n\nDeletes the specified Operation List from the stage and returns the deleted record. The stage no longer runs the Operations in that list during future pipeline runs.\n\n**About Deleting Operation Lists**\nAn Operation List defines what a Stage does. Removing it changes the stage's behavior for every future run of the pipeline, so review the list's Operations before deleting it.\n\n**Key Fields / Query Parameters**\n- `stage_id` — UUID of the Stage (path parameter)\n- `operationlist_id` — UUID of the Operation List to delete (path parameter)\n\n**Common Use Cases**\n- Removing an obsolete set of actions from a stage\n- Cleaning up a stage before rebuilding its Operation List\n\n**Best Practices**\n- Check the list's Operations with `GET /pipelines/v0/operationlists/{operationlist_id}/operations/` before deleting\n- Avoid deleting an Operation List while a run of its pipeline is in progress\n\n**Workflow**\n1. Call `GET /pipelines/v0/stages/{stage_id}/operationlists/` to confirm the target\n2. Review its Operations\n3. Call this endpoint\n", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "deleteStageOperationList", "tags": [ "pipelines_Operation Lists" ], "parameters": [ { "name": "stage_id", "in": "path", "description": "ID of the Stage", "required": true, "schema": { "type": "string" } }, { "name": "operationlist_id", "in": "path", "description": "ID of the Operation List", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delete operation list from stage", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_OperationList" } } } } } }, "401": { "description": "Operation list detach error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/pipelines/{pipeline_id}/targetlists/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get all Target Lists in Pipeline", "description": "Retrieves all Target Lists defined in a Pipeline.\n\nReturns a paginated list of Target List objects for the specified pipeline; use this to see which sets of devices and Device Groups are configured as targets across the pipeline's stages.\n\n**About Target Lists**\n\nA Target List defines which devices a Stage acts on, either through individual Targets, attached Device Groups, or both. Target Lists are what a Pipeline's Stages point to at execution time to determine which devices receive each stage's operations.\n", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "getPipelineTargetLists", "tags": [ "pipelines_Target Lists" ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "All Target Lists in Pipeline", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/pipelines_TargetList" } } } } } } } } }, "401": { "description": "Target List get error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } }, "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Create a Target List", "description": "Creates a new Target List within a Pipeline.\n\nSend a POST request to define a new set of devices for the pipeline; the response returns the created Target List object, which you can then populate with individual Targets and/or Device Groups.\n\n**About Target Lists**\n\nA Target List is the mechanism by which a Pipeline's Stages determine which devices to act on — it can contain individual device Targets, whole Device Groups, or both. A Stage Run created against a Target List with no targets is marked INVALID.\n\n**Workflow**\n\n1. Create the Target List\n2. Add Targets and/or Device Groups to it\n3. Attach the Target List to a Stage so it's used when the pipeline runs\n", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "addPipelineTargetList", "tags": [ "pipelines_Target Lists" ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_TargetList_POST" } } } }, "responses": { "200": { "description": "All Targets in Target List", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_TargetList" } } } } } }, "401": { "description": "Target List get error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/pipelines/{pipeline_id}/targetlists/{targetlist_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get a Pipeline Target list", "description": "Retrieves the details of a single Target List by ID.\n\nReturns the full Target List object for the specified pipeline and target list; use this to inspect which devices or Device Groups a particular targeting definition includes.\n\n**About Target Lists**\n\nA Target List defines which devices — via individual Targets and/or Device Groups — a Pipeline's Stages act on when the pipeline runs.\n", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "getPipelineTargetList", "tags": [ "pipelines_Target Lists" ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string" } }, { "name": "targetlist_id", "in": "path", "description": "ID of the Target list", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get target list", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_TargetList" } } } } } }, "401": { "description": "Target list attach error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } }, "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Update a Pipeline Target List", "description": "Updates the details of an existing Target List.\n\nSend a PUT request with the updated fields to modify a Target List's configuration; the response returns the updated Target List object.\n\n**About Target Lists**\n\nA Target List defines the devices a Pipeline Stage acts on, either through individual Targets or attached Device Groups; its configuration is managed separately from the Targets and Device Groups it contains, which have their own dedicated endpoints.\n", "operationId": "updatePipelineTargetList", "tags": [ "pipelines_Target Lists" ], "security": [ { "pipelines_SCAPIAuthToken": [] } ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string" } }, { "name": "targetlist_id", "in": "path", "description": "ID of the Target List", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_TargetList" } } } }, "responses": { "200": { "description": "Updated Target List Information", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_TargetList" } } } } } }, "400": { "description": "Target List update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_400_Bad_Data" } } } }, "401": { "description": "Target List update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Delete a Pipeline Target list", "description": "Deletes a Target List from a Pipeline.\n\nPermanently removes the specified Target List, including its association with any Targets or Device Groups it contained; the response returns the deleted Target List object.\n\n**About Target Lists**\n\nA Target List defines the set of devices — individual Targets and/or Device Groups — that a Pipeline Stage acts on. Deleting one removes that targeting definition from the pipeline.\n", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "deletePipelineTargetList", "tags": [ "pipelines_Target Lists" ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string" } }, { "name": "targetlist_id", "in": "path", "description": "ID of the Target List", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delete target list", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_TargetList" } } } } } }, "401": { "description": "Target list delete error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/pipelines/{pipeline_id}/targetlists/{targetlist_id}/targets/": { "get": { "description": "Retrieves all individual device Targets in a Pipeline Target List.\n\nReturns each device-level Target record within the specified Target List, including its device identifier and active state.\n\n**About Targets**\nA Target represents a single device entry within a Target List. Target Lists can hold Targets directly (individual devices) as well as Device Groups; this endpoint returns only the individually-added device Targets.\n\n**Key Fields / Query Parameters**\n- `pipeline_id` — UUID of the parent Pipeline\n- `targetlist_id` — UUID of the Target List to list Targets from\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get all Targets in the Target List", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "getTargetListTargets", "tags": [ "pipelines_Targets" ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string" } }, { "name": "targetlist_id", "in": "path", "description": "ID of the Target List", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "All Targets in Target List", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/pipelines_Target" } } } } } } } } }, "401": { "description": "Target List get error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } }, "post": { "description": "Adds a device as an individual Target to a Pipeline Target List.\n\nCreates a new Target record scoped to the specified Target List, identifying a single device by its device_id so that pipeline stages using this Target List will act on it.\n\n**About Targets**\nA Target represents a single device entry within a Target List, as distinct from a Device Group (which adds many devices at once). Use this endpoint when a pipeline needs to target specific devices individually rather than an entire group.\n\n**Key Fields / Query Parameters**\n- `device_id` — Required — UUID of the device to add as a Target\n- `device_alias` — Optional display alias for the device within this Target List\n- `device_name` — Optional device name to store alongside the Target\n- `is_active` — Whether the Target is currently active and should be included in pipeline runs\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Create a target for the target list", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "createTargetListTargets", "tags": [ "pipelines_Targets" ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string" } }, { "name": "targetlist_id", "in": "path", "description": "ID of the Target List", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Target_POST" } } } }, "responses": { "200": { "description": "All Targets in Target List", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_Target" } } } } } }, "401": { "description": "Target List get error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/pipelines/{pipeline_id}/targetlists/{targetlist_id}/targets/{target_id}/": { "get": { "description": "Retrieves a single Target from a Pipeline Target List.\n\nReturns the details of one device-level Target record, identified by target_id, within the specified Target List.\n\n**About Targets**\nA Target represents a single device entry within a Target List. This endpoint is the single-record counterpart to the Target List endpoint.\n\n**Key Fields / Query Parameters**\n- `pipeline_id` — UUID of the parent Pipeline\n- `targetlist_id` — UUID of the Target List\n- `target_id` — UUID of the specific Target record to retrieve\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get one target from target list", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "getTargetListTarget", "tags": [ "pipelines_Targets" ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "targetlist_id", "in": "path", "description": "ID of the Target List", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "target_id", "in": "path", "description": "ID of the Target", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Target from Target List", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_Target" } } } } } }, "401": { "description": "Target List device delete error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } }, "put": { "description": "Updates a Target in a Pipeline Target List.\n\nUpdates the device_name and is_active fields of the specified Target record; this is a full-replacement update, so include both fields in the request. Not recommended for pipelines that are currently running.\n\n**About Targets**\nA Target represents a single device entry within a Target List. Updating a Target most commonly toggles is_active to include or exclude that device from future pipeline runs without removing the record entirely.\n\n**Key Fields / Query Parameters**\n- `target_id` — UUID of the Target to update\n- `device_name` — Updated display name for the device\n- `is_active` — Whether the Target should be included in pipeline runs\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Update a target in the target list", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "updateTargetListTarget", "tags": [ "pipelines_Targets" ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "targetlist_id", "in": "path", "description": "ID of the Target List", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "target_id", "in": "path", "description": "ID of the Target", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Target_PUT" } } } }, "responses": { "200": { "description": "Updated Target from Target List", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_Target" } } } } } }, "401": { "description": "Target List device delete error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } }, "delete": { "description": "Removes a Target from a Pipeline Target List.\n\nPermanently deletes the specified device-level Target record from the Target List; the device itself is unaffected, only its inclusion in this pipeline's scope.\n\n**About Targets**\nA Target represents a single device entry within a Target List. Deleting it removes that device from the pipeline's scope for future runs — it does not affect any pipeline runs that have already started.\n\n**Key Fields / Query Parameters**\n- `pipeline_id` — UUID of the parent Pipeline\n- `targetlist_id` — UUID of the Target List\n- `target_id` — UUID of the Target to delete\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Delete a Target or Device from a Target List", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "deleteTargetListTarget", "tags": [ "pipelines_Targets" ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "targetlist_id", "in": "path", "description": "ID of the Target List", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "target_id", "in": "path", "description": "ID of the Target", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted Target from Target List", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_Target" } } } } } }, "401": { "description": "Target List device delete error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/pipelines/{pipeline_id}/targetlists/{targetlist_id}/targets-bulk/": { "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Bulk add targets to a target list", "description": "Adds multiple targets to a target list. Creates target records if they don't exist, then links them to the target list. Existing targets in the list are left unchanged (skipped). Behaves the same as legacy /targets/ API. device_name should be provided for proper target run creation. device_alias can be provided as a direct property and will be stored in device_meta.", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "bulkAddTargetListTargets", "tags": [ "pipelines_Targets" ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "targetlist_id", "in": "path", "description": "ID of the Target List", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "description": "Array of device IDs (strings) or device objects with metadata", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "type": "string", "description": "Device ID" }, "example": [ { "device_id": "18d21907-a3b3-491b-9237-d835de82a3ef", "device_name": "ESPR-LAB-AAA03", "device_alias": "Actineon Edge 10A" }, { "device_id": "550e8400-e29b-41d4-a716-446655440002", "device_name": "ESPR-LAB-AAA04", "device_alias": "Actineon Edge 10B" } ] }, { "type": "array", "items": { "type": "object", "required": [ "device_id" ], "properties": { "device_id": { "type": "string", "description": "Device ID (UUID)" }, "device_name": { "type": "string", "description": "Device name (should be provided for proper target run creation)" }, "device_alias": { "type": "string", "description": "Device alias (optional, stored in device_meta)" }, "device_meta": { "type": "object", "description": "Device metadata (optional)" }, "args": { "type": "object", "description": "Custom arguments (optional)" }, "is_active": { "type": "boolean", "description": "Active status (optional, defaults to true)" } } } } ] } } } }, "responses": { "200": { "description": "Bulk add completed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Bulk add completed. 2 target(s) created, 5 target(s) added to list, 1 target(s) skipped." }, "content": { "type": "object", "properties": { "created_count": { "type": "integer", "description": "Number of new target records created", "example": 2 }, "added_count": { "type": "integer", "description": "Number of targets successfully added to the list", "example": 5 }, "skipped_count": { "type": "integer", "description": "Number of targets that were already in the list", "example": 1 }, "errors": { "type": "array", "items": { "type": "object" }, "description": "List of any errors encountered", "example": [] } } } } } } } }, "400": { "description": "Bad request - invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_500_Internal_Server_Error" } } } } } } }, "/pipelines/v0/pipelines/{pipeline_id}/targetlists/{targetlist_id}/devicegroups/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get all Device Groups in the Target List", "description": "Retrieves all Device Groups attached to a Target List.\n\nReturns a paginated list of Device Group objects linked to the specified Target List; use this to see which groups of devices a pipeline's targeting definition includes, as a complement to any individually listed Targets.\n\n**About Device Groups in Target Lists**\n\nA Target List can target devices either directly, via individual Targets, or in bulk by attaching a Device Group — every device in an attached group becomes a target for that Stage. This endpoint returns only the Device Group side of a Target List's targeting; individual Targets are retrieved via a separate endpoint.\n", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "getTargetListDeviceGroups", "tags": [ "pipelines_Device Groups" ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string" } }, { "name": "targetlist_id", "in": "path", "description": "ID of the Target List", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "All Device Groups in Target List", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/pipelines_TargetListDeviceGroup" } } } } } } } } }, "401": { "description": "Target List device group get error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } }, "post": { "description": "Adds a Device Group to a Pipeline Target List.\n\nLinks an existing Device Group to the specified Target List, so that pipeline stages using this Target List will act on every device currently in the group. Not recommended for pipelines that are currently running.\n\n**About Target List Device Groups**\nTarget Lists can scope a pipeline stage to individual device Targets, whole Device Groups, or both. Adding a Device Group is the fastest way to target a large, already-organized set of devices without adding them one at a time.\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Add a Device Group to the Target List", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "addTargetListDeviceGroups", "tags": [ "pipelines_Device Groups" ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string" } }, { "name": "targetlist_id", "in": "path", "description": "ID of the Target List", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_TargetListDeviceGroups_POST" } } } }, "responses": { "200": { "description": "Added Device group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_TargetListDeviceGroup" } } } }, "401": { "description": "Target List Device Group add error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/pipelines/{pipeline_id}/targetlists/{targetlist_id}/devicegroups/{devicegroup_id}/": { "delete": { "description": "Removes a Device Group from a Pipeline Target List.\n\nDetaches the specified Device Group from the Target List; the Device Group itself and its devices are unaffected, only its inclusion in this pipeline's scope. This does not stop any pipeline actions that are currently running.\n\n**About Target List Device Groups**\nTarget Lists can scope a pipeline stage to individual device Targets, whole Device Groups, or both. Removing a Device Group narrows the pipeline's scope without deleting the group or its devices.\n\n**Key Fields / Query Parameters**\n- `pipeline_id` — UUID of the parent Pipeline\n- `targetlist_id` — UUID of the Target List\n- `devicegroup_id` — UUID of the Device Group to remove from the Target List\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Delete Device Group from a Target List", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "deleteTargetListDeviceGroup", "tags": [ "pipelines_Device Groups" ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "targetlist_id", "in": "path", "description": "ID of the Target List", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "devicegroup_id", "in": "path", "description": "ID of the Device Group", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted Device Group from Target List", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } }, "401": { "description": "Target List device delete error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/pipelines/{pipeline_id}/targetlists/{targetlist_id}/devicegroups/{device_group_id}/devices/": { "get": { "description": "Retrieves all devices in a Device Group attached to a Pipeline Target List.\n\nReturns the devices that belong to the specified Device Group, as scoped through this Target List — this is the set of devices that pipeline stages using the Target List will act on via this group.\n\n**About Target List Device Groups**\nTarget Lists can scope a pipeline stage to whole Device Groups. This endpoint resolves a Device Group attachment down to its actual member devices, which is useful for confirming exactly who will be affected before a pipeline run.\n\n**Key Fields / Query Parameters**\n- `pipeline_id` — UUID of the parent Pipeline\n- `targetlist_id` — UUID of the Target List\n- `device_group_id` — UUID of the Device Group whose member devices you want to list\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get all Devices in the device group", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "getDeviceGroupDevices", "tags": [ "pipelines_Device Groups" ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "targetlist_id", "in": "path", "description": "ID of the Target List", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "device_group_id", "in": "path", "description": "ID of the Device Group", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "All Devices in Device group", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/pipelines_Device" } } } } } } } } }, "401": { "description": "Operation List get error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/operationlists/{operationlist_id}/operations/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get all Operations in the Operation List", "description": "Returns a paginated list of Operations belonging to a specific Operation List within a Pipeline. Use it to see all the individual operations queued or defined under one Operation List.\n\nSupports filtering by operation_type, and returns a count plus previous/next pagination links alongside the Operation records.\n\nThis is the Pipelines Operations endpoint. Use the [Operations API](https://api.esper.io/openapi/device_operations) for command operations (dispatch commands). \n\n**About Operations**\n\nEsper's Pipelines system orchestrates multi-step device operations. A Pipeline contains Stages, and each Stage can have Target Lists (Targets and/or Device Groups) and Operation Lists; an Operation List groups the individual Operations that get executed as part of a Stage. Pipeline Runs, Stage Runs, and Target Runs track execution against these definitions, with statuses including PENDING, QUEUED, PROCESSING, RUNNING, WAITING, COMPLETE, SUCCESS, FAILURE, CANCELLED, TIMEOUT (default 21 days), and INVALID.\n\n**Key Fields / Query Parameters**\n\n- operationlist_id — path parameter identifying the Operation List\n- operation_type — optional query filter to return only operations of a specific type\n\n**Common Use Cases**\n\n- Reviewing the individual operations configured under a Pipeline's Operation List before or after a run\n- Auditing an Operation List's contents when troubleshooting a Pipeline Run\n", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "getOperationListOperations", "tags": [ "pipelines_Operations" ], "parameters": [ { "name": "operationlist_id", "in": "path", "description": "ID of the Operation List", "required": true, "schema": { "type": "string" } }, { "name": "operation_type", "in": "query", "description": "Operation Type to filter on as defined in Operation_POST model", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "All Operations in Operation List", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/pipelines_Operation" } } } } } } } } }, "401": { "description": "Operation List get error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } }, "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Create an Operation for Operation List", "description": "Adds a new Operation to an existing Operation List in Esper's Pipelines system.\n\nSend the operation_type (e.g. LOCK, REBOOT, WIPE, INSTALL, SIMPLE_INSTALL, UNINSTALL, SET_KIOSK_APP, SET_WALLPAPER) and its args in the request body; the created Operation is returned and becomes one of the actions performed when the parent Stage runs.\n\nThis is the Pipelines Operations endpoint. Use the [Operations API](https://api.esper.io/openapi/device_operations) for command operations (dispatch commands). \n\n**About Operation Lists**\n\nAn Operation List holds one or more Operations — the individual device actions a Pipeline Stage performs against its targeted devices. Grouping Operations into a list lets a single stage execute multiple actions in sequence when its Stage Run processes. This is an authenticated SCAPI endpoint.\n\n**Key Fields / Query Parameters**\n\n- operation_type — the action to perform (e.g. LOCK, REBOOT, WIPE, INSTALL, SET_KIOSK_APP, etc.)\n- args — object containing the arguments for the selected operation_type\n\n**Common Use Cases**\n\n- Adding a device action to a stage's operation list while building out a pipeline\n", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "addOperationListOperations", "tags": [ "pipelines_Operations" ], "parameters": [ { "name": "operationlist_id", "in": "path", "description": "ID of the Operation List", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Operation_POST" } } } }, "responses": { "200": { "description": "Created operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_Operation" } } } } } }, "401": { "description": "Operation create error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/operationlists/{operationlist_id}/operations/{operation_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get an Operation from the operation list", "description": "Retrieves the details of a single Operation within an Operation List.\n\nReturns the Operation's operation_type, args, and metadata (created_by, updated_by, created_at, updated_at) for the given operation_id.\n\nThis is the Pipelines Operations endpoint. Use the [Operations API](https://api.esper.io/openapi/device_operations) for command operations (dispatch commands). \n\n**About Operation Lists**\n\nAn Operation List holds one or more Operations — the individual device actions a Pipeline Stage performs against its targeted devices. Operations are grouped into a list so a single stage can execute multiple actions in sequence. This is an authenticated SCAPI endpoint.\n", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "getOperationListOperation", "tags": [ "pipelines_Operations" ], "parameters": [ { "name": "operationlist_id", "in": "path", "description": "ID of the Operation list", "required": true, "schema": { "type": "string" } }, { "name": "operation_id", "in": "path", "description": "ID of the Operation", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get operation from operation list", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_Operation" } } } } } }, "401": { "description": "Operation get error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } }, "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Update an Operation", "description": "Updates an existing Operation in an Operation List.\n\nReplace the operation_type and/or args for the Operation identified by operation_id; the updated Operation is returned.\n\nThis is the Pipelines Operations endpoint. Use the [Operations API](https://api.esper.io/openapi/device_operations) for command operations (dispatch commands). \n\n**About Operation Lists**\n\nAn Operation List holds one or more Operations — the individual device actions a Pipeline Stage performs against its targeted devices. Operations are grouped into a list so a single stage can execute multiple actions in sequence. This is an authenticated SCAPI endpoint.\n", "operationId": "updateOperationListOperation", "tags": [ "pipelines_Operations" ], "security": [ { "pipelines_SCAPIAuthToken": [] } ], "parameters": [ { "name": "operationlist_id", "in": "path", "description": "ID of the Operation List", "required": true, "schema": { "type": "string" } }, { "name": "operation_id", "in": "path", "description": "ID of the Operation", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Operation" } } } }, "responses": { "200": { "description": "Updated Operation Information", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_Operation" } } } } } }, "400": { "description": "Operation update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_400_Bad_Data" } } } }, "401": { "description": "Operation update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Delete an Operation list operation", "description": "Removes a specific Operation from an Operation List.\n\nDeletes the Operation identified by operation_id from the given operationlist_id, so that action no longer runs when the associated Stage executes.\n\nThis is the Pipelines Operations endpoint. Use the [Operations API](https://api.esper.io/openapi/device_operations) for command operations (dispatch commands). \n\n**About Operation Lists**\n\nAn Operation List holds one or more Operations — the individual device actions a Pipeline Stage performs against its targeted devices. Operations are grouped into a list so a single stage can execute multiple actions in sequence. This is an authenticated SCAPI endpoint.\n", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "deleteOperationListOperation", "tags": [ "pipelines_Operations" ], "parameters": [ { "name": "operationlist_id", "in": "path", "description": "ID of the Operation List", "required": true, "schema": { "type": "string" } }, { "name": "operation_id", "in": "path", "description": "ID of the Operation", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delete operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_Operation" } } } } } }, "401": { "description": "Operation delete error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/runs/": { "get": { "description": "Retrieves all Pipeline Runs across the enterprise, with optional filtering.\n\nReturns Pipeline Run records for every pipeline in the enterprise, rather than scoped to a single pipeline, and supports filtering by status and pipeline name.\n\n**About Pipeline Runs (Enterprise-wide)**\nA Pipeline Run is a single execution instance of a Pipeline. This enterprise-wide endpoint is the broadest view of pipeline activity, useful for monitoring or dashboarding across all pipelines rather than checking one at a time.\n\n**Key Fields / Query Parameters**\n- `status` — Filter runs by their current status (e.g., pending, running, success, failure)\n- `pipeline_name` — Filter runs by the name of the parent pipeline\n- `ordering` — Field to sort results by\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get all Runs for the Pipelines in the Enterprise", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "getAllPipelineRuns", "tags": [ "pipelines_Pipeline Runs" ], "parameters": [ { "in": "query", "name": "status", "description": "Filter by pipeline run status", "schema": { "type": "string", "enum": [ "pending", "queued", "processing", "running", "waiting", "complete", "success", "failure", "cancelled", "invalid", "timeout" ] } }, { "in": "query", "name": "pipeline_name", "description": "Filter by pipeline name", "schema": { "type": "string" } }, { "in": "query", "name": "ordering", "description": "Sorting pipelines runs based on the field name", "schema": { "type": "string", "enum": [ "run_number", "-run_number", "status", "-status", "pipeline__name", "-pipeline__name", "started_at", "-started_at", "ended_at", "-ended_at" ] } } ], "responses": { "200": { "description": "All Runs for the Pipelines in the Enterprise", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/pipelines_PipelineRun" } } } } } } } } }, "401": { "description": "Pipeline run get error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/pipelines/{pipeline_id}/runs/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get all Runs for the Pipeline", "description": "Lists all Pipeline Runs created for a given Pipeline.\n\nSupports filtering by status and ordering by run_number, status, started_at, or ended_at (prefix a field with - for descending order).\n\n**About Pipeline Runs**\n\nEach time a Pipeline is executed it produces a Pipeline Run, which moves through PENDING (created) → QUEUED (queued for processing) → PROCESSING (scheduler preparing it) → RUNNING → WAITING (on a manual/automatic action) → COMPLETE (all Stage Runs processed), then SUCCESS or FAILURE. A run can also end as CANCELLED (user-cancelled), TIMEOUT (default 21 days), or INVALID (the pipeline has zero stages).\n\n**Key Fields / Query Parameters**\n\n- status — filter by run status (pending, queued, processing, running, waiting, complete, success, failure, cancelled, invalid, timeout)\n- ordering — sort by run_number, status, started_at, or ended_at\n", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "getPipelineRuns", "tags": [ "pipelines_Pipeline Runs" ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "status", "description": "Filter by pipeline run status", "schema": { "type": "string", "enum": [ "pending", "queued", "processing", "running", "waiting", "complete", "success", "failure", "cancelled", "invalid", "timeout" ] } }, { "in": "query", "name": "ordering", "description": "Sorting pipelines runs based on the field name", "schema": { "type": "string", "enum": [ "run_number", "-run_number", "status", "-status", "started_at", "-started_at", "ended_at", "-ended_at" ] } } ], "responses": { "200": { "description": "All Runs for the Pipeline", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/pipelines_PipelineRun" } } } } } } } } }, "401": { "description": "Pipeline run get error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } }, "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Create a Pipeline Run", "description": "Triggers a new run of the specified Pipeline.\n\nCreates a Pipeline Run for pipeline_id; the run starts in PENDING status and progresses through the scheduler before executing its Stages against their targeted devices.\n\n**About Pipeline Runs**\n\nEach time a Pipeline is executed it produces a Pipeline Run, which moves through PENDING → QUEUED → PROCESSING → RUNNING → WAITING → COMPLETE, then SUCCESS or FAILURE — or ends as CANCELLED, TIMEOUT (default 21 days), or INVALID (zero stages). Each Pipeline Run in turn produces one Stage Run per stage, which produces Target Runs for each targeted device.\n\n**Common Use Cases**\n\n- Kicking off a configured Pipeline (e.g. a multi-step device provisioning or update flow) on demand\n- Re-running a Pipeline after fixing its Stages, Target Lists, or Operation Lists\n\n**Workflow**\n\n1. Configure the Pipeline's Stages, Target Lists, and Operation Lists\n2. Create a Pipeline Run to execute the pipeline\n3. Track the run's status (and its Stage Runs / Target Runs) through to SUCCESS or FAILURE\n", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "createPipelineRun", "tags": [ "pipelines_Pipeline Runs" ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_PipelineRun_POST" } } } }, "responses": { "200": { "description": "Created Pipeline Run", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_PipelineRun" } } } } } }, "401": { "description": "Pipeline run create error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/pipelines/{pipeline_id}/runs/{pipeline_run_id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get Pipeline run by pipeline run id", "description": "Retrieves the details of a single Pipeline Run.\n\nReturns the run's status, run_number, status_meta, and timestamps (created_at, updated_at, started_at, ended_at) for the given pipeline_run_id.\n\n**About Pipeline Runs**\n\nA Pipeline Run tracks the execution of a Pipeline through statuses PENDING → QUEUED → PROCESSING → RUNNING → WAITING → COMPLETE, then SUCCESS or FAILURE — or CANCELLED, TIMEOUT (default 21 days), or INVALID (zero stages). It in turn produces one Stage Run per stage in the pipeline.\n", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "getPipelineRun", "tags": [ "pipelines_Pipeline Runs" ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string" } }, { "name": "pipeline_run_id", "in": "path", "description": "Run Id of pipeline run", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get Pipeline run", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_PipelineRun" } } } } } }, "401": { "description": "Operation get error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } }, "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Update a Pipeline Run", "description": "Updates a Pipeline Run for a specific pipeline.\n\nSend a PUT request with a new status value to transition the run programmatically; the request body accepts a single status field using the same enum values as the run lifecycle (pending, queued, processing, running, waiting, complete, success, failure, cancelled, invalid, timeout), and the response returns the updated Pipeline Run object.\n\n**About Pipeline Runs**\n\nA Pipeline Run is the record created each time a Pipeline executes, progressing through Esper's orchestration lifecycle from PENDING through QUEUED, PROCESSING, RUNNING, and WAITING to COMPLETE with a SUCCESS or FAILURE outcome (or CANCELLED, TIMEOUT after 21 days, or INVALID if the pipeline has zero stages). Each Pipeline Run produces one Stage Run per stage in the pipeline.\n\n**Key Fields / Query Parameters**\n\n- status — the lifecycle status to set on the run\n\n**Common Use Cases**\n\n- Cancel an in-progress Pipeline Run by setting status to cancelled\n", "operationId": "updatePipelineRun", "tags": [ "pipelines_Pipeline Runs" ], "security": [ { "pipelines_SCAPIAuthToken": [] } ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string" } }, { "name": "pipeline_run_id", "in": "path", "description": "Run id of pipeline run", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "$ref": "#/components/schemas/pipelines_PipelineRun_PUT" } } } }, "responses": { "200": { "description": "Updated Pipeline run information", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_PipelineRun" } } } } } }, "400": { "description": "Pipeline Run update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_400_Bad_Data" } } } }, "401": { "description": "Pipeline Run update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Delete a Pipeline Run", "description": "Deletes a specific Pipeline Run. Only non-running pipelines can be deleted.\n\nRemoves the Pipeline Run identified by pipeline_run_id under the given pipeline_id.\n\n**About Pipeline Runs**\n\nA Pipeline Run is the record produced each time a Pipeline is executed, tracking status through PENDING, QUEUED, PROCESSING, RUNNING, WAITING, COMPLETE, and finally SUCCESS or FAILURE (or CANCELLED, TIMEOUT, INVALID).\n", "operationId": "deletePipelineRun", "tags": [ "pipelines_Pipeline Runs" ], "security": [ { "pipelines_SCAPIAuthToken": [] } ], "parameters": [ { "name": "pipeline_id", "in": "path", "description": "ID of the Pipeline", "required": true, "schema": { "type": "string" } }, { "name": "pipeline_run_id", "in": "path", "description": "Run id of pipeline run", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted Pipeline run information", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_PipelineRun" } } } } } }, "400": { "description": "Pipeline Run update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_400_Bad_Data" } } } }, "401": { "description": "Pipeline Run update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/runs/{pipeline_run_id}/stageruns/": { "get": { "description": "Retrieves all Stage Runs for a specific Pipeline Run.\n\nReturns the stage-level execution records for the specified pipeline run, showing the status of each stage as the pipeline progressed.\n\n**About Stage Runs**\nA Stage Run is the execution instance of one Stage within a Pipeline Run. Since pipelines execute in ordered stages, this endpoint is the primary way to see how far a run has progressed and where it may have stalled or failed.\n\n**Key Fields / Query Parameters**\n- `pipeline_run_id` — UUID of the Pipeline Run to list Stage Runs for\n- `status` — Optional filter to narrow results to Stage Runs in a specific status\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get all Stage Runs for the Pipeline Run", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "getPipelineRunStageRuns", "tags": [ "pipelines_Stage Runs" ], "parameters": [ { "name": "pipeline_run_id", "in": "path", "description": "ID of the Pipeline Run", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Status of stage run", "required": false, "schema": { "type": "string", "enum": [ "pending", "queued", "processing", "running", "complete", "success", "failure", "cancelled", "invalid", "timeout" ] } } ], "responses": { "200": { "description": "All Stage Runs for the Pipeline Run", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/pipelines_StageRun" } } } } } } } } }, "401": { "description": "Stage run get error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/runs/{pipeline_run_id}/stageruns/{stage_run_id}/": { "get": { "description": "Retrieves a single Stage Run's details.\n\nReturns the full record for one Stage Run, identified by stage_run_id within the given pipeline_run_id.\n\n**About Stage Runs**\nA Stage Run is the execution instance of one Stage within a Pipeline Run. This single-record endpoint is the detail view behind the Stage Run list.\n\n**Key Fields / Query Parameters**\n- `pipeline_run_id` — UUID of the parent Pipeline Run\n- `stage_run_id` — UUID of the specific Stage Run to retrieve\n\n\n**Workflow**\n1. List Stage Runs for the pipeline run to find the stage_run_id\n2. GET this endpoint with pipeline_run_id and stage_run_id\n3. Use PUT on the same path if a manual status change is needed\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get Pipeline Stage run by stage run Id", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "getPipelineRunStageRun", "tags": [ "pipelines_Stage Runs" ], "parameters": [ { "name": "pipeline_run_id", "in": "path", "description": "ID of the Pipeline Run", "required": true, "schema": { "type": "string" } }, { "name": "stage_run_id", "in": "path", "description": "ID of pipeline stage run", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get pipeline run stage run", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_StageRun" } } } } } }, "401": { "description": "Operation get error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } }, "put": { "description": "Updates the status of a Stage Run.\n\nSets the status field of the specified Stage Run to one of the supported values (e.g., cancelled), typically used to manually intervene in a pipeline run. Only Cancelled is supported.\n\n**About Stage Runs**\nA Stage Run is the execution instance of one Stage within a Pipeline Run. Manually updating its status is generally reserved for exceptional cases, such as cancelling a stuck stage, since Stage Runs otherwise progress automatically as the pipeline executes.\n\n**Key Fields / Query Parameters**\n- `stage_run_id` — UUID of the Stage Run to update\n- `status` — New status — cancelled\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Update a Pipeline Stage Run", "operationId": "updatePipelineRunStageRun", "tags": [ "pipelines_Stage Runs" ], "security": [ { "pipelines_SCAPIAuthToken": [] } ], "parameters": [ { "name": "pipeline_run_id", "in": "path", "description": "ID of the Pipeline Run", "required": true, "schema": { "type": "string" } }, { "name": "stage_run_id", "in": "path", "description": "id of pipeline stage run", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "queued", "processing", "running", "complete", "success", "failure", "cancelled", "invalid", "timeout" ] } } } } } }, "responses": { "200": { "description": "Updated Pipeline Stage run information", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_StageRun" } } } } } }, "400": { "description": "Pipeline Stage Run update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_400_Bad_Data" } } } }, "401": { "description": "Pipeline Stage Run update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/stageruns/{stage_run_id}/operations/": { "get": { "description": "Retrieves the Operations executed as part of a Stage Run.\n\nReturns each Operation record executed for the specified Stage Run, reflecting the actual actions carried out (or attempted) during that stage's execution.\n\n**About Stage Run Operations**\nOperations are the individual actions defined in an Operation List and executed by a Stage. A Stage Run's Operations records show what actually happened during execution, as distinct from the Operation List's static definition of what should happen.\n\n**Key Fields / Query Parameters**\n- `stage_run_id` — UUID of the Stage Run whose executed Operations you want to retrieve\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get all Operations for the Stage Run", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "getPipelineStageRunOperations", "tags": [ "pipelines_Stage Runs" ], "parameters": [ { "name": "stage_run_id", "in": "path", "description": "Stage run Id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "All Operations for the Stage Run", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/pipelines_StageRunOperation" } } } } } } } } }, "401": { "description": "Stage run operation get error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/stageruns/{stage_run_id}/operations/{stage_run_operation_id}/": { "get": { "description": "Retrieves a single executed Operation from a Stage Run.\n\nReturns the full record for one Operation executed as part of the specified Stage Run, identified by stage_run_operation_id.\n\n**About Stage Run Operations**\nOperations are the individual actions defined in an Operation List and executed by a Stage. This single-record endpoint provides the detail view for one executed operation within a Stage Run.\n\n**Key Fields / Query Parameters**\n- `stage_run_id` — UUID of the parent Stage Run\n- `stage_run_operation_id` — UUID of the specific executed Operation to retrieve\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get single Operation for the Stage Run", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "getPipelineStageRunOperation", "tags": [ "pipelines_Stage Runs" ], "parameters": [ { "name": "stage_run_id", "in": "path", "description": "Stage run Id", "required": true, "schema": { "type": "string" } }, { "name": "stage_run_operation_id", "in": "path", "description": "Stage run operation Id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation for the Stage Run", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_StageRunOperation" } } } } } }, "401": { "description": "Stage run operation get error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/stageruns/{stage_run_id}/targetruns/": { "get": { "description": "Retrieves all Target Runs for a Stage Run.\n\nReturns the device-level execution records for the specified Stage Run, showing the per-device outcome of that stage, with optional filters by status and operation.\n\n**About Target Runs**\nA Target Run is the execution record of one device (Target) within a Stage Run — this is where per-device success/failure detail lives, since a single stage typically acts on many devices at once.\n\n**Key Fields / Query Parameters**\n- `stage_run_id` — UUID of the Stage Run to list Target Runs for\n- `status` — Optional filter by Target Run status\n- `stage_run_operation_id` — Optional filter to a specific executed Operation\n- `ordering` — Field to sort results by\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get all Target Runs for the Stage Run", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "getPipelineStageTargetRuns", "tags": [ "pipelines_Target Runs" ], "parameters": [ { "name": "stage_run_id", "in": "path", "description": "Stage run Id", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Status of target run", "schema": { "type": "string", "enum": [ "pending", "queued", "processing", "dispatched", "running", "complete", "success", "failure", "cancelled", "invalid", "timeout" ] } }, { "name": "stage_run_operation_id", "in": "query", "description": "Stage run Operation Id to filter on", "schema": { "type": "string", "format": "uuid" } }, { "name": "ordering", "in": "query", "description": "Sorting target runs based on status field", "schema": { "type": "string", "enum": [ "status", "-status" ] } } ], "responses": { "200": { "description": "All Target runs for the Stage Run", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/pipelines_TargetRun" } } } } } } } } }, "401": { "description": "Target run get error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } }, "post": { "description": "Creates a new Target Run for a Stage Run.\n\nAdds a device-level execution record to the specified Stage Run, identifying the Target (device) that the stage should now also act on. Not recommended for pipelines that are currently running. \n\n**About Target Runs**\nA Target Run is the execution record of one device (Target) within a Stage Run. Creating one directly is an advanced operation, typically used to add a device to an in-progress or newly created stage run outside of the normal automatic scoping from the stage's Target Lists.\n\n**Key Fields / Query Parameters**\n- `stage_run_id` — UUID of the Stage Run to add the Target Run to\n- `target_id` — UUID of the Target (device entry) this run applies to\n- `device_name` — Display name of the device\n- `device_alias` — Display alias of the device\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Create a Target Runs for Stage Run", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "createPipelineStageTargetRuns", "tags": [ "pipelines_Target Runs" ], "parameters": [ { "name": "stage_run_id", "in": "path", "description": "Stage run Id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_TargetRun_POST" } } } }, "responses": { "200": { "description": "Created Target Runs", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/pipelines_TargetRun" } } } } } } }, "401": { "description": "Target Run create error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/stageruns/{stage_run_id}/targetruns/{target_run_id}/": { "get": { "description": "Retrieves a single Target Run's details.\n\nReturns the full record for one device-level Target Run, identified by target_run_id within the specified Stage Run.\n\n**About Target Runs**\nA Target Run is the execution record of one device (Target) within a Stage Run. This single-record endpoint is the detail view behind the Target Run list.\n\n**Key Fields / Query Parameters**\n- `stage_run_id` — UUID of the parent Stage Run\n- `target_run_id` — UUID of the specific Target Run to retrieve\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get Target Run by Target Run ID", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "getPipelineStageTargetRun", "tags": [ "pipelines_Target Runs" ], "parameters": [ { "name": "stage_run_id", "in": "path", "description": "Stage run Id", "required": true, "schema": { "type": "string" } }, { "name": "target_run_id", "in": "path", "description": "Id of the Target Run", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get target run", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_TargetRun" } } } } } }, "401": { "description": "Operation get error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } }, "put": { "description": "Updates the status of a Target Run.\n\nSets the status (and optionally device_name) of the specified Target Run, typically used to manually intervene in a single device's execution within a stage. Only Cancelled is supported. \n\n**About Target Runs**\nA Target Run is the execution record of one device (Target) within a Stage Run. Manual status updates are generally reserved for exceptional cases, since Target Run status otherwise reflects the underlying device command's real progress.\n\n**Key Fields / Query Parameters**\n- `target_run_id` — UUID of the Target Run to update\n- `status` — New status — cancelled\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Update a Target Run", "operationId": "updatePipelineStageTargetRun", "tags": [ "pipelines_Target Runs" ], "security": [ { "pipelines_SCAPIAuthToken": [] } ], "parameters": [ { "name": "stage_run_id", "in": "path", "description": "Stage run Id", "required": true, "schema": { "type": "string" } }, { "name": "target_run_id", "in": "path", "description": "Id of the target run", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_TargetRun_PUT" } } } }, "responses": { "200": { "description": "Updated Target Run run information", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_TargetRun" } } } } } }, "400": { "description": "Target Run update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_400_Bad_Data" } } } }, "401": { "description": "Target Run update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/stageruns/{stage_run_id}/targetruns/{target_run_id}/command/": { "get": { "description": "Retrieves the device command status for a Target Run.\n\nReturns the status and details of the underlying device command that was dispatched for this Target Run, since a Target Run's execution is ultimately carried out via a command sent to the device.\n\n**About Target Run Command**\nEach Target Run corresponds to a command dispatched to a device. This endpoint exposes that command's live status, which is the most granular level of detail available for troubleshooting why a specific device's stage execution succeeded or failed.\n\n**Key Fields / Query Parameters**\n- `stage_run_id` — UUID of the parent Stage Run\n- `target_run_id` — UUID of the Target Run whose command status you want\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get status of the command running for Target run", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "getTargetRunCommandStatus", "tags": [ "pipelines_Target Runs" ], "parameters": [ { "name": "stage_run_id", "in": "path", "description": "ID of the stage run", "required": true, "schema": { "type": "string" } }, { "name": "target_run_id", "in": "path", "description": "Id of the target run", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Command processor request status", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_CommandResponse" } } } } } }, "401": { "description": "Command request create error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } }, "post": { "description": "Issues the device command processor request for a Target Run.\n\nTriggers dispatch of the underlying device command associated with this Target Run, typically as part of the pipeline engine's normal execution flow.\n\n**About Target Run Command**\nEach Target Run corresponds to a command dispatched to a device. This endpoint creates that command-processor request; it is primarily used internally by the pipeline execution flow rather than called ad hoc.\n\n**Key Fields / Query Parameters**\n- `stage_run_id` — UUID of the parent Stage Run\n- `target_run_id` — UUID of the Target Run to dispatch a command for\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Create an command processor request for Target Run", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "createTargetRunCommand", "tags": [ "pipelines_Target Runs" ], "parameters": [ { "name": "stage_run_id", "in": "path", "description": "ID of the stage run", "required": true, "schema": { "type": "string" } }, { "name": "target_run_id", "in": "path", "description": "Id of the target run", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_AndroidCommandRequest" } } } }, "responses": { "200": { "description": "Created command processor request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_CommandResponse" } } } } } }, "401": { "description": "Command request create error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_401_Unauthorized" } } } } } } }, "/pipelines/v0/stageruns/{stage_run_id}/targetruns/{target_run_id}/command/{command_id}/": { "put": { "description": "Updates a Target Run's device command, currently supporting cancellation.\n\nSets the request_status of the specified command to cancelled, stopping further execution of that device-level command. \n\n**About Target Run Command**\nEach Target Run corresponds to a command dispatched to a device. This endpoint is the mechanism for cancelling that command mid-flight, most commonly used to stop a stuck or unwanted device operation without waiting for it to time out.\n\n**Key Fields / Query Parameters**\n- `stage_run_id` — UUID of the parent Stage Run\n- `target_run_id` — UUID of the Target Run\n- `command_id` — UUID of the specific command to update\n- `request_status` — Currently only supports the value cancelled\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Update target run command information.", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "putTargetRunCommandStatus", "tags": [ "pipelines_Target Runs" ], "parameters": [ { "name": "stage_run_id", "in": "path", "description": "ID of the stage run", "required": true, "schema": { "type": "string" } }, { "name": "target_run_id", "in": "path", "description": "Id of the target run", "required": true, "schema": { "type": "string" } }, { "name": "command_id", "in": "path", "description": "Id of the command", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_CommandRequest_PUT" } } } }, "responses": { "200": { "description": "Command processor request status", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/pipelines_CommandResponse" } } } } } }, "400": { "description": "Target run command update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error_400_Bad_Data" } } } } } } }, "/sys/health": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Health check endpoint", "security": [ { "pipelines_SCAPIAuthToken": [] } ], "operationId": "getServiceHealth", "tags": [ "pipelines_System" ], "responses": { "200": { "description": "Pipelines health service response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Health" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipelines_Error" } } } } } } }, "/device/v0/devices/": { "get": { "x-badges": [ { "name": "Deprecated", "color": "red" } ], "security": [ { "device_apiKey": [] } ], "summary": "Get all devices in the tenant", "description": "**Deprecated.** Use [Get all devices (v2)](https://api.esper.io/openapi/device_device/paths/~1v2~1devices~1/get) instead.\n\nRetrieves a paginated list of all devices enrolled in the tenant across Android, Apple, Linux, and Windows.\n\n**About Get All Devices (Deprecated)**\n\nGET /v2/devices/ replaces this endpoint and is the recommended way to list devices. Build new integrations on v2, and move existing integrations off this endpoint.\n", "operationId": "getDeviceList", "tags": [ "device_Device" ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "type": "integer" } }, { "in": "query", "name": "ordering", "description": "Field to order the results by. Prefix with '-' to reverse the order.", "schema": { "type": "string", "enum": [ "alias", "created_at", "last_seen", "model", "os_version", "name", "onboarded_on", "serial", "provisioned_on", "battery_level", "dpc_version", "eea_version", "is_gms", "security_state", "wifi_ssid", "platform", "template_name" ] } }, { "in": "query", "name": "serial", "schema": { "type": "string" } }, { "in": "query", "name": "udid", "schema": { "type": "string" } }, { "in": "query", "name": "android_version", "schema": { "type": "string" } }, { "in": "query", "name": "ios_version", "schema": { "type": "string" } }, { "in": "query", "name": "ipados_version", "schema": { "type": "string" } }, { "in": "query", "name": "tvos_version", "schema": { "type": "string" } }, { "in": "query", "name": "windows_version", "schema": { "type": "string" } }, { "in": "query", "name": "state", "schema": { "type": "integer" } }, { "in": "query", "name": "battery_level_gte", "schema": { "type": "string" } }, { "in": "query", "name": "battery_level_lte", "schema": { "type": "string" } }, { "in": "query", "name": "is_gms", "schema": { "type": "boolean" } }, { "in": "query", "name": "active_connection", "schema": { "type": "string" } }, { "in": "query", "name": "group_multi", "description": "Filter by multiple group ID. Fetch the devices from groups matching with the IDs and its subgroup.", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "group_multi_immediate", "description": "Filter by multiple group IDs. Fetch the devices from groups matching with the IDs. Excludes devices in any subgroups.", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "assigned_blueprint_id", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "current_blueprint_id", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "current_blueprint_version_id", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "current_blueprint_version_id_net", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "platform", "schema": { "type": "string", "enum": [ "ANDROID", "APPLE", "LINUX", "WINDOWS" ] } }, { "in": "query", "name": "os", "schema": { "type": "string", "enum": [ "iOS", "iPadOS", "tvOS", "Android", "Linux", "Windows" ] } }, { "in": "query", "name": "device_source", "description": "a csv list of device sources [ABM, NON_ABM]", "schema": { "type": "string" } }, { "in": "query", "name": "tags", "description": "a csv list of tag UUID's", "schema": { "type": "string" } }, { "in": "query", "description": "Search devices by multiOS -> name, serial, imei, model. Apple -> udid. Android -> iccid, phone number, brand, wifi, manufacturer, hardware", "name": "search", "schema": { "type": "string" } }, { "in": "query", "name": "foundation_device_model_id", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "android_version_exact", "schema": { "type": "string" } }, { "in": "query", "name": "foundation_major_version", "schema": { "type": "integer" } }, { "in": "query", "name": "foundation_minor_version", "schema": { "type": "integer" } }, { "in": "query", "name": "foundation_build_number", "schema": { "type": "integer" } }, { "in": "query", "name": "airwave_tenant_model_id", "schema": { "type": "string" } }, { "in": "query", "name": "airwave_build_id", "schema": { "type": "string" } }, { "in": "query", "name": "airwave_build_number", "schema": { "type": "integer" } }, { "in": "query", "name": "is_seamless", "schema": { "type": "boolean" } }, { "in": "query", "name": "global_device_id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Device information for the Tenant", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/device_AndroidDevice" }, { "$ref": "#/components/schemas/device_AppleDevice" }, { "$ref": "#/components/schemas/device_LinuxDevice" }, { "$ref": "#/components/schemas/device_WindowsDevice" } ] } } } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_401_Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_500_Internal_Server_Error" } } } } } } }, "/device/v0/devices/{id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "device_apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the device", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "summary": "Get details of a Device", "description": "Retrieves the full detail record for a single device by its ID.\n\nReturns the same platform-specific device object (Apple, Android, Linux, or Windows) used in the device list, but scoped to one device, including hardware identifiers, OS version, connectivity, and current blueprint assignment.\n\n**About Get Device Detail**\n\nThis is the single-device counterpart to GET /device/v0/devices/, useful once you already have a device id and need its full current record rather than a filtered list. The response shape depends on the device's platform, so integrations should handle each of the possible device object types.\n\n**Common Use Cases**\n\nLooking up a device's full configuration and status before issuing a command or Converge action\n\nVerifying a device's current blueprint and OS version during troubleshooting\n\n**Best Practices**\n\nConfirm the device id is correct before relying on a 404 to mean the device doesn't exist, since it could also indicate the ID belongs to a different tenant\n\nUse GET /device/v0/devices/{id}/devicestate for a lighter-weight check when you only need current state rather than the full device record\n\n**Workflow**\n\nObtain the device id from the device list or from a prior command or operation response\n\nCall this endpoint to retrieve the full device record\n\nUse the device's platform and current_blueprint_version_id to decide on next steps\n", "operationId": "getDeviceRequest", "tags": [ "device_Device" ], "responses": { "200": { "description": "Details of the device", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "oneOf": [ { "$ref": "#/components/schemas/device_AppleDevice" }, { "$ref": "#/components/schemas/device_AndroidDevice" }, { "$ref": "#/components/schemas/device_LinuxDevice" }, { "$ref": "#/components/schemas/device_WindowsDevice" } ] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_400_Bad_Data" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_401_Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_500_Internal_Server_Error" } } } } } }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Delete a device. Currently supported by iOS, Linux and Windows devices.", "description": "Permanently deletes a single device record from Esper.\n\nTakes the device's UUID in the path and removes it from the tenant; supported only for iOS, iPadOs, tvOS, Windows, or Linux devices, not Android.\n\n**About Device Deletion**\n\nThis endpoint removes a device from Esper's device inventory, so treat it as a destructive, hard-to-reverse action. See help documentation on the recommended steps for each device, as removal steps can differ by OS and provisioning method.\n\n**Key Fields / Query Parameters**\n\n- id — UUID of the device to delete, passed in the path\n\n**Common Use Cases**\n\n- Removing decommissioned or retired iOS, Windows, or Linux devices from the fleet\n- Cleaning up stale device records after a factory reset or hardware swap\n\n**Best Practices**\n\n- See help documentation on the recommended steps for each OS and provisioning method\n- Confirm the device's platform before calling this endpoint, since it does not apply to Android devices\n- Verify the device ID via a GET call first if you're not certain it's the correct record\n", "operationId": "deleteDeviceRequest", "tags": [ "device_Device" ], "security": [ { "device_apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the device", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Details of the device", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "oneOf": [ { "$ref": "#/components/schemas/device_AppleDevice" }, { "$ref": "#/components/schemas/device_LinuxDevice" }, { "$ref": "#/components/schemas/device_WindowsDevice" } ] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_400_Bad_Data" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_401_Unauthorized" } } } }, "404": { "description": "Device not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_500_Internal_Server_Error" } } } } } } }, "/device/v0/devices/{id}/devicestate": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get details of Current Device State", "description": "Retrieves the current settings and state snapshot for a single device.\n\nReturns the DeviceSettings object representing the device's live configuration state, distinct from the broader device record returned by the main device detail endpoint.\n\n**About Get Device State**\n\nWhile GET /device/v0/devices/{id}/ returns a device's overall record (hardware, OS, blueprint assignment, and so on), this endpoint returns its current settings state specifically. It's a lighter-weight check when the only thing you need is the device's live configuration snapshot rather than its full profile.\n\n**Common Use Cases**\n\nChecking a device's current settings state without pulling its full device record\n\nConfirming a configuration change has actually taken effect on the device\n\n**Best Practices**\n\nUse this endpoint instead of the full device detail endpoint when polling repeatedly for state changes, to reduce response size\n\nCompare the returned state against the blueprint version a device was converged to, to confirm the Converge action applied as expected\n\n**Workflow**\n\nObtain the device id\n\nCall this endpoint to retrieve its current state\n\nCompare against the expected blueprint or command outcome to confirm the change took effect\n", "operationId": "getDeviceStateRequest", "tags": [ "device_Device" ], "security": [ { "device_apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the device", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Details of the current device state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_DeviceSettings" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_400_Bad_Data" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_401_Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_500_Internal_Server_Error" } } } } } } }, "/v2/devices/{id}/devicestate": { "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Receive device state report and publish to Kafka for drift detection", "description": "Submits a device state report so Esper can detect blueprint drift.\n\nAccepts a sparse report of device settings that have changed and records it against the device. Esper compares these reports with the device's assigned blueprint to detect drift. Returns 201 on success.\n\n**About Device State Reports**\nBlueprint drift happens when a device's actual settings no longer match its assigned blueprint. Device state reports feed that comparison. Drift results are available from the Blueprint Drift endpoints, such as `GET /v2/blueprint-drift/{deviceId}/status`.\n\n**Key Fields / Query Parameters**\n- `id` — UUID of the device (path parameter)\n- `device_settings` — Object containing only the settings keys that changed (required)\n- `event_ts` — Time of the change, in milliseconds since the Unix epoch\n\n**Common Use Cases**\n- Reporting setting changes that feed blueprint drift detection\n\n**Best Practices**\n- Send only changed keys in `device_settings`, not the full settings object\n- Include `event_ts` so reports can be ordered correctly\n\n**Workflow**\n1. Collect the settings that changed on the device\n2. Call this endpoint with `device_settings` and `event_ts`\n3. Check drift results with the Blueprint Drift endpoints\n", "operationId": "updateDeviceState", "tags": [ "device_Device" ], "security": [ { "device_apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the device", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "device_settings" ], "properties": { "event_ts": { "type": "number", "description": "Event timestamp in milliseconds since epoch" }, "device_settings": { "type": "object", "description": "Partial settings payload containing only changed keys (sparse object)", "additionalProperties": true } }, "additionalProperties": true } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_400_Bad_Data" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_401_Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_500_Internal_Server_Error" } } } } } } }, "/v2/devices/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "device_apiKey": [] } ], "summary": "Get all devices in the tenant", "description": "Retrieves a paginated list of all devices enrolled in the tenant, across all platforms, using the V2 device schema.\n\nReturns richer device records than the v0 equivalent, with expanded filter support including managed_by, policy_multi, template_multi, is_locked_down, extended search coverage, and esper_agent_version_name for Esper agent version filtering.\n\n**About List All Devices (V2)**\n\nThis is the current recommended device list endpoint. Compared to /api/device/v0/devices/, V2 adds several filters valuable for fleet management at scale: managed_by distinguishes blueprint-managed from template-managed devices; policy_multi and template_multi allow multi-value policy/template filtering; is_locked_down targets locked-down devices; and the search field covers more Android-specific identifiers including WiFi MAC address, SIM operator, network operator, and IP address. Results are returned as device objects.\n\n**Key Query Parameters**\n\nmanaged_by — Filter by management mode: BLUEPRINT or TEMPLATE\n\npolicy_multi — CSV list of policy names to filter by\n\ntemplate_multi — CSV list of template names to filter by\n\nis_locked_down — Filter to locked-down devices only\n\nesper_agent_version_name — Filter by Esper agent (DPC) version name\n\nfoundation_version — Full Foundry OS version string (e.g., os_version.major.minor.build or eea_version)\n\nsearch — Extended Android search: name, serial, IMEI, model, ICCID, phone, brand, WiFi, manufacturer, WiFi MAC, SIM operator, network operator, IP address\n\nAll v0 filters are also available: platform, os, group_multi, group_multi_immediate, assigned_blueprint_id, current_blueprint_id, current_blueprint_version_id_net, state, battery_level_gte/lte, tags, device_source, udid, serial\n\n**Common Use Cases**\n\nIdentifying all devices not yet on the latest blueprint version for targeted update campaigns\n\nFiltering by managed_by=TEMPLATE to locate devices still on legacy template management\n\nQuerying all locked-down devices by group for compliance auditing\n\n**Best Practices**\n\nPrefer this endpoint over /api/device/v0/devices/ for all new integrations\n\nUse platform as a CSV list (e.g., ANDROID,APPLE) to query multiple platforms in one call\n\nFor Foundry OS fleet management, use foundation_version or the granular foundation_major_version, foundation_minor_version, foundation_build_number filters\n\n**Workflow**\n\nChoose filters appropriate to the use case (group, platform, blueprint version, policy, etc.)\n\nCall with limit and offset for pagination\n\nIterate results, using next for subsequent pages; branch on the platform field to handle per-platform schema differences\n", "tags": [ "device_Device" ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 10, "maximum": 1000 } }, { "in": "query", "name": "offset", "schema": { "type": "integer" } }, { "in": "query", "name": "cursor", "description": "Opaque cursor token for cursor-based pagination.\n- Use `start` to begin from the first page\n- Use the `next_cursor` value from previous response for subsequent pages\n- Use the `prev_cursor` value from previous response to navigate backward\n- When provided, offset parameter is ignored\n", "schema": { "type": "string", "example": "start" } }, { "in": "query", "name": "ordering", "description": "Field to order the results by. Prefix with '-' to reverse the order.", "schema": { "type": "string", "enum": [ "alias", "created_at", "last_seen", "model", "os_version", "name", "serial", "provisioned_on", "battery_level", "dpc_version", "eea_version", "is_gms", "security_state", "wifi_ssid", "platform", "template_name", "policy_name", "state" ] } }, { "in": "query", "name": "serial", "schema": { "type": "string" } }, { "in": "query", "name": "udid", "schema": { "type": "string" } }, { "in": "query", "name": "android_version", "schema": { "type": "string" } }, { "in": "query", "name": "ios_version", "schema": { "type": "string" } }, { "in": "query", "name": "ipados_version", "schema": { "type": "string" } }, { "in": "query", "name": "tvos_version", "schema": { "type": "string" } }, { "in": "query", "name": "windows_version", "schema": { "type": "string" } }, { "in": "query", "name": "state", "schema": { "type": "string" } }, { "in": "query", "name": "battery_level_gte", "schema": { "type": "string" } }, { "in": "query", "name": "battery_level_lte", "schema": { "type": "string" } }, { "in": "query", "name": "is_gms", "schema": { "type": "boolean" } }, { "in": "query", "name": "active_connection", "schema": { "type": "string" } }, { "in": "query", "name": "group_multi", "description": "Filter by multiple group ID. Fetch the devices from groups matching with the IDs and its subgroup.", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "group_multi_immediate", "description": "Filter by multiple group IDs. Fetch the devices from groups matching with the IDs. Excludes devices in any subgroups.", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "assigned_blueprint_id", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "current_blueprint_id", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "current_blueprint_version_id", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "current_blueprint_version_id_net", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "platform", "description": "a csv list of platforms [ANDROID, APPLE, LINUX, WINDOWS]", "schema": { "type": "string" } }, { "in": "query", "name": "os", "schema": { "type": "string", "enum": [ "iOS", "iPadOS", "tvOS", "Android", "Linux", "Windows" ] } }, { "in": "query", "name": "device_source", "description": "a csv list of device sources [ABM, NON_ABM]", "schema": { "type": "string" } }, { "in": "query", "name": "managed_by", "schema": { "type": "string", "enum": [ "BLUEPRINT", "TEMPLATE" ] } }, { "in": "query", "name": "template_multi", "description": "a csv list of template names", "schema": { "type": "string" } }, { "in": "query", "name": "policy_multi", "description": "a csv list of policy names", "schema": { "type": "string" } }, { "in": "query", "description": "Search devices by multiOS -> Name, Serial, IMEI, Model, WiFi SSID, Apple UDID, ICCID1, ICCID2, Brand, Manufacturer, Hardware, WiFi MAC Address, SIM Operator, Network Operator and IP Address.", "name": "search", "schema": { "type": "string" } }, { "in": "query", "name": "foundation_device_model_id", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "android_version_exact", "schema": { "type": "string" } }, { "in": "query", "name": "foundation_major_version", "schema": { "type": "integer" } }, { "in": "query", "name": "foundation_minor_version", "schema": { "type": "integer" } }, { "in": "query", "name": "foundation_build_number", "schema": { "type": "integer" } }, { "in": "query", "name": "airwave_tenant_model_id", "schema": { "type": "string" } }, { "in": "query", "name": "airwave_build_id", "schema": { "type": "string" } }, { "in": "query", "name": "airwave_build_number", "schema": { "type": "integer" } }, { "in": "query", "name": "foundation_version", "description": "Filter by one or more full foundation version strings (os_version.major.minor.build or eea_version). Multiple values can be passed as a comma-separated list (e.g. ?foundation_version=1.0-arm64-20210617-RELEASE,1.0-sb30-20210302-DEBUG), consistent with other multi-value filters.", "schema": { "type": "string" } }, { "in": "query", "name": "esper_agent_version_name", "description": "Filter devices by Esper agent version name (DPC version)", "schema": { "type": "string" } }, { "in": "query", "name": "tags", "description": "a csv list of tag ids", "schema": { "type": "string" } }, { "in": "query", "name": "is_locked_down", "schema": { "type": "boolean" } }, { "in": "query", "name": "global_device_id", "schema": { "type": "string" } }, { "in": "query", "name": "ungrouped_only", "description": "When true, returns only devices that are not associated with any group", "schema": { "type": "boolean" } }, { "in": "query", "name": "fields", "description": "Sparse fieldset: comma-separated list of top-level response field names to return (e.g. `fields=id,name,created_at`).\n- `id` is always included in the response regardless of whether it is requested.\n- Only top-level fields are supported; nested sub-fields (e.g. within `hardware_info`) cannot be selected individually.\n- Requesting an unknown field name returns a 400 error.\n- Omit this parameter to receive the full device object.\n", "schema": { "type": "string", "example": "id,name,created_at" } } ], "responses": { "200": { "description": "Device information for the Tenant.\nResponse format depends on pagination type used:\n- **Offset-based**: Returns `count`, `prev`, `next` (URLs), `results`\n- **Cursor-based**: Returns `results`, `next_cursor`, `prev_cursor`\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "oneOf": [ { "$ref": "#/components/schemas/device_OffsetPaginatedDeviceList" }, { "$ref": "#/components/schemas/device_CursorPaginatedDeviceList" } ] } } } } } }, "400": { "description": "Bad Request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_400_Bad_Data" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_401_Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_500_Internal_Server_Error" } } } } } } }, "/v2/devices/{id}": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "device_apiKey": [] } ], "summary": "Retrieve detailed device information.", "description": "Retrieves comprehensive details for a single enrolled device by UUID, using the V2 device schema.\n\nReturns a V2 platform-typed device record with richer fields than the v0 equivalent, for all supported Esper-managed platforms.\n\n**About Get Device Details (V2)**\n\nThis is the recommended endpoint for single-device lookups in new integrations. The V2 device schema provides additional fields compared to the v0 schema and aligns with the richer data model returned by /api/v2/devices/. Like the list endpoint, the response is polymorphic — the exact fields depend on the device platform. \n\n**Key Fields**\n\nid (path) — Esper device UUID (required)\n\n**Common Use Cases**\n\nFetching full device context before constructing a pipeline or operation\n\nRetrieving V2-specific fields like Foundry OS version, Esper agent version, or lock-down state\n\nIntegrating device data into external ITSM, asset management, or monitoring systems\n\n**Best Practices**\n\nPrefer this over /api/device/v0/devices/{id}/ for all new integrations\n\nInspect the platform field to determine which V2 schema variant applies before parsing\n\nUse the heartbeat endpoints for lightweight connectivity checks rather than polling this endpoint\n", "tags": [ "device_Device" ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the device", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Detailed information of the device", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "oneOf": [ { "$ref": "#/components/schemas/device_AppleDeviceV2" }, { "$ref": "#/components/schemas/device_AndroidDeviceV2" }, { "$ref": "#/components/schemas/device_LinuxDeviceV2" }, { "$ref": "#/components/schemas/device_WindowsDeviceV2" } ] } } } } } }, "400": { "description": "Bad Request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_400_Bad_Data" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_401_Unauthorized" } } } }, "404": { "description": "Device not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_500_Internal_Server_Error" } } } } } } }, "/v2/devices/{id}/tags/": { "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "device_apiKey": [] } ], "summary": "Update tags associated with a device.", "description": "Updates the tags associated with a device.\n\nApplies tag changes incrementally via add and remove lists, for a single enrolled Apple, Linux, or Windows device identified by UUID.\n\n**About Device Tags**\nDevice tags are free-form labels that can be used to organize and filter devices (for example, in the Device Telemetry report's tags filter) independently of device groups. This endpoint currently applies to Apple, Linux, and Windows devices.\n\n**Key Fields / Query Parameters**\n- `id` — UUID of the device to update tags for\n- `add` — List of tags to add to the device\n- `remove` — List of tags to remove from the device\n\n**Common Use Cases**\n- Tagging a device for a temporary pilot or campaign without changing its device group\n- Bulk-organizing devices by attributes not covered by groups (e.g., ownership, condition, project)\n- Removing outdated tags as a device's status changes\n\n**Best Practices**\n- Use add/remove incrementally rather than trying to replace the full tag set in one call, since the API is additive/subtractive by design\n- Keep a consistent tagging convention across the fleet so tags remain useful for filtering in reports\n- Confirm the device platform — this endpoint currently supports Apple, Linux, and Windows devices, not Android\n", "tags": [ "device_Device" ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the device", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_DeviceTagsRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/device_DeviceTagsResponse" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_401_Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_500_Internal_Server_Error" } } } } } } }, "/device/v0/heartbeat/{id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get heartbeat of a device which contains last seen information", "description": "Retrieves the last-seen heartbeat record for a single device, including its most recent check-in timestamp.\n\nReturns the device UUID, the last-seen timestamp, and a legacy status flag indicating whether the device was seen within the last 30 minutes (1) or not (0).\n\n**About Get Device Heartbeat (v0)**\n\nThe heartbeat endpoint provides a lightweight alternative to a full device fetch when only connectivity recency is needed. The status field is a legacy binary indicator (1 = seen in the last 30 minutes, 0 = not seen) and should not be used as the sole signal for device availability in new integrations — use the timestamp directly for more precise evaluation. For bulk heartbeat queries across all devices within a time window, use /api/v2/heartbeat/.\n\n**Key Fields**\n\ndevice_id — UUID of the device\n\ntimestamp — ISO 8601 datetime of the device's last check-in\n\nstatus — Legacy field: 1 if last seen within 30 minutes, 0 otherwise\n\n**Common Use Cases**\n\nConfirming a specific device is online before triggering a remote operation\n\nDisplaying last-seen timestamps in a device monitoring dashboard\n\nLightweight polling loop to detect when a device comes back online\n\n**Best Practices**\n\nUse timestamp rather than status for precision — status is a legacy 30-minute binary bucket and is not suitable for finer-grained availability logic\n\nFor checking connectivity across many devices in a time window, use /api/v2/heartbeat/ instead\n\nAvoid polling this endpoint at high frequency; prefer event-driven or scheduled checks\n", "operationId": "getDeviceHeartbeat", "tags": [ "device_Device Heartbeat" ], "security": [ { "device_apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the device", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Last seen details of the device", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/device_EsperDeviceHeartbeat" } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_401_Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_500_Internal_Server_Error" } } } } } } }, "/v2/heartbeat/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get list of heartbeat for all devices", "description": "Retrieves heartbeat records for all devices whose last-seen timestamp falls within a specified date-time range.\n\nRequires last_seen_gt and last_seen_lt query parameters to define the time window, and optionally filters by platform. Returns a paginated list of EsperDeviceHeartbeat records, each containing device UUID, last-seen timestamp, and a legacy status flag.\n\n**About List Device Heartbeats (V2)**\n\nThis endpoint enables bulk connectivity queries across the entire device fleet, useful for fleet health monitoring, SLA reporting, and identifying devices that have gone silent over a defined period. The required time window filters mean queries are always bounded, preventing inadvertent large data pulls. The platform filter can be used to narrow results to a specific OS family. As with the single-device heartbeat endpoint, the status field is a legacy 30-minute binary indicator; use timestamp values directly for precision analysis.\n\n**Key Query Parameters**\n\nlast_seen_gt (required) — Start of the time window in ISO 8601 format (e.g., 2024-01-01T00:00:00Z)\n\nlast_seen_lt (required) — End of the time window in ISO 8601 format\n\nplatform — Optional platform filter: ANDROID, APPLE, LINUX, or WINDOWS\n\nlimit / offset — Pagination controls\n\n**Common Use Cases**\n\nGenerating daily fleet health reports showing which devices checked in during the past 24 hours\n\nIdentifying devices that have gone silent (not seen within a defined window) for incident response\n\nProducing SLA-aligned uptime evidence for specific device cohorts\n\n**Best Practices**\n\nKeep the time window reasonably narrow for large fleets to limit result set size and response latency\n\nUse platform to scope queries when platform-specific reporting is needed\n\nUse timestamp from each result record for precise analysis; do not rely on the legacy status field for business logic\n\n**Workflow**\n\nDefine the time window using last_seen_gt and last_seen_lt (both required)\n\nOptionally add platform to narrow results\n\nPaginate through results; devices appearing in the result set were seen within the window\n", "operationId": "getDeviceHeartbeatList", "tags": [ "device_Device Heartbeat" ], "security": [ { "device_apiKey": [] } ], "parameters": [ { "name": "last_seen_gt", "in": "query", "description": "Specify the starting date and time for device lookup in the format (2023-08-29T00:00:00Z).", "required": true, "schema": { "type": "string", "format": "date-time", "example": "2023-08-29T00:00:00Z" } }, { "name": "last_seen_lt", "in": "query", "description": "Specify the end date and time for device lookup in the format (2023-08-30T00:00:00Z).", "required": true, "schema": { "type": "string", "format": "date-time", "example": "2023-08-30T00:00:00Z" } }, { "name": "platform", "in": "query", "description": "platform of the device", "schema": { "type": "string", "enum": [ "ANDROID", "APPLE", "LINUX", "WINDOWS" ] } }, { "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Last seen details of the device", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/device_DeviceLastSeen" } } } } } }, "400": { "description": "Device create error - Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_400_Bad_Data" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_401_Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_500_Internal_Server_Error" } } } } } } }, "/v2/devices/{deviceId}/device-apps/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "device_apiKey": [] } ], "summary": "Get all apps for a device in the tenant", "description": "Retrieves a paginated list of every app installed on a specific device.\n\nReturns each app's DeviceAppsResponse record, filterable by app type such as VPP, tenant-uploaded iOS or Windows apps, Esper iOS apps, or webclips.\n\n**About Get Device Apps**\n\nThis is the v2 device-scoped app inventory, showing exactly what's installed on one device across its supported app types. It complements the tenant-wide app catalogs (Tenant Apps, Tenant Esper Apps, VPP) by showing installation state on a specific device rather than what's available to install.\n\n**Key Fields / Query Parameters**\n\napp type — filters by one or more app types, comma-separated, for example VPP, TENANT_IOS, or WEBCLIP\n\n**Common Use Cases**\n\nAuditing exactly which apps are installed on a specific device\n\nConfirming an app installed through a command or Converge action actually landed on the target device\n\nFiltering by app type to check only VPP-licensed apps or only webclips on a device\n\n**Best Practices**\n\nFilter by app type when you only care about one category, rather than paging through every installed app\n\nCross-reference results against the Tenant Apps or Tenant Esper Apps catalog to confirm a device has the expected version installed\n\n**Workflow**\n\nObtain the deviceId\n\nCall this endpoint, optionally filtering by app type\n\nCompare the results against the expected app list from a blueprint or command\n", "tags": [ "device_Device Apps" ], "parameters": [ { "name": "deviceId", "in": "path", "description": "ID of the device", "required": true, "schema": { "type": "string" } }, { "name": "app type", "in": "query", "description": "App Type to filter list by, supports multiple values separated by comma", "schema": { "type": "string", "enum": [ "VPP", "TENANT_IOS", "ESPER_IOS", "WEBCLIP", "ESPER_WINDOWS", "TENANT_WINDOWS", "TENANT_WINDOWS_EXE", "TENANT_WINDOWS_UWP" ] } }, { "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/device_DeviceAppsResponse" } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_400_Bad_Data" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_401_Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_500_Internal_Server_Error" } } } } } } }, "/v2/device-apps": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "device_apiKey": [] } ], "summary": "Get list of devices with an app by app_id or app_version_id.", "description": "iOS/iPadOS/tvOS/Windows only\n\nRetrieves a list of device IDs that have a specific app or app version associated, identified by app_id or app_version_id.\n\nBoth app_id and app_version_id are required query parameters; the endpoint returns a paginated list of device UUIDs matching the association.\n\n**About List Devices by App**\n\nThis endpoint inverts the typical device→apps query: given an app (or specific version), it returns the set of devices associated with it. This is useful for determining deployment coverage of a specific app version across a fleet. The response contains device UUIDs only — full device details require a subsequent call to GET /api/v2/devices/{id}. This endpoint is associated with the iOS and Windows Device Apps tag context; Android app associations are not covered.\n\n**Key Query Parameters**\n\napp_id (required) — Esper UUID of the application\n\napp_version_id (required) — Esper UUID of the specific app version\n\n**Common Use Cases**\n\nDetermining which devices have a specific app version deployed for targeted update campaigns\n\nAuditing app version coverage across iOS or Windows device fleets\n\nBuilding a list of affected devices before pushing an app update or removal\n\n**Best Practices**\n\nBoth app_id and app_version_id are required — the endpoint will return a 400 if either is omitted\n\nUse the returned device_id values to query GET /api/v2/devices/{id} for full device context\n\nPaginate using prev/next for large result sets\n\n**Workflow**\n\nObtain the app_id and app_version_id from the application management endpoints\n\nCall with both required parameters\n\nUse the returned device_id list to drive subsequent operations or lookups\n", "tags": [ "device_Device Apps" ], "parameters": [ { "in": "query", "name": "app_id", "required": false, "description": "ID of the app. Either app_id or app_version_id must be provided. Mandatory when app_version_id_not is provided.", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "app_version_id", "required": false, "description": "ID of the app version to match. Either app_id or app_version_id must be provided. Cannot be used together with app_version_id_not.", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "app_version_id_not", "required": false, "description": "ID of the app version to exclude. Returns devices whose app_version_id is not equal to this value. Requires app_id and cannot be used together with app_version_id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "prev": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "device_id": { "type": "string", "format": "uuid" } } } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_400_Bad_Data" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_401_Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_500_Internal_Server_Error" } } } } } } }, "/v2/devices/{deviceId}/google-accounts/policy/": { "get": { "description": "Retrieves the Google EMM policy details currently applied to a specific device.\n\nReturns the Google EMM policy configuration (including managed applications) associated with the device's Google account enrollment.\n\n**About Device Google EMM Policy**\nWhen a device is enrolled via Google EMM, Google maintains a policy for that device (distinct from, but often derived from, an Esper Enterprise Policy) that governs managed app behavior. This endpoint reflects that policy as currently applied on the Google side.\n\n**Key Fields / Query Parameters**\n- `deviceId` — UUID of the device whose Google EMM policy to retrieve\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get the Google EMM Policy details for a specific device.", "tags": [ "device_Device Enrollment in EMM" ], "parameters": [ { "name": "deviceId", "in": "path", "description": "ID of the device for which to retrieve the Google EMM policy", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_GoogleEMMDevice" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_401_Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_500_Internal_Server_Error" } } } } } }, "put": { "description": "Updates the Google EMM policy applications for a specific device.\n\nSets the applications list on the device's Google EMM policy; optional is_provisioning and is_converging query parameters indicate whether this update is happening as part of device provisioning or a converge operation.\n\n**About Device Google EMM Policy**\nThis endpoint pushes managed-application policy changes directly to a device's Google EMM enrollment. It is typically invoked by Esper's own provisioning and converge workflows rather than called ad hoc, hence the is_provisioning/is_converging flags.\n\n**Key Fields / Query Parameters**\n- `deviceId` — UUID of the device to update\n- `applications` — List of managed applications to set in the device's Google EMM policy\n- `is_provisioning` — Whether this update is part of initial device provisioning\n- `is_converging` — Whether this update is part of a Blueprint converge operation\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Update the Google EMM Policy details for a specific device.", "tags": [ "device_Device Enrollment in EMM" ], "parameters": [ { "name": "deviceId", "in": "path", "description": "The unique identifier of the device for which Google account details need to be updated.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "is_provisioning", "in": "query", "description": "Flag indicating if provisioning is enabled (true or false). Default is false.", "required": false, "schema": { "type": "string", "default": "false" } }, { "name": "is_converging", "in": "query", "description": "Flag indicating if convergence is enabled (true or false). Default is false.", "required": false, "schema": { "type": "string", "default": "false" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_GoogleEMMDevicePolicyRequest" } } } }, "responses": { "200": { "description": "Successfully updated the Google EMM policy details for the specified device.", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/device_GoogleEMMDevice" } } } } } }, "400": { "description": "Bad request due to invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_401_Unauthorized" } } } }, "404": { "description": "Device not found for the provided deviceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_404_Not_Found" } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_500_Internal_Server_Error" } } } } } } }, "/v2/devices/{deviceId}/google-accounts/emm-managed/": { "get": { "description": "Retrieves the list of Google EMM managed devices for a user's devices.\n\nReturns Google EMM-managed device records associated with the Google account linked to the specified device.\n\n**About Device Google EMM Managed Status**\nA single Google account/user may be associated with multiple EMM-managed devices; this endpoint surfaces that relationship from the perspective of one enrolled device's Google account.\n\n**Key Fields / Query Parameters**\n- `deviceId` — UUID of the device whose associated Google EMM-managed devices to retrieve\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get the List of Google EMM Managed Devices for a user's devices.", "tags": [ "device_Device Enrollment in EMM" ], "parameters": [ { "name": "deviceId", "in": "path", "description": "ID of the device for which to retrieve the Google EMM policy", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_DevicesListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_401_Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_500_Internal_Server_Error" } } } } } } }, "/v2/devices/{deviceId}/google-accounts/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Return the Google account details of the EMM enrollment stored in the database for the specified device.", "description": "⚠️ **Android only.**\n\nRetrieves the Google account records Esper has stored for a device's Google EMM enrollment.\n\nReturns the Google user ID, Google device ID, and account type linked to the device. An empty `results` list means no Google account is linked.\n\n**About Device Google Accounts**\nThis endpoint reads Esper's records and does not query Google. To see what Google reports, use the `emm-managed/` or `policy/` endpoints for the same device.\n\n**Key Fields / Query Parameters**\n- `deviceId` — UUID of the device\n- `google_authentication_token` — Treat as a secret; don't log or display it\n", "tags": [ "device_Device Enrollment in EMM" ], "parameters": [ { "name": "deviceId", "in": "path", "description": "ID of the device for which to retrieve the EMM enrollment status", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/device_GoogleAccount" } } } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_401_Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_500_Internal_Server_Error" } } } } } }, "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Update the Google account details of the EMM enrollment stored in the database for a specific device.", "description": "⚠️ **Android only.**\n\nUpdates the Google user ID and Google device ID that Esper has stored for a device.\n\nChanges Esper's record only; nothing is changed on the Google side. Returns the `device_id` and `tenant_id` of the updated record.\n\n**About Updating a Device Google Account**\nUse this to correct Esper's record when it no longer matches what the `emm-managed/` endpoint reports for the device.\n\n**Key Fields / Query Parameters**\n- `deviceId` — UUID of the device\n- `google_device_id`, `google_user_id` — Both required\n", "tags": [ "device_Device Enrollment in EMM" ], "parameters": [ { "name": "deviceId", "in": "path", "description": "The unique identifier of the device for which Google account details need to be updated.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_GoogleAccountUpdateRequestBody" } } } }, "responses": { "200": { "description": "Successfully updated the Google account details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/device_GoogleAccountUpdateResponseBody" } } } } } }, "400": { "description": "Bad request due to invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_401_Unauthorized" } } } }, "404": { "description": "Device not found for the provided deviceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_404_Not_Found" } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_500_Internal_Server_Error" } } } } } }, "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Create a Google user and, if request body is not provided, generate a Google auth token for a specific device on the Google EMM side.", "description": "⚠️ **Android only.**\n\nCreates a Google EMM user for a device and links it in Esper.\n\nWith no request body, Esper creates the Google user on the Google EMM side and generates an authentication token for the device. Check for an existing account with GET first to avoid duplicates.\n\n**About Creating a Device Google Account**\nEsper normally creates this account during enrollment. Use this endpoint when a device enrolled without one.\n\n**Key Fields / Query Parameters**\n- `deviceId` — UUID of the device\n- Request body (optional) — When included, `tenant_id`, `google_user_id`, `device_id`, and `account_type` are required\n", "tags": [ "device_Device Enrollment in EMM" ], "parameters": [ { "name": "deviceId", "in": "path", "description": "The unique identifier of the device for which Google account details need to be updated.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_GoogleAccount" } } } }, "responses": { "200": { "description": "Successfully updated the Google account details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/device_GoogleAccount" } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_401_Unauthorized" } } } }, "404": { "description": "Device not found for the provided deviceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_404_Not_Found" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_409_Conflict" } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_500_Internal_Server_Error" } } } } } }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Unenrolls device from Google EMM and deletes the Google account details.", "description": "Creates a Google user for a device and, if no request body is provided, generates a Google auth token on the EMM side.\n\nCreates the Google account binding record for the device's EMM enrollment; when called without a request body, it also generates a fresh Google authentication token for that device on the Google EMM side.\n\n**About Device Google Account (EMM Enrollment)**\nThis endpoint is typically invoked as part of the device provisioning flow for Google EMM enrollment, establishing (or refreshing) the link between an Esper device and its Google-managed account.\n\n**Key Fields / Query Parameters**\n- `deviceId` — UUID of the device to create the Google account binding for\n- `google_device_id` — Unique identifier for the Google device\n- `google_user_id` — Unique identifier for the Google user\n- `google_authentication_token` — Authentication token for the Google account, generated automatically if the request body is omitted\n", "tags": [ "device_Device Enrollment in EMM" ], "parameters": [ { "name": "deviceId", "in": "path", "description": "The unique identifier of the device for which Google account details need to be updated.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successfully unenrolled and deleted the Google account details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/device_GoogleAccount" } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_401_Unauthorized" } } } }, "404": { "description": "Device not found for the provided deviceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_404_Not_Found" } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_500_Internal_Server_Error" } } } } } } }, "/v0/operations/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get all Operations in the Tenant", "description": "Retrieves a paginated list of all Dispatch operations created within the tenant.\n\nUse this endpoint to see every large-scale fleet operation issued through the Operations API, including Converge actions and group-level app installs and uninstalls, along with each operation's aggregate progress. Supports filtering by state, operation type, and group.\n\n**About Operations (Dispatch Commands)**\n\nOperations, also called Dispatch commands, are designed for large fleet actions that need to be issued once and tracked as a single unit rather than as many individual device commands. Currently supported operation types are CONVERGE and group-level app INSTALL and UNINSTALL (immediate only). Each operation moves through a lifecycle from Created through Dispatching, Dispatched, and Processing to a final Success or Failure, and this endpoint surfaces that lifecycle across every operation in the tenant.\n\n**Key Fields / Query Parameters**\n\nstate — filters by operation state using integer codes, for example 10 for Created, 50 for Dispatched, 80 for Success, and 90 for Failure\n\noperation_type — filters by type, for example CONVERGE, INSTALL, or UNINSTALL\n\ngroup_multi — filters to operations targeting one or more group IDs and their subgroups\n\nordering — orders results by created_at, state, or updated_at; prefix with a minus sign to reverse order\n\n**Common Use Cases**\n\nAuditing every Converge operation issued across the tenant over a time period\n\nFinding all operations currently stuck in a Dispatching or Processing state, which usually points to device connectivity issues\n\nFiltering operations by group to review fleet actions scoped to a specific store or region\n\n**Best Practices**\n\nFilter by operation_type and state together to narrow large result sets before paging through them\n\nInvestigate operations that remain in Dispatched or Processing for an extended period, since this usually indicates devices are not picking up the command due to network issues\n\nUse group_multi rather than fetching all operations and filtering client-side when working with group-scoped fleets\n\n**Workflow**\n\nCall this endpoint with the desired state or operation_type filters\n\nIdentify the operation of interest and note its id\n\nCall GET /v0/operations/{operationId}/ for the full status and aggregate device counts\n\nDrill into GET /v0/operations/{operationsId}/devices/ if the operation shows failures\n", "operationId": "getOperationsList", "tags": [ "device_Operations" ], "security": [ { "device_apiKey": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "type": "integer" } }, { "in": "query", "name": "state", "schema": { "type": "integer" }, "description": "Following are the Operation States and their corresponding integer values\n```\nOPERATION_CREATED = 10\nOPERATION_RESOLVING = 20\nOPERATION_RESOLVED = 30\nOPERATION_DISPATCHING = 40\nOPERATION_DISPATCHED = 50\nOPERATION_PROCESSING = 60\nOPERATION_COMPLETED = 70\nOPERATION_SUCCESS = 80\nOPERATION_FAILURE = 90\nOPERATION_SCHEDULED = 100\nOPERATION_CANCELLED = 110\nOPERATION_TIMEOUT = 120\n```\n" }, { "in": "query", "name": "ordering", "description": "Field to order the results by. Prefix with '-' to reverse the order.", "schema": { "type": "string", "enum": [ "created_at", "state", "updated_at" ] } }, { "in": "query", "name": "operation_type", "description": "Filter operations by type (e.g., INSTALL, UNINSTALL, CONVERGE, INSTALL_APP, UNINSTALL_APP, REBOOT)", "schema": { "type": "string" } }, { "in": "query", "name": "group_multi", "description": "Filter by multiple group ID. Fetch the devices from groups matching with the IDs and its subgroup.", "schema": { "type": "string", "format": "uuid" } } ], "x-scope": [ "read:operation" ], "responses": { "200": { "description": "Operations information for the Tenant", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/device_OperationWithStats" } } } } } } } } } } }, "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Create a new Operation", "description": "Creates a new Dispatch operation to run a large fleet action, such as Converge, across a set of devices or groups in a single request.\n\nOperations are built for scale — a single call can target device_ids directly or resolve a device_request query (for example matching on group_multi or state) into as many as tens of thousands of devices. The operation is queued immediately in the Created state and resolves asynchronously as Esper identifies the applicable devices and dispatches the command.\n\n**About Create Operation**\n\nCurrently, operation_type supports CONVERGE and group-level app INSTALL and UNINSTALL, and INSTALL/UNINSTALL are immediate only. Unlike the Command Request API, which issues one command per device or group call, Operations are designed specifically for very large fleet actions and report a single aggregate status alongside individual per-device results. A created operation does not affect devices immediately; it queues the action, then resolves the target devices, then dispatches the command to each of them.\n\n**Key Fields / Request Body**\n\noperation_type — the action to run, currently CONVERGE, INSTALL, or UNINSTALL\n\nschedule_type — IMMEDIATE to run right away or WINDOW to run within a scheduled window\n\noperation_device_query — the device targeting payload; accepts a device_ids list or a device_request object with filters such as group_multi or state\n\narguments — operation-specific arguments that mirror the command_args payload for the corresponding command type. Use the same field names and structure as POST /commands/v0/commands/ for that operation_type. For example, pass converge_with_provision for CONVERGE, or package_name and app_version for INSTALL/UNINSTALL operations.\n\n**Common Use Cases**\n\nConverging tens of thousands of devices onto an updated blueprint in a single request\n\nInstalling or uninstalling an app across every device in one or more groups\n\nRe-driving a Converge operation for a targeted list of devices that failed a previous attempt\n\n**Best Practices**\n\nBatch very large device lists in operation_device_query rather than issuing many smaller operations, since Operations are built to scale to tens of thousands of devices per request\n\nCapture the id returned in the response immediately, since it is required for every subsequent status check\n\nConfirm devices are online and provisioned before including them in a Converge operation to avoid indefinite Dispatched or Processing states\n\n**Workflow**\n\nDetermine the device_ids or device_request filters that define the target fleet\n\nPOST to this endpoint with the operation_type and operation_device_query\n\nCapture the returned id as the Operation ID\n\nPoll GET /v0/operations/{operationId}/ until the operation reaches Success or Failure\n", "operationId": "createOperation", "tags": [ "device_Operations" ], "security": [ { "device_apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Operations_POST" }, "examples": { "devices": { "$ref": "#/components/examples/device_example_devices" }, "filters": { "$ref": "#/components/examples/device_example_filters" } } } } }, "x-scope": [ "create:operation:CONVERGE" ], "responses": { "201": { "description": "Operation information for the Tenant", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/device_OperationWithStats" } } } } } } } } }, "/v0/operations/{operationId}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get specific Operation details (Operation Status)", "description": "Retrieves the full status and aggregate device counts for a single Dispatch operation.\n\nUse this endpoint to check whether a Converge, install, or uninstall operation has resolved, how many devices it reached, and how many succeeded or failed. The operation_stats object gives the aggregate breakdown, while operation_activity gives a timestamped history of the operation's state transitions.\n\n**About Operation Status**\n\nAn Operation moves through Created, Query Initiated, Query Resolved, Dispatching, Dispatched, Processing, and finally Success or Failure. The operation is only marked Success once every applicable device has executed the command successfully; a single device failure marks the whole operation Failure. Operations can remain indefinitely in Dispatched or Processing if devices are not picking up the command, which is usually a sign of network connectivity issues rather than a problem with the operation itself.\n\n**Common Use Cases**\n\nPolling an operation after creation to confirm it reached Success\n\nChecking operation_stats to see how many of a large batch of devices failed a Converge action\n\nReviewing operation_activity to see how long an operation spent in each lifecycle state\n\n**Best Practices**\n\nTreat a Failure state as meaning at least one device failed, not that the entire batch failed; check operation_stats.failed_device_count for the real scope\n\nIf an operation is stuck in Dispatched or Processing, check the affected devices' connectivity rather than re-issuing the operation immediately\n\nUse the state query parameter on GET /v0/operations/ to find other operations in the same state if you suspect a systemic issue\n\n**Workflow**\n\nCreate the operation with POST /v0/operations/ and capture the returned id\n\nPoll this endpoint until state reaches a terminal value\n\nIf state is Failure, call GET /v0/operations/{operationsId}/devices/ to identify which devices failed\n\nRe-drive the operation for the failed devices once their connectivity is confirmed\n", "operationId": "getOperation", "security": [ { "device_apiKey": [] } ], "tags": [ "device_Operations" ], "parameters": [ { "name": "operationId", "in": "path", "description": "ID of the Operation", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-scope": [ "read:operation" ], "responses": { "200": { "description": "Operation information for the Tenant", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/device_OperationWithStats" } } } } } } } }, "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Cancel an operation", "description": "Cancels an existing Dispatch operation. User-initiated updates support only the CANCELLED state.\n\nUse this endpoint to request cancellation while the operation is in a cancellable state. Internal states such as FAILURE, TIMEOUT, DISPATCHING, and PROCESSING are managed by Esper services and cannot be set through this public API.\n\n**About Update Operation**\n\nCancellation is allowed only when the operation's current state permits a transition to CANCELLED. For operations that have already dispatched work, cancellation is asynchronous and some devices may complete before downstream cancellation is processed.\n\n**Key Fields / Request Body**\n\nstate — the new operation state, CANCELLED\n\nreason — free text explaining the state change\n\n**Common Use Cases**\n\nCancelling an operation that was created in error or is no longer needed\n\n**Best Practices**\n\nCheck the operation's current state with GET /v0/operations/{operationId}/ before attempting to cancel it\n\nAlways include a reason so the cancellation is auditable alongside the operation's activity history\n\n**Workflow**\n\nCall GET /v0/operations/{operationId}/ to confirm the operation is still in a cancellable state\n\nPUT state CANCELLED and a reason to this endpoint\n\nRe-check the operation to confirm the update took effect\n", "tags": [ "device_Operations" ], "security": [ { "device_apiKey": [] } ], "parameters": [ { "name": "operationId", "in": "path", "required": true, "description": "The ID of the operation to update (Put created operationId here)", "schema": { "type": "string", "example": "5743470f-7dcc-4a92-8a4b-f41b1cea69ed" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "CANCELLED" ], "description": "The new status of the operation. Only CANCELLED is supported for user-initiated updates." }, "reason": { "type": "string", "description": "Free text explaining the state change. Required." } }, "required": [ "state", "reason" ] }, "examples": { "example-1": { "summary": "Update status to CANCELLED", "value": { "state": "CANCELLED", "reason": "User requested" } } } } } }, "x-scope": [ "update:operation" ], "responses": { "200": { "description": "Operation status updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "operationId": { "type": "string", "description": "The ID of the updated operation" }, "status": { "type": "string", "description": "The updated status of the operation" } } }, "example": { "operationId": "12345", "status": "SUCCEEDED" } } } } } } }, "/v0/operations/{operationsId}/devices/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get all DeviceOperations for a specific Operation", "description": "Retrieves the per-device breakdown of a single Dispatch operation, showing where every targeted device stands in the operation's lifecycle.\n\nUse this endpoint after checking an operation's aggregate status to see exactly which devices succeeded, failed, or are still processing. Supports filtering by device operation state and ordering, which makes it the primary tool for isolating the devices that failed a Converge, install, or uninstall action.\n\n**About Device Operations for an Operation**\n\nWhen a Dispatch operation targets many devices, Esper tracks each device's progress as a separate DeviceOperation record nested under the parent Operation. This endpoint lists all of those records for a given operationsId, each carrying its own state and activity history distinct from the operation's overall state. It is the standard way to move from \"this operation had failures\" to \"these are the specific devices that failed.\"\n\n**Key Fields / Query Parameters**\n\nstate — filters by device operation state using integer codes; common values are 10 for Created, 30 for Dispatched, 40 for Processing, 50 for Success, and 60 for Failure\n\nordering — orders results by created_at, state, or updated_at; prefix with a minus sign to reverse order\n\n**Common Use Cases**\n\nListing every device that failed a fleet-wide Converge operation by filtering state to the failure code\n\nMonitoring how many devices in a large install or uninstall operation are still processing\n\nBuilding a per-device progress view for a dispatch operation shown in the Activity Feed\n\n**Best Practices**\n\nFilter by state rather than paging through the full device list when you only need failures\n\nCombine with ordering by created_at to review the most recently updated devices first\n\nFor a single device's status within the operation, use GET /v0/operations/{operationsId}/devices/{deviceId}/ instead of filtering this list\n\n**Workflow**\n\nCreate or identify the operation using the Operations endpoints\n\nCall this endpoint with the operationsId to retrieve the full device breakdown\n\nFilter by state to isolate failed or still-processing devices\n\nRe-drive the operation for any failed devices once their connectivity is confirmed\n", "operationId": "getDeviceOperations", "tags": [ "device_DeviceOperations" ], "security": [ { "device_apiKey": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "type": "integer" } }, { "name": "operationsId", "in": "path", "description": "ID of the Operation", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "5743470f-7dcc-4a92-8a4b-f41b1cea69ed" }, { "in": "query", "name": "state", "schema": { "type": "integer" }, "description": "Following are the Device Operation States and their corresponding integer values\n```\nDEVICE_OPERATION_CREATED = 10\nDEVICE_OPERATION_INITIATED = 20\nDEVICE_OPERATION_DISPATCHED = 30\nDEVICE_OPERATION_PROCESSING = 40\nDEVICE_OPERATION_SUCCESS = 50\nDEVICE_OPERATION_FAILURE = 60\nDEVICE_OPERATION_CANCELLED = 70\nDEVICE_OPERATION_TIMEOUT = 80\nDEVICE_OPERATION_COMPLETED = 90\n```\n" }, { "in": "query", "name": "ordering", "description": "Field to order the results by. Prefix with '-' to reverse the order.", "schema": { "type": "string", "enum": [ "created_at", "state", "updated_at" ] } } ], "x-scope": [ "read:operation:devices" ], "responses": { "200": { "description": "Device Operation information for the Operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/device_DeviceOperationWithStats" } } } } } } } } } } } }, "/v0/devices/{deviceId}/operations/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get a Operations for a device", "description": "Retrieves the Dispatch operations that have targeted a specific device, giving a device-centric view of Converge, install, and uninstall activity.\n\nUse this endpoint when you already have a device_id and want to see which fleet-wide dispatch operations it was included in, rather than starting from the operation and looking up its devices. Returns the same OperationWithStats objects used elsewhere in the Operations API, each including the operation's type, current state, and aggregate device counts.\n\n**About Operations for a Device**\n\nOperations, also called Dispatch commands, are Esper's mechanism for issuing large fleet actions such as Converge and group-level app installs and uninstalls to many devices in a single request. Every operation that includes this device appears in this list, regardless of when it was created or how many other devices it targeted. This is the reverse lookup of GET /v0/operations/{operationsId}/devices/, which starts from the operation instead of the device.\n\n**Common Use Cases**\n\nAuditing every dispatch operation a device has participated in\n\nTroubleshooting a device that appears out of sync by checking whether a recent Converge operation reached it\n\nConfirming whether a device was included in a bulk install or uninstall operation\n\n**Best Practices**\n\nCross-reference the operation IDs returned here with GET /v0/operations/{operationId}/ for full operation-level context, including overall success and failure counts\n\nCheck the most recent entries first when troubleshooting a device that just failed to Converge\n\n**Workflow**\n\nIdentify the device_id from a device listing endpoint\n\nCall this endpoint with that device_id to list the operations that targeted it\n\nUse the returned operation id with GET /v0/operations/{operationsId}/devices/{deviceId}/ to see this device's specific status within that operation\n", "tags": [ "device_DeviceOperations" ], "security": [ { "device_apiKey": [] } ], "parameters": [ { "name": "deviceId", "in": "path", "description": "ID of the Device", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "17d384d3-29bd-4dd4-af64-d02b9d6d54ee" } ], "x-scope": [ "read:device:operations" ], "responses": { "200": { "description": "Operations information for the Device", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/device_OperationWithStats" } } } } } } } } } }, "/v0/operations/{operationsId}/devices/{deviceId}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get a specific DeviceOperations for a specific Operation (Device Operation Status)", "description": "Retrieves the status of a single device's progress within a specific Dispatch operation.\n\nUse this endpoint to check exactly where one device stands inside a larger fleet operation, including its full state history from creation through to success or failure. This is the most granular status check available for Dispatch operations such as Converge, install, and uninstall.\n\n**About Device Operation Status**\n\nEvery device targeted by an Operation gets its own DeviceOperation record, which moves independently through Created, Initiated, Dispatched, Processing, and a terminal state such as Success, Failure, Cancelled, or Timeout. The device_operation_activity array on the response captures a timestamped history of every state transition for that device, useful for diagnosing exactly when and where a device stalled or failed.\n\n**Common Use Cases**\n\nDiagnosing why one specific device failed a Converge operation while the rest of the fleet succeeded\n\nConfirming a device has reached Success before considering a bulk install or uninstall complete for that device\n\nReviewing the timing between dispatch and completion for a single device\n\n**Best Practices**\n\nCheck device_operation_activity for the full timeline rather than relying on the current state alone\n\nIf a device is stuck in Dispatched or Processing, confirm its connectivity with GET /device/v0/heartbeat/{id}/ before assuming the operation failed\n\nPair this with GET /v0/operations/{operationsId}/devices/ when you need to move from a fleet-wide failure list down to individual device detail\n\n**Workflow**\n\nIdentify the operationsId and deviceId, typically from the device operation list endpoint\n\nCall this endpoint to retrieve the device's current state and activity history\n\nIf the device shows a failure or timeout state, check its last-seen connectivity before retrying\n\nInclude the device_id again in a new Operation if it needs to be re-dispatched\n", "operationId": "getDeviceOperation", "tags": [ "device_DeviceOperations" ], "security": [ { "device_apiKey": [] } ], "parameters": [ { "name": "operationsId", "in": "path", "description": "ID of the Operation", "required": true, "schema": { "type": "string", "format": "uuid", "example": "5743470f-7dcc-4a92-8a4b-f41b1cea69ed" } }, { "name": "deviceId", "in": "path", "description": "ID of the Device", "required": true, "schema": { "type": "string", "format": "uuid", "example": "17d384d3-29bd-4dd4-af64-d02b9d6d54ee" } } ], "x-scope": [ "read:operation:devices" ], "responses": { "200": { "description": "Device Operation information for the Operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/device_DeviceOperationWithStats" } } } } } } } }, "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Update a specific DeviceOperation for a specific Operation", "description": "Updates the recorded state of a single device's progress within a Dispatch operation.\n\nUsed to request cancellation for an individual device operation (instead of a larger fleetwide operation) by specifying the sate as CANCELLATION_REQUESTED. Cancellation is not guaranteed and depends the command's exact state. \n\n**About Update Device Operation**\n\nEach DeviceOperation record represents one device's slice of a larger Operation. As the underlying dispatch command progresses on the device side, the owning service reports the new state back through this endpoint, which then rolls up into the parent operation's aggregate stats (resolved, dispatched, failed, and success counts). Because this directly affects the parent operation's reported outcome, updates here should come from the service that owns the operation's execution rather than from ad hoc calls.\n\n**Key Fields / Request Body**\n\noperation_type — the operation type this device operation belongs to, for example CONVERGE\n\nstate — the new device operation state, for example SUCCESS\n\nservice_id — Optional. identifies the internal service reporting the update, for example drift-service\n\nreason — free text explaining the state change\n\n**Common Use Cases**\n\nAn internal service reporting that a device successfully completed its Converge action\n\nMarking a device's operation as failed after the underlying command times out on the device\n\n**Best Practices**\n\nOnly update state from the service that actually owns execution of the underlying command for that device\n\nAlways populate reason when reporting a failure so the cause is visible in the operation's activity history\n\n**Workflow**\n\nIdentify the operationsId and deviceId for the device operation being updated\n\nDetermine the device's actual outcome from the underlying command or drift check\n\nPUT the new state, service_id, and reason to this endpoint\n\nConfirm the update is reflected in the parent operation's aggregate stats via GET /v0/operations/{operationId}/\n", "operationId": "updateDeviceOperation", "tags": [ "device_DeviceOperations" ], "security": [ { "device_apiKey": [] } ], "parameters": [ { "name": "operationsId", "in": "path", "description": "ID of the Operation", "required": true, "schema": { "type": "string", "format": "uuid", "example": "0aae03d2-32b4-4cab-b733-6919b84bb2ac" } }, { "name": "deviceId", "in": "path", "description": "ID of the Device", "required": true, "schema": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "x-scope": [ "update:operation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "state" ], "properties": { "operation_type": { "type": "string", "example": "CONVERGE", "description": "Optional; resolved from the database if not provided.", "deprecated": true }, "state": { "type": "string", "enum": [ "CANCELLATION_REQUESTED" ], "description": "The new state for the device operation. Only CANCELLATION_REQUESTED is supported for user-initiated updates. Cancellation is not guaranteed and depends on the command's current execution state on the device.\n", "example": "CANCELLATION_REQUESTED" }, "service_id": { "type": "string", "example": "drift-service" }, "reason": { "type": "string", "example": "test" } } } } } }, "responses": { "200": { "description": "Device Operation updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/device_DeviceOperationWithStats" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_401_Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_500_Internal_Server_Error" } } } } } } }, "/v2/foundationversions": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get all distinct foundation versions", "description": "Returns the distinct Foundation versions present across the tenant's devices.\n\nReturns a de-duplicated list of Foundation (Esper's on-device agent/runtime) version strings currently reported by devices in the tenant, with search and pagination support.\n\n**About Foundation Versions**\nFoundation is Esper's on-device software layer that enables management capabilities. Knowing which Foundation versions are present across a fleet is useful for understanding which devices may need an agent update before certain features or fixes are available to them.\n\n**Key Fields / Query Parameters**\n- `search` — Filter Foundation version strings by a search term\n- `limit / offset` — Pagination controls\n\n**Common Use Cases**\n- Auditing Foundation version spread across the fleet before rolling out a feature that requires a minimum version\n- Identifying outdated Foundation versions that may need an update\n- Reporting on agent version compliance for a security or operations review\n\n**Best Practices**\n- Cross-reference results with the Device Tiles report if you need to find which specific devices are on an outdated version\n- Check this before rolling out features gated on a minimum Foundation version\n- Re-run periodically after a fleet-wide agent update to confirm rollout completion\n\n**Workflow**\n1. GET this endpoint to see the distinct Foundation versions present\n2. Use the Device Tiles report or device list filters to find devices on outdated versions\n3. Plan and execute a Foundation update for those devices as needed\n", "operationId": "getFoundationVersionsList", "x-scope": [ "read:foundationversions" ], "tags": [ "device_Device" ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 10 }, "description": "Number of results to return per page" }, { "in": "query", "name": "offset", "schema": { "type": "integer", "default": 0 }, "description": "The initial index from which to return the results" }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Filter foundation versions by partial string match (case-insensitive)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of distinct foundation versions" }, "prev": { "type": "string", "description": "URL to the previous page of results" }, "next": { "type": "string", "description": "URL to the next page of results" }, "results": { "type": "array", "items": { "type": "object", "properties": { "foundation_version": { "type": "string", "description": "The foundation version string" } } } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_401_Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_500_Internal_Server_Error" } } } } } } }, "/v2/rv-activity-feed/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get RemoteViewer Activity Feed for the tenant", "description": "Retrieves a paginated, filterable feed of Remote Viewer sessions across the tenant.\n\nEach entry represents one Remote Viewer session, including the device it targeted, its current state, video quality, duration, and who initiated it. Supports filtering by state, video quality, device name, and the user who created the session.\n\n**About Remote Viewer Activity Feed**\n\nRemote Viewer sessions move through INITIATED, ACKNOWLEDGED, ACTIVE, and a terminal TERMINATED or FAILED state. This feed gives a tenant-wide, auditable view of who has remotely viewed which devices, how long each session lasted, and whether it completed successfully, spanning the multi-OS Remote Viewer feature rather than any single platform.\n\n**Key Fields / Query Parameters**\n\nstates — filters by one or more session states, comma-separated\n\ncreated_by — filters sessions by the user who initiated them\n\ndevice_name — searches sessions by device name\n\nordering — orders results, defaults to -created_at (most recent first)\n\n**Common Use Cases**\n\nAuditing who accessed a given device through Remote Viewer and when\n\nReviewing failed or unusually long Remote Viewer sessions across the fleet\n\nInvestigating support activity on a specific device by filtering on device_name\n\n**Best Practices**\n\nFilter by states to separate completed sessions from ones that failed or never became active\n\nUse created_by when auditing an individual support agent's Remote Viewer activity\n\n**Workflow**\n\nCall this endpoint with the filters relevant to your audit or investigation\n\nReview session state and duration for each result\n\nUse the session_id to correlate with support tickets or other internal records if needed\n", "tags": [ "device_MultiOS Remote Viewer" ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "type": "integer" } }, { "in": "query", "name": "states", "schema": { "type": "string", "enum": [ "INITIATED", "ACKNOWLEDGED", "ACTIVE", "TERMINATED", "FAILED" ], "description": "List API supports comma separated states." } }, { "in": "query", "name": "video_qualities", "schema": { "type": "string", "enum": [ "STANDARD", "DATA_SAVER" ], "description": "To allow filtering sessions list by comma separated video qualities" } }, { "in": "query", "name": "reason", "schema": { "type": "string", "description": "To allow searching sessions list by reason" } }, { "in": "query", "name": "created_by", "schema": { "type": "string", "description": "To allow filtering sessions list by created by" } }, { "in": "query", "name": "device_name", "schema": { "type": "string", "description": "To allow searching sessions list by device name" } }, { "in": "query", "name": "ordering", "schema": { "type": "string", "default": "-created_at", "enum": [ "created_at", "updated_at", "device_name", "duration", "state", "reason", "video_quality", "created_by" ], "description": "To allow ordering sessions list by created_at, updated_at, device_name, duration, state, reason, video_quality and created_by." } }, { "in": "query", "name": "duration_lt", "schema": { "type": "string", "format": "duration", "description": "Duration less than filter. The time duration (in ISO 8601 duration format) of only a valid elapsed session, i.e., sessions that have moved from ACTIVE state (where session start-time can be captured) to TERMINATED or FAILED state (where the session end-time can be captured).", "example": "duration_lt=PT10M30S" } }, { "in": "query", "name": "duration_lte", "schema": { "type": "string", "format": "duration", "description": "Duration less than or equal to filter. The time duration (in ISO 8601 duration format) of only a valid elapsed session, i.e., sessions that have moved from ACTIVE state (where session start-time can be captured) to TERMINATED or FAILED state (where the session end-time can be captured).", "example": "duration_lte=PT10M30S" } }, { "in": "query", "name": "duration_gt", "schema": { "type": "string", "format": "duration", "description": "Duration greater than filter. The time duration (in ISO 8601 duration format) of only a valid elapsed session, i.e., sessions that have moved from ACTIVE state (where session start-time can be captured) to TERMINATED or FAILED state (where the session end-time can be captured).", "example": "duration_gt=PT10M30S" } }, { "in": "query", "name": "duration_gte", "schema": { "type": "string", "format": "duration", "description": "Duration greater than or equal to filter. The time duration (in ISO 8601 duration format) of only a valid elapsed session, i.e., sessions that have moved from ACTIVE state (where session start-time can be captured) to TERMINATED or FAILED state (where the session end-time can be captured).", "example": "duration_gte=PT10M30S" } }, { "in": "query", "name": "created_at_lt", "schema": { "type": "string", "format": "date-time", "description": "Created at less than filter. Datetime format must be in \"YY-MM-DDTHH:mm:ss.fffffffffZ\".", "example": "created_at_lt=2023-10-01T12:00:00Z" } }, { "in": "query", "name": "created_at_gt", "schema": { "type": "string", "format": "date-time", "description": "Created at greater than filter. Datetime format must be in \"YY-MM-DDTHH:mm:ss.fffffffffZ\".", "example": "created_at_gt=2023-10-01T12:00:00Z" } }, { "in": "query", "name": "created_at_lte", "schema": { "type": "string", "format": "date-time", "description": "Created at less than or equal to filter. Datetime format must be in \"YY-MM-DDTHH:mm:ss.fffffffffZ\".", "example": "created_at_lte=2023-10-01T12:00:00Z" } }, { "in": "query", "name": "created_at_gte", "schema": { "type": "string", "format": "date-time", "description": "Created at greater than or equal to filter. Datetime format must be in \"YY-MM-DDTHH:mm:ss.fffffffffZ\".", "example": "created_at_gte=2023-10-01T12:00:00Z" } }, { "in": "query", "name": "updated_at_lt", "schema": { "type": "string", "format": "date-time", "description": "Updated at less than filter. Datetime format must be in \"YY-MM-DDTHH:mm:ss.fffffffffZ\".", "example": "updated_at_lt=2023-10-01T12:00:00Z" } }, { "in": "query", "name": "updated_at_gt", "schema": { "type": "string", "format": "date-time", "description": "Updated at greater than filter. Datetime format must be in \"YY-MM-DDTHH:mm:ss.fffffffffZ\".", "example": "updated_at_gt=2023-10-01T12:00:00Z" } }, { "in": "query", "name": "updated_at_lte", "schema": { "type": "string", "format": "date-time", "description": "Updated at less than or equal to filter. Datetime format must be in \"YY-MM-DDTHH:mm:ss.fffffffffZ\".", "example": "updated_at_lte=2023-10-01T12:00:00Z" } }, { "in": "query", "name": "updated_at_gte", "schema": { "type": "string", "format": "date-time", "description": "Updated at greater than or equal to filter. Datetime format must be in \"YY-MM-DDTHH:mm:ss.fffffffffZ\".", "example": "updated_at_gte=2023-10-01T12:00:00Z" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/device_RemoteViewerSessionsListForTenantResponse" } } } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_401_Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_Error_500_Internal_Server_Error" } } } } } } }, "/apps/v0/vpp": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "summary": "Get VPP License List", "description": "Returns a paginated list of VPP (Volume Purchase Program) licenses associated with the tenant's configured VPP token. Use it to see all Apple VPP-licensed apps and their license counts in one call.\n\nThe response includes a count of results plus prev/next pagination URLs alongside the list of VPPLicense records, so you can page through large license sets.\n\n**About VPP License Management**\n\nVPP lets organizations purchase iOS/iPadOS/tvOS app licenses in bulk through Apple and distribute them to managed devices; Esper syncs license data using the tenant's VPP token. This endpoint surfaces that synced license inventory so you can audit what's licensed before assigning apps to devices.\n\n**Common Use Cases**\n\n- Auditing which apps have VPP licenses provisioned for the tenant\n- Checking license availability before assigning an iOS app to additional devices\n", "tags": [ "apps_management_VPP License Management" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "response code", "default": 200 }, "message": { "type": "string", "description": "response message" }, "content": { "type": "object", "properties": { "count": { "type": "integer", "description": "number of results returned" }, "prev": { "type": "string", "description": "URL for previous page of results" }, "next": { "type": "string", "description": "URL for next page of results" }, "results": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/apps_management_VPPLicense" } ] } } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } } }, "/apps/v0/vpp/{appId}": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "parameters": [ { "in": "path", "name": "appId", "schema": { "type": "integer" }, "required": true } ], "summary": "Get VPP License Info about an App", "description": "Returns VPP (Volume Purchase Program) license details for a single app, identified by its VPP app ID. Use it to check license status and counts for one specific iOS app rather than pulling the full license list.\n\nReturns a single VPPLicense object for the given appId.\n\n**About VPP License Management**\n\nVPP lets organizations purchase iOS/iPadOS/tvOS app licenses in bulk through Apple; Esper syncs license data using the tenant's VPP token so license counts stay current without manual entry.\n\n**Key Fields / Query Parameters**\n\n- appId — the app's VPP identifier (path parameter, numeric), not Esper's internal app UUID\n\n**Common Use Cases**\n\n- Checking whether an iOS app still has available VPP license seats before assigning it to more devices\n", "tags": [ "apps_management_VPP License Management" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "response code", "default": 200 }, "message": { "type": "string", "description": "response message" }, "content": { "$ref": "#/components/schemas/apps_management_VPPLicense" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } } }, "/v2/itunesapps": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "parameters": [ { "name": "app_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "version_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "apple_app_id", "in": "query", "schema": { "type": "string" } }, { "name": "country_code", "in": "query", "description": "ISO country code for App Store region (e.g., \"us\", \"gb\", \"de\"). Defaults to \"us\".", "schema": { "type": "string", "pattern": "^[a-zA-Z]{2}$", "example": "us" } } ], "summary": "Get iOS App Info (v2)", "description": "Looks up iOS app information by app ID or Apple app ID.\n\nReturns a paginated list of ItunesAppInfoV2 records — app name, icon, developer, current version, and iTunes Store URL — matched by Esper's internal app_id, an Apple app ID, or a specific version_id, optionally scoped to an App Store country/region.\n\n**About iOS App Info**\n\nThis is an iOS/VPP-specific endpoint (Android is not applicable) that surfaces iTunes/App Store metadata for apps managed through Esper's VPP App Management. It's the v2 replacement path for looking up iTunes app details tied to a tenant's VPP-managed iOS apps.\n\n**Key Fields / Query Parameters**\n\n- app_id — Esper's internal UUID for the app\n- version_id — UUID of a specific app version\n- apple_app_id — the app's ID from Apple\n- country_code — ISO country code for the App Store region, defaults to \"us\"\n\n**Common Use Cases**\n\n- Looking up current iTunes metadata (name, icon, version) for a VPP-managed iOS app\n- Resolving an Apple app ID to Esper's internal app_id for further API calls\n", "tags": [ "apps_management_VPP App Management" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "count": { "type": "integer", "description": "number of results returned" }, "prev": { "type": "string", "description": "URL for previous page of results" }, "next": { "type": "string", "description": "URL for next page of results" }, "results": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/apps_management_ItunesAppInfoV2" } ] } } } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } } }, "/v2/itunesapps/{appleAppId}/preferred-region": { "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "parameters": [ { "in": "path", "required": true, "name": "appleAppId", "schema": { "type": "string" }, "description": "The Apple App Store ID of the VPP app (e.g., \"361309726\")" } ], "summary": "Set Preferred Region for VPP App", "description": "⚠️ Apple devices only. This endpoint applies exclusively to iOS devices managed via VPP (Volume Purchase Program).\n\nSets the preferred App Store region for a specific VPP app, overriding the default storefront used when Esper fetches app metadata and updates for that app.\n\nEach VPP app can be assigned to one of the preferred regions configured at the tenant level. Assigning the correct region is important for update reliability — devices in a region that doesn't match the app's assigned storefront may fail to receive app updates.\n\n**About VPP App Preferred Region**\n\nApple's App Store is region-segmented; the same app may exist under different storefronts with different availability, pricing tiers, and update cadences. When managing VPP apps across a multi-region fleet, Esper needs to know which App Store storefront to use for each app. This endpoint sets that per-app region preference. The available regions to select from are those already configured at the tenant level via POST /v2/preferred-regions (up to five). In the Console, this setting is accessible when adding or editing an app under Apps > VPP Apps.\n\n**Key Fields**\n\nappleAppId (path, required) — the Apple numeric App Store ID for the VPP app (e.g., 361309726)\n\npreferred_region (required) — ISO 3166-1 alpha-2 country code (uppercase) for the desired App Store storefront (e.g., \"US\", \"GB\", \"AU\"); must be one of the regions already added to the tenant's preferred region list\n\n**Common Use Cases**\n\nAssigning each VPP app to the App Store storefront matching the primary device region where it is deployed\nCorrecting a region mismatch when devices in a specific country are failing to receive app updates\nReconfiguring app storefronts after an organizational expansion into a new country\nBest Practices\n\nOnly assign a region that is already in the tenant's configured preferred region list — the available options are set via POST /v2/preferred-regions\nMatch the app's region to the physical operating region of the devices it is assigned to, not the billing region of the VPP token\nAudit per-app region assignments when expanding into new countries to prevent silent update failures\nWorkflow\n\nConfirm the desired country is in the tenant's preferred region list via GET /v2/preferred-regions\nPUT to /v2/itunesapps/{appleAppId}/preferred-region with { \"preferred_region\": \"US\" } (or the appropriate code)\nVerify the response message confirms success; subsequently, device updates for that app will use the assigned storefront\n", "tags": [ "apps_management_VPP App Management" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_SetPreferredRegionRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "message": { "type": "string", "example": "Preferred region updated successfully" } } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } } }, "/v2/itunesapps/{appId}/refresh-version": { "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "parameters": [ { "in": "path", "required": true, "name": "appId", "schema": { "type": "string", "format": "uuid" }, "description": "The internal Esper app id (UUID) of the VPP app" } ], "summary": "Force refresh of VPP app version metadata", "description": "Forces an on-demand refresh of a single VPP app's iTunes version metadata.\n\nSynchronously re-fetches the latest iTunes metadata for the given app under the caller's tenant and persists it, using the same write path as the daily VPP version cron job, but scoped to just that one (tenant, app_id) pair. Returns the refreshed app details directly so callers can render updated info without a follow-up GET.\n\n**About VPP App Refresh**\n\nVPP apps are normally kept in sync with Apple's iTunes catalog via a daily background cron job; this endpoint lets a caller trigger that same sync immediately for a single app rather than waiting for the next scheduled run.\n\n**Key Fields / Query Parameters**\n\n- appId — UUID of the VPP app to refresh, passed in the path\n\n**Common Use Cases**\n\n- Immediately pulling a newly released app version's metadata into Esper instead of waiting for the daily cron\n- Refreshing stale iTunes metadata (icon, version, size) for a specific app right before deployment\n\n**Best Practices**\n\n- Use this for one-off, on-demand refreshes rather than as a substitute for the daily sync — it's scoped to a single app, not the full catalog\nSynchronously re-fetches the latest iTunes metadata for a single VPP\napp under the caller's tenant and persists it. Same write path as the\ndaily VPP version cron, scoped to one (tenant, app_id). Returns\nthe refreshed app details so the UI can render without a follow-up GET.\n", "tags": [ "apps_management_VPP App Management" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/apps_management_ItunesAppInfoV2" } } } } } }, "400": { "description": "Bad Request (invalid app_id or missing headers)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found (no vpp_app_ids row for the tenant + app_id, or app not found in iTunes)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } } }, "/v2/tenant-apps": { "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "summary": "Upload tenant app for a tenant", "description": "Uploads a new iOS or Windows app file to the tenant's app catalog.\n\nAccepts a multipart file upload along with a platform value and returns the newly created app and version identifiers.\n\n**About Upload Tenant App**\n\n⚠️ iOS and Windows only. This is how enterprise apps for iOS and Windows devices get into Esper for later assignment to blueprints or installation via commands. If the appId already exists for a re-uploaded app, this call creates a new version under that app rather than a duplicate app record; confirm which behavior applies for your platform before assuming either outcome.\n\n**Key Fields / Request Body**\n\nplatform — the target platform, APPLE or WINDOWS, required\n\nfile — the app binary to upload, required\n\n**Common Use Cases**\n\nPublishing a new iOS or Windows enterprise app for the first time\n\nUploading a new build of an already-published app as a new version\n\n**Best Practices**\n\nCapture both the id and version_id from the upload response immediately, since later calls may need either one\n\nConfirm the platform value matches the actual file type before uploading, since this determines how the app is validated and distributed\n\n**Workflow**\n\nPrepare the app file and confirm its target platform\n\nPOST the file as multipart form data to this endpoint\n\nCapture the returned id and version_id\n\nReference the app in a blueprint version or install command to distribute it to devices\n", "tags": [ "apps_management_Tenant Apps" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/apps_management_AppUploadRequestBody" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/apps_management_TenantAppUploadResponse" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_403_Forbidden" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } }, "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "number" } }, { "in": "query", "name": "offset", "schema": { "type": "number" } }, { "in": "query", "name": "platform", "schema": { "type": "string", "enum": [ "APPLE", "WINDOWS" ] } }, { "in": "query", "name": "package_name", "schema": { "type": "string" } }, { "in": "query", "name": "app_name", "schema": { "type": "string" } } ], "summary": "Get tenant apps for a tenant", "description": "Retrieves a paginated list of all tenant-uploaded apps for iOS and Windows devices.\n\nReturns each app's TenantAppResponse record, filterable by platform, package name, and app name.\n\n**About Get Tenant Apps**\n\n⚠️ iOS and Windows only. Tenant Apps are enterprise apps uploaded directly to Esper for distribution to iOS or Windows devices. This is the tenant-wide catalog view, separate from Tenant Esper Apps (Esper-provided apps) and from Android enterprise apps, which live in the older Application V1 API.\n\n**Key Fields / Query Parameters**\n\nplatform — filters by APPLE or WINDOWS\n\npackage_name — filters by exact package name\n\napp_name — filters by app name\n\n**Common Use Cases**\n\nBrowsing the full catalog of uploaded iOS and Windows apps before assigning one to a blueprint\n\nFinding an app's id to look up its available versions\n\n**Best Practices**\n\nFilter by platform when working with a single-OS fleet to avoid paging through apps for the other platform\n\nUse package_name to find a specific app quickly rather than searching by app_name alone, since app_name is not guaranteed to be unique\n\n**Workflow**\n\nCall this endpoint with the desired filters\n\nIdentify the appId for the app you need\n\nCall GET /v2/tenant-apps/{appId}/versions to see its available versions\n", "tags": [ "apps_management_Tenant Apps" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "count": { "type": "integer", "description": "number of results returned" }, "prev": { "type": "string", "description": "URL for previous page of results" }, "next": { "type": "string", "description": "URL for next page of results" }, "results": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/apps_management_TenantAppResponse" } ] } } } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } } }, "/v2/tenant-apps/{appId}": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "parameters": [ { "in": "path", "required": true, "name": "appId", "schema": { "type": "string", "format": "uuid" } } ], "summary": "Get tenant app by ID", "description": "Retrieves a single tenant app's detail record by its ID.\n\nReturns the TenantAppResponse object for the given appId, including its platform, package name, and audit timestamps.\n\n**About Get Tenant App**\n\n⚠️ iOS and Windows only. This is the single-app counterpart to the tenant apps list, useful once you already have an appId and need its current record.\n\n**Common Use Cases**\n\nConfirming an app's platform and package name before referencing it in a blueprint\n\nChecking when an app record was last updated\n\n**Best Practices**\n\nUse GET /v2/tenant-apps/{appId}/versions immediately after this call if you need the app's installable versions, since this endpoint does not return version detail\n\n**Workflow**\n\nObtain the appId from the tenant apps list or from the upload response\n\nCall this endpoint to retrieve its detail record\n", "tags": [ "apps_management_Tenant Apps" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/apps_management_TenantAppResponse" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } } }, "/v2/tenant-apps/{appId}/versions": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "parameters": [ { "in": "path", "required": true, "name": "appId", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "limit", "schema": { "type": "number" } }, { "in": "query", "name": "offset", "schema": { "type": "number" } }, { "in": "query", "name": "app_name", "schema": { "type": "string" } }, { "in": "query", "name": "app_type", "schema": { "type": "string" }, "description": "Filter by app type. When TENANT_WINDOWS_EXE, response items include is_active." }, { "in": "query", "name": "is_active", "schema": { "type": "boolean" }, "description": "Filter by active status. Only supported when app_type=TENANT_WINDOWS_EXE. Returns 400 if used with any other app_type." }, { "in": "query", "name": "legacy_format", "schema": { "type": "boolean", "default": true }, "description": "If false, returns version_code instead of build_number. Defaults to true for backward compatibility." } ], "summary": "Get tenant app versions by app ID", "description": "Retrieves a paginated list of every version uploaded for a specific tenant app.\n\nReturns each version's TenantAppVersionResponse record. The legacy_format parameter controls whether version identification is returned as the legacy build_number or the newer version_code.\n\n**About Get Tenant App Versions**\n\n⚠️ iOS and Windows only. Every time a new build of a tenant app is uploaded, it becomes a new version under the same appId. This endpoint lists all of them, which is the standard way to find the version_id needed to install a specific build or to reference in a blueprint.\n\n**Key Fields / Query Parameters**\n\nlegacy_format — when true (the default), returns build_number for backward compatibility; set to false to receive version_code instead\n\napp_name — filters by app name\n\n**Common Use Cases**\n\nFinding the latest version of an app before assigning it to a blueprint\n\nAuditing the upload history of a tenant app\n\n**Best Practices**\n\nSet legacy_format to false in new integrations to work with version_code directly, rather than relying on the legacy build_number field\n\nSort or filter results to confirm you're referencing the intended version before using it in a blueprint or install command\n\n**Workflow**\n\nCall this endpoint with the appId\n\nIdentify the versionId of the version you need\n\nCall GET /v2/tenant-apps/{appId}/versions/{versionId} for that version's full detail\n", "tags": [ "apps_management_Tenant Apps" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "count": { "type": "integer", "description": "number of results returned" }, "prev": { "type": "string", "description": "URL for previous page of results" }, "next": { "type": "string", "description": "URL for next page of results" }, "results": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/apps_management_TenantAppVersionResponse" } ] } } } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } } }, "/v2/tenant-apps/{appId}/versions/{versionId}": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "parameters": [ { "in": "path", "required": true, "name": "appId", "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "required": true, "name": "versionId", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "legacy_format", "schema": { "type": "boolean", "default": true }, "description": "If false, returns version_code instead of build_number. Defaults to true for backward compatibility." } ], "summary": "Get tenant app version by ID", "description": "Retrieves the full detail record for a single tenant app version.\n\nReturns the TenantAppVersionDetailResponse for the given appId and versionId, with the same legacy_format option for choosing between build_number and version_code.\n\n**About Get Tenant App Version**\n\n⚠️ iOS and Windows only. This is the detail view behind a single entry in the app's version list, useful once you already have both the appId and versionId.\n\n**Common Use Cases**\n\nConfirming a specific version's detail before referencing it in a blueprint or install command\n\nAuditing a specific build's metadata\n\n**Best Practices**\n\nSet legacy_format to false to receive version_code if your integration doesn't depend on the legacy build_number field\n\n**Workflow**\n\nObtain the appId and versionId from the versions list\n\nCall this endpoint for the full version detail\n", "tags": [ "apps_management_Tenant Apps" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/apps_management_TenantAppVersionDetailResponse" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } }, "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "parameters": [ { "in": "path", "required": true, "name": "appId", "schema": { "type": "string" } }, { "in": "path", "required": true, "name": "versionId", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "description": "At least one field must be provided. All fields are optional\n(omitted = leave unchanged). `version_name` and `exe_config`\nare only accepted for EXE app versions; rejected with 400 otherwise.\n", "properties": { "description": { "type": "string" }, "version_name": { "type": "string", "maxLength": 64, "description": "Version name. Only valid for EXE app versions." }, "exe_config": { "description": "EXE configuration. Only valid for TENANT_WINDOWS_EXE app versions; rejected with 400 otherwise.", "allOf": [ { "$ref": "#/components/schemas/apps_management_WindowsExeConfigRequest" } ] } } } } } }, "summary": "Update tenant app version by ID", "description": "Updates the description field on a specific tenant app version.\n\nThis is a narrow update endpoint; the only writable field is description, so it's used for annotating a version rather than changing its binary or platform.\n\n**About Update Tenant App Version**\n\n⚠️ iOS and Windows only. Because the app binary itself is immutable once uploaded, this endpoint only supports updating the version's description. To change the actual app content, upload a new version through POST /v2/tenant-apps instead.\n\n**Key Fields / Request Body**\n\ndescription — the only writable field on this endpoint\n\n**Common Use Cases**\n\nAdding release notes or context to an already-uploaded version\n\nCorrecting a typo in a version's description after upload\n\n**Best Practices**\n\nDo not expect this endpoint to change anything beyond description, including platform or the app binary\n\n**Workflow**\n\nObtain the appId and versionId for the version you want to annotate\n\nPUT the updated description to this endpoint\n\nConfirm the change with a follow-up GET on the version detail\n", "tags": [ "apps_management_Tenant Apps" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/apps_management_TenantAppVersionResponse" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_403_Forbidden" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "parameters": [ { "in": "path", "required": true, "name": "appId", "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "required": true, "name": "versionId", "schema": { "type": "string", "format": "uuid" } } ], "summary": "Delete tenant app version by ID", "description": "Permanently deletes a single version of a tenant-uploaded iOS or Windows app.\n\nRemoves the specified versionId from the app identified by appId. This deletes only that version's record, not the parent app or its other versions.\n\n**About Delete Tenant App Version**\n\n⚠️ iOS and Windows only. Tenant Apps are enterprise apps uploaded directly for iOS or Windows devices, distinct from Android enterprise apps, which are managed through the separate Application V1 API. Deleting a version removes it from the catalog, so it can no longer be installed on new devices, though devices that already have it installed are not automatically affected.\n\n**Common Use Cases**\n\nRemoving an outdated or broken app version from the catalog\n\nCleaning up test or pre-release versions after a stable version has been published\n\n**Best Practices**\n\nConfirm no active blueprints or pending install commands reference the version before deleting it\n\nDelete older versions only after confirming devices have moved to a newer version, if version continuity matters for your fleet\n\n**Workflow**\n\nCall GET /v2/tenant-apps/{appId}/versions to confirm the versionId you intend to delete\n\nDELETE the version using its appId and versionId\n\nConfirm the deletion with a follow-up GET on the versions list\n", "tags": [ "apps_management_Tenant Apps" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/apps_management_TenantAppVersionResponse" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_403_Forbidden" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } } }, "/v2/tenant-apps/{appId}/versions/{versionId}/artifacts": { "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "parameters": [ { "in": "path", "required": true, "name": "appId", "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "required": true, "name": "versionId", "schema": { "type": "string", "format": "uuid" } } ], "summary": "Add an artifact to a UWP app version", "description": "Adds an artifact to a UWP (Windows) app version.\n\nUploads a per-version artifact such as a UWP framework dependency package (.msix/.appx) for a TENANT_WINDOWS_UWP app version.\n\n**About Tenant App Version Artifacts**\nUWP (Universal Windows Platform) apps can require additional framework dependencies or signing certificates beyond the main app package. Artifacts let Esper store and deploy these supporting files alongside a specific app version, rather than bundling everything into the app package itself.\n\n**Key Fields / Query Parameters**\n- `appId` — UUID of the tenant app\n- `versionId` — UUID of the specific app version to attach the artifact to\n- `artifact_type` — A .msix/.appx framework package\n- `file` — The artifact file to upload\n\n**Common Use Cases**\n- Attaching a required framework dependency package to a UWP app version so it installs successfully\n- Uploading a signing certificate needed to validate a UWP app package\n- Managing multiple supporting files across different versions of the same Windows app\n\n**Best Practices**\n- Confirm artifact_type matches the actual file being uploaded — dependency packages and certificates are validated differently\n- Upload all required dependencies before attempting to deploy the app version to devices\n- Keep track of which artifacts belong to which versionId, since artifacts are version-scoped, not app-wide\n\n**Workflow**\n1. Identify the appId and versionId the artifact belongs to\n2. POST the artifact file with the correct artifact_type\n3. Confirm successful upload before deploying that app version to Windows devices\n", "tags": [ "apps_management_Tenant Apps" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "artifact_type", "file" ], "properties": { "artifact_type": { "type": "string", "enum": [ "UWP_DEPENDENCY", "UWP_CERTIFICATE" ], "description": "The kind of artifact being uploaded." }, "file": { "type": "string", "format": "binary", "description": "The artifact file. For UWP_DEPENDENCY a .msix/.appx package;\nfor UWP_CERTIFICATE a .cer signing certificate.\n" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/apps_management_ArtifactMutationResponse" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found (the app version does not exist)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } } }, "/v2/tenant-apps/{appId}/versions/{versionId}/artifacts/{artifactId}": { "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "parameters": [ { "in": "path", "required": true, "name": "appId", "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "required": true, "name": "versionId", "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "required": true, "name": "artifactId", "schema": { "type": "string", "format": "uuid" }, "description": "The id of the artifact to delete." } ], "summary": "Delete an artifact from a UWP app version", "description": "Deletes an artifact from a UWP app version.\n\nRemoves the specified per-version artifact (a dependency package or signing certificate) by its ID, deleting both the stored file and its record. The app version must be removed for all associated blueprints and blueprint versions prior to deletion.\n\n**About Tenant App Version Artifacts**\nUWP apps can have framework dependency packages or signing certificates attached at the version level. Deleting an artifact is irreversible and may affect the app version's ability to install correctly if the artifact was required.\n\n**Key Fields / Query Parameters**\n- `appId` — UUID of the tenant app\n- `versionId` — UUID of the app version the artifact belongs to\n- `artifactId` — UUID of the artifact to delete\n\n**Common Use Cases**\n- Removing an outdated or incorrect dependency package from an app version\n- Cleaning up an expired signing certificate no longer needed\n- Correcting an artifact upload made in error before the app version is deployed\n\n**Best Practices**\n- Confirm the artifact is not required for the version's current deployment before deleting\n- Upload a replacement artifact first if the app version still needs an equivalent dependency or certificate\n- Double-check appId/versionId/artifactId together, since artifact IDs are scoped to a specific app version\n\n**Workflow**\n1. Identify the artifactId to remove (via the app version's detail)\n2. DELETE using appId, versionId, and artifactId\n3. Upload a replacement artifact if the app version still requires one\n", "tags": [ "apps_management_Tenant Apps" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/apps_management_ArtifactMutationResponse" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } } }, "/v2/appleappstore/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "parameters": [ { "name": "title", "in": "query", "required": true, "schema": { "type": "string" } } ], "summary": "Search Apple App Store", "description": "⚠️ Apple devices only. This endpoint searches Apple's App Store for apps available for deployment to Apple-managed devices.\n\nSearches the Apple App Store by app title (required), returning matching app records with metadata including icon, bundle ID, file size, App Store URL, minimum OS version, release date, and seller name.\n\n**About Search Apple App Store**\n\nThis endpoint proxies a title-based search against Apple's App Store, enabling integrators to discover apps by name before adding them to Esper for deployment. Unlike GET /api/v2/itunesapps, which retrieves metadata for apps already in Esper's system, this endpoint queries the App Store directly and does not require the app to already exist in the tenant library. Results include the bundle_id needed to identify the app in subsequent VPP or deployment workflows. This is a discovery tool — app installation and deployment are handled through VPP licensing and blueprint or operation endpoints.\n\n**Key Query Parameters / Fields**\n\ntitle (required) — App title search string\n\nname (response) — App name as listed in the App Store\n\nbundle_id (response) — Bundle identifier (e.g., com.apple.mobilesafari); use this in VPP and deployment workflows\n\nicon (response) — URL for the app's icon\n\napp_store_url (response) — Direct link to the app's App Store listing\n\nminimum_os (response) — Minimum iOS version required\n\nfile_size_in_bytes (response) — App binary size in bytes\n\nrelease_date (response) — App release date in ISO 8601 format\n\nseller_name (response) — App developer or publisher name\n\n**Common Use Cases**\n\nSearching for an app by name to retrieve its bundle_id before configuring a VPP install or blueprint\nVerifying minimum OS version compatibility before targeting a specific iOS device group\nConfirming app availability and publisher identity before adding it to the tenant's VPP library\n\n**Best Practices**\n\nUse specific, well-formed title strings — broad or partial searches may return large result sets; use the bundle_id from results to uniquely identify the target app\n\nVerify minimum_os against the OS versions in your device fleet before targeting an app for deployment\n\nThis endpoint is for discovery only — use VPP licensing endpoints and blueprint or operation endpoints to configure and deploy the app\n", "tags": [ "apps_management_Apple App Store" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "count": { "type": "integer", "description": "number of results returned" }, "prev": { "type": "string", "description": "URL for previous page of results" }, "next": { "type": "string", "description": "URL for next page of results" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/apps_management_AppleAppStoreApp" } } } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } } }, "/v2/apps": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "number" } }, { "in": "query", "name": "offset", "schema": { "type": "number" } }, { "in": "query", "name": "search", "schema": { "type": "string" } }, { "in": "query", "name": "ordering", "schema": { "type": "string", "enum": [ "name", "created_at", "updated_at" ] } }, { "in": "query", "name": "app_type", "schema": { "type": "string" } }, { "in": "query", "name": "legacy_format", "schema": { "type": "boolean", "default": true }, "description": "If false, returns version_code instead of build_number. Defaults to true for backward compatibility." } ], "summary": "Get unified list of iOS apps (IPAs and Webclips) for a tenant", "description": "⚠️ Apple devices and Windows only. This endpoint returns Window or iOS app records only. Android apps use the Application V1 API (https://api.esper.io/openapi/esper_cloud_api_application-v1).Retrieves a unified, paginated list of all iOS and Windows apps in the tenant library, spanning MSI, IPA-based tenant apps, and webclips, in a single normalized view.\n\n**About List Windows or iOS Apps (Unified)**\n\nThis endpoint provides a single list across iOS and Windows app types — TENANT_IOS, WEBCLIP, and TENANT_WINDOWS entries — surfaced as AppInfo records. Unlike the type-specific endpoints (GET /api/v2/tenant-apps and GET /api/v2/webclips), this unified view is useful when you need a single inventory sweep of all deployable iOS app entries regardless of type. The app_type filter can be used to scope results to a specific type. The AppInfo schema covers both IPA and webclip-specific fields — fields like url, is_full_screen, and is_removable are relevant for webclips, while file_size_in_kb, build_number/version_code, and min_sdk_version apply to IPA-based apps. The legacy_format parameter controls whether the response uses build_number (default) or version_code.\n\n**Key Query Parameters**\n\napp_type — Filter by app type (e.g., TENANT_IOS, WEBCLIP, TENANT_WINDOWS)\n\nsearch — Search by app name or label\n\nordering — Sort by name, created_at, or updated_at\n\nlegacy_format — true (default): build_number; false: version_code\n\n**Common Use Cases**\n\nGenerating a complete inventory of all deployable iOS apps and webclips in the tenant\n\nSearching by name across both app types in a single call before blueprint configuration\n\nAuditing app library contents by type using the app_type filter\n\n**Best Practices**\n\nUse app_type to filter when only IPAs or only webclips are needed — the combined list can be large for tenants with many apps\n\nUse legacy_format=false in new integrations to consume version_code\n\nFor type-specific detail (e.g., presigned download URL or webclip icon), follow up with the appropriate scoped endpoint\n", "tags": [ "apps_management_App List" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "count": { "type": "integer", "description": "number of results returned" }, "prev": { "type": "string", "description": "URL for previous page of results" }, "next": { "type": "string", "description": "URL for next page of results" }, "results": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/apps_management_AppInfo" } ] } } } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } } }, "/v2/webclips": { "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "summary": "Create webclip for a tenant", "description": "⚠️ iOS/iPadOS only. Webclips are home screen shortcuts for iOS and iPadOS managed devices.\n\nCreates a new webclip in the tenant library, making it available for deployment to iOS/iPadOS managed devices via blueprint or install operation.\n\n**About Create Webclip**\n\nA webclip is a home screen bookmark that opens a specified URL in a browser or within a target app, appearing as an app icon on the device. In Esper, webclips are managed as a distinct app type (WEBCLIP) within the iOS app system. The request uses multipart/form-data and requires label, esper_name, url, target_bundle_id, target_bundle_name, is_full_screen, and is_removable. An optional icon binary can be uploaded to set a custom home screen icon. The target_bundle_id and target_bundle_name identify the iOS app that will handle the URL (e.g., Safari). A 409 response indicates a webclip with a conflicting identifier already exists.\n\n**Key Fields**\n\nlabel (required) — Display name shown on the device home screen\n\nesper_name (required) — Internal name for the webclip in Esper (used for lookup and management)\n\nurl (required) — The URL the webclip opens\n\ntarget_bundle_id (required) — Bundle ID of the app that handles the URL (e.g., com.apple.mobilesafari)\n\ntarget_bundle_name (required) — Display name of the target bundle (e.g., Safari)\n\nis_full_screen (required) — Whether the webclip opens in full-screen mode\n\nis_removable (required) — Whether the user can remove the webclip from the home screen\n\nicon (optional) — Custom icon binary for the home screen shortcut\n\n**Common Use Cases**\n\nCreating a home screen shortcut to an internal web app or portal for field devices\n\nAdding a branded webclip with a custom icon that opens in full-screen kiosk-style mode\n\nDeploying a managed browser link that users cannot remove from the home screen\n\n**Best Practices**\n\nSet is_removable=false for compliance-critical or kiosk-mode webclips that should not be user-removable\n\nUse a descriptive esper_name that distinguishes webclips with similar labels — it is the primary lookup identifier in Esper\n\nAfter creation, capture the returned id (webclip UUID) for blueprint configuration or install operations\n\n**Workflow**\n\nPrepare the webclip details — URL, target bundle, label, and icon if needed\n\nSubmit the multipart/form-data POST with all required fields\n\nCapture the returned webclip id for use in blueprint or operation configuration\n", "tags": [ "apps_management_Webclips" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/apps_management_WebclipCreateRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/apps_management_Webclip" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_409_Conflict" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } }, "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "number" } }, { "in": "query", "name": "offset", "schema": { "type": "number" } }, { "in": "query", "name": "label", "schema": { "type": "string" } }, { "in": "query", "name": "exact_esper_name", "schema": { "type": "string" } } ], "summary": "Get webclips for a tenant", "description": "⚠️ Apple devices only.\n\nRetrieves a paginated list of all webclips in the tenant library, with optional filtering by label or internal Esper name.\n\n**About List Webclips**\n\nReturns Webclip records for all webclips uploaded to the tenant — the same resource created by POST /api/v2/webclips. Each record includes the webclip's UUID, label, URL, target bundle details, full-screen and removability flags, icon URL, and audit timestamps. The exact_esper_name filter performs an exact-match lookup on the internal esper_name field, useful for finding a specific webclip by its Esper identifier without paginating through the full list. For a unified view of webclips alongside IPA-based apps, use GET /api/v2/apps with app_type=WEBCLIP.\n\n**Key Query Parameters**\n\nlabel — Filter by webclip display label (partial match)\n\nexact_esper_name — Exact-match filter on the internal esper_name field\n\n**Common Use Cases**\n\nLooking up a specific webclip's UUID by its esper_name for use in blueprint or operation configuration\n\nAuditing all webclips in the tenant library before a deployment or cleanup operation\n\nVerifying webclip details (URL, target bundle, removability) before assigning to a blueprint\n\n**Best Practices**\n\nUse exact_esper_name when you know the internal name — it is more precise than label and avoids ambiguity with similarly labeled webclips\n\nPaginate with limit and offset for tenants with large webclip libraries\n", "tags": [ "apps_management_Webclips" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "count": { "type": "integer", "description": "number of results returned" }, "prev": { "type": "string", "description": "URL for previous page of results" }, "next": { "type": "string", "description": "URL for next page of results" }, "results": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/apps_management_Webclip" } ] } } } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } } }, "/v2/webclips/{webclipId}": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "parameters": [ { "in": "path", "required": true, "name": "webclipId", "schema": { "type": "string", "format": "uuid" } } ], "summary": "Get webclip by id for a tenant", "description": "⚠️ iOS/iPadOS only.\n\nRetrieves the full record for a specific webclip by its Esper UUID.\nReturns a single Webclip object with all fields including label, URL, target bundle ID and name, full-screen mode, removability, icon URL, and audit timestamps.\n\n**About Get Webclip**\n\nThis endpoint fetches the complete detail record for a single webclip, identified by its Esper-assigned UUID. It is the direct lookup complement to GET /api/v2/webclips — use it when you already have the webclipId and need to confirm current configuration or retrieve specific field values before an update or deployment operation. The response is identical in structure to webclip records returned by the list endpoint.\n\n**Key Fields**\n\nwebclipId (path) — Esper webclip UUID (required)\n\nlabel — Home screen display name\n\nurl — URL the webclip opens\n\ntarget_bundle_id / target_bundle_name — iOS app handling the URL\n\nis_full_screen / is_removable — Behavioral flags\n\nicon_url — URL for the webclip's home screen icon (nullable)\n\n**Common Use Cases**\n\nConfirming webclip configuration details before including it in a blueprint\n\nRetrieving current url or target bundle values for audit or documentation purposes\n\nPre-flight check before a DELETE to confirm the correct webclip is targeted\n\n**Best Practices**\n\nUse this as a pre-flight check before DELETE operations to confirm the correct webclipId is targeted\n\nIf the webclipId is unknown, use GET /api/v2/webclips with exact_esper_name to look it up first\n", "tags": [ "apps_management_Webclips" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/apps_management_Webclip" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "parameters": [ { "in": "path", "required": true, "name": "webclipId", "schema": { "type": "string", "format": "uuid" } } ], "summary": "Delete webclip for a tenant", "description": "⚠️ Apple devices only.\n\nDeletes a specific webclip from the tenant library by its Esper UUID, returning the deleted webclip record.\nThe deletion is permanent. A 409 response indicates the webclip cannot be deleted because it is currently referenced by an active blueprint or configuration.\n\n**About Delete Webclip**\n\nDeleting a webclip removes it from the tenant library and makes it unavailable for new deployments. The 200 response returns the complete Webclip record for the deleted entry — retain it for audit purposes. The 409 Conflict response is significant: it indicates the webclip is still referenced in a blueprint or active configuration and must be removed from those references before deletion can proceed. Devices that already have the webclip installed are not immediately affected by deletion from the library — the webclip remains on those devices until actively removed via an operation or blueprint change.\n\n**Key Fields**\n\nwebclipId (path) — Esper webclip UUID (required)\n\nResponse — The deleted Webclip record\n\n**Common Use Cases**\n\nRemoving an outdated or incorrect webclip from the tenant library\nCleaning up test webclips created during development or blueprint configuration\nDecommissioning a webclip for a retired internal web application\n\n**Best Practices**\n\nIf you receive a 409, use GET /api/v2/webclips/{webclipId} to confirm which blueprints and blueprint versions reference the webclip, then remove those references before retrying the delete\n\nStore the returned Webclip record from the 200 response for audit trail purposes\n\nNote that deletion removes the webclip from the console but does not uninstall it from devices where it is already deployed — use an uninstall operation for that\n", "tags": [ "apps_management_Webclips" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/apps_management_Webclip" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_404_Not_Found" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_409_Conflict" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } } }, "/v2/provisioning-profiles": { "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "summary": "Upload provisioning profile for a tenant", "description": "⚠️ Apple devices only.\n\nUpload a .mobileprovision file to register an iOS provisioning profile for use with Enterprise app distribution in Esper.\nThe uploaded file is parsed and validated by Esper, which extracts the App ID, team identifier, profile type, expiration date, and entitlements. The resulting profile record is then available to attach to blueprints. App Store (VPP) apps distributed through Apple's App Store do not require provisioning profiles.\n\n**About Upload Provisioning Profile**\niOS provisioning profiles are Apple-issued authorization files that enable Enterprise apps to run on iOS and iPadOS devices without going through the App Store. In Esper, provisioning profiles are uploaded here, then associated with specific blueprints via the blueprint's iOS app configuration. Each upload creates a new version under a profile record keyed by App ID; uploading a .mobileprovision file with the same App ID as an existing profile creates an additional version rather than overwriting it.\n\n**Key Fields / Request Body**\n\nfile (required) — The .mobileprovision binary file to upload, sent as multipart/form-data\n\nid (response) — Esper's UUID for the parent provisioning profile record\n\nversion_id (response) — UUID for this specific uploaded version\n\napp_identifier (response) — The app's bundle ID extracted from the file (e.g., com.example.app)\n\nprofile_type (response) — One of development, ad-hoc, app-store, or enterprise\n\nexpiration_date (response) — When Apple's authorization on this profile expires\n\n**Common Use Cases**\n\nRegistering a new app profile before attaching it to a blueprint\n\nAdding an updated or renewed profile version for an app whose previous profile is nearing expiration\n\nManaging multiple profile versions for the same App ID across development and enterprise distribution types\n\n**Best Practices**\n\nUpload profiles before configuring blueprints — the profile must exist in Esper before it can be added to a blueprint's iOS tab\n\nTrack expiration_date in the response and plan renewals before profiles expire, as expired profiles will block app installation on devices\n\nUploading a file with the same App ID as an existing profile creates a new version; verify which version blueprints are using after uploading renewals\n\n**Workflow**\n\nObtain the .mobileprovision file from the Apple Developer portal for the Enterprise app\n\nPOST the file to this endpoint as multipart/form-data and capture the returned id and version_id\n\nNavigate to the target blueprint's Apps & Configuration > iOS tab and use Add Provisioning Profile to attach the uploaded profile\n\nSet the expiration date in the blueprint configuration, then save, publish, and converge to apply to devices\n", "tags": [ "apps_management_Provisioning Profiles" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/apps_management_ProvisioningProfileUploadRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/apps_management_ProvisioningProfileUploadResponse" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } }, "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "number", "description": "Maximum number of provisioning profiles to return", "default": 10 } }, { "in": "query", "name": "offset", "schema": { "type": "number", "description": "Number of provisioning profiles to skip", "default": 0 } }, { "in": "query", "name": "app_identifier", "schema": { "type": "string", "description": "Filter by bundle identifier of the associated app" } }, { "in": "query", "name": "profile_type", "schema": { "type": "string", "description": "Filter by profile type", "enum": [ "development", "ad-hoc", "app-store", "enterprise" ] } }, { "in": "query", "name": "team_id", "schema": { "type": "string", "description": "Filter by Apple Developer Team identifier" } }, { "in": "query", "name": "search", "schema": { "type": "string", "description": "Search in provisioning profile names and identifiers" } } ], "summary": "Get provisioning profiles for a tenant", "description": "⚠️ Apple devices only.\n\nRetrieve a paginated list of all iOS provisioning profiles registered for the tenant, including a signed download URL for each profile file.\nReturns profile metadata extracted from uploaded .mobileprovision files — App ID, team identifier, profile type, and expiration date — along with a signed download_url for retrieving the raw file. Results default to 10 per page and can be filtered by app_identifier, profile_type, team_id, or searched by name and identifier.\n\n**About List Provisioning Profiles**\n\nProvisioning profiles in Esper are uploaded per tenant and then attached to blueprints to authorize Enterprise iOS apps on managed devices. This endpoint provides the full tenant inventory of profiles, useful for auditing coverage, identifying profiles nearing expiration, and confirming which App IDs are registered. Each record represents a profile keyed by App ID; individual uploads of the same App ID create versioned records accessible via the versions sub-resource.\n\n**Key Fields / Query Parameters**\n\nlimit — Max results per page; defaults to 10\n\noffset — Number of records to skip for pagination; defaults to 0\n\napp_identifier — Filter by bundle ID (e.g., com.example.app)\n\nprofile_type — Filter by development, ad-hoc, app-store, or enterprise\n\nteam_id — Filter by Apple Developer Team identifier\n\nsearch — Search within profile names and identifiers\n\ndownload_url (response) — Signed S3 URL for downloading the .mobileprovision file\n\n**Common Use Cases**\n\nAuditing which Enterprise app IDs have registered provisioning profiles in the tenant\nIdentifying profiles approaching expiration before device-side installation failures occur\nRetrieving profile IDs needed to fetch version history or attach profiles to blueprints via the API\n\n**Best Practices**\n\nFilter by profile_type=enterprise to focus on profiles relevant to Enterprise app distribution\n\nUse app_identifier filtering when managing profiles for a specific app across multiple versions\n\nPaginate with limit and offset for tenants with large profile inventories; next and prev URLs are included in the response\n", "tags": [ "apps_management_Provisioning Profiles" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of provisioning profiles" }, "prev": { "type": "string", "description": "URL for previous page of results" }, "next": { "type": "string", "description": "URL for next page of results" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/apps_management_ProvisioningProfileWithDownloadResponse" } } } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } } }, "/v2/provisioning-profiles/{id}": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "parameters": [ { "in": "path", "required": true, "name": "id", "schema": { "type": "string", "format": "uuid", "description": "Unique identifier for the provisioning profile" } } ], "summary": "Get provisioning profile by ID", "description": "⚠️ Apple devices only.\n\nRetrieve a single iOS provisioning profile record by its Esper-assigned UUID, including a signed download URL for the profile file.\nReturns the full metadata for the profile — App ID, team identifier, profile type, expiration date, and audit fields — along with a download_url for downloading the .mobileprovision file. Use this endpoint to confirm profile details before attaching to a blueprint or to retrieve the download link for the current profile file.\n\n**About Get Provisioning Profile by ID**\n\nEach provisioning profile in Esper is identified by a UUID assigned at upload time. The profile record represents the app identity (App ID) level of the hierarchy; individual uploads of the same App ID are tracked as versions under the profile and accessible via the /versions sub-resource. This endpoint returns the profile-level record, not a specific version.\n\n**Key Fields / Path Parameters**\n\nid (required) — Esper UUID of the provisioning profile (returned from upload or list endpoint)\n\ndownload_url (response) — Signed S3 URL for downloading the .mobileprovision file; time-limited\n\napp_identifier (response) — Bundle ID of the associated app\n\nprofile_type (response) — One of development, ad-hoc, app-store, or enterprise\n\nexpiration_date (response) — When the profile authorization expires\n\n**Common Use Cases**\n\nConfirming profile details (type, expiration, App ID) before associating with a blueprint\nGenerating a fresh signed download URL for the profile file\nValidating that a specific profile ID exists and is accessible before referencing it in blueprint configuration\n\n**Best Practices**\n\nUse the list endpoint (GET /v2/provisioning-profiles) to find the id if it isn't already known\n\nThe download_url is a time-limited signed URL; retrieve it fresh when an actual download is needed rather than caching it\n", "tags": [ "apps_management_Provisioning Profiles" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/apps_management_ProvisioningProfileWithDownloadResponse" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } } }, "/v2/provisioning-profiles/{id}/versions": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "parameters": [ { "in": "path", "required": true, "name": "id", "schema": { "type": "string", "format": "uuid", "description": "Unique identifier for the provisioning profile" } }, { "in": "query", "name": "limit", "schema": { "type": "number", "description": "Maximum number of provisioning profile versions to return", "default": 10 } }, { "in": "query", "name": "offset", "schema": { "type": "number", "description": "Number of provisioning profile versions to skip", "default": 0 } }, { "in": "query", "name": "search", "schema": { "type": "string", "description": "Search in provisioning profile version names" } } ], "summary": "Get provisioning profile versions list", "description": "⚠️ Apple devices only.\n\nRetrieve a paginated list of all uploaded versions of a specific iOS provisioning profile, ordered by expiration date descending.\nEach version corresponds to a separate .mobileprovision file upload made for the same App ID. Results include Apple-extracted metadata (UUID, expiration date, entitlements, platforms, developer certificates) and a signed download_url for the version file. Results default to 10 per page and support search by version name.\n\n**About List Provisioning Profile Versions**\n\nEsper allows multiple versions of a provisioning profile to exist under a single profile record (shared App ID), reflecting real-world scenarios where profiles are renewed or updated over time. This endpoint surfaces that version history in descending expiration order — most recent first — making it straightforward to identify which version is current and which are expired. Version IDs retrieved here are used when attaching a specific version to a blueprint or when deleting an obsolete version.\n\n**Key Fields / Query Parameters**\n\nid (path, required) — Esper UUID of the parent provisioning profile\n\nlimit — Max results per page; defaults to 10\n\noffset — Records to skip for pagination; defaults to 0\n\nsearch — Search within version names\n\nexpiration_date (response) — When this version expires; results are ordered by this field descending\n\nuuid (response) — Apple's own UUID for this profile version, distinct from Esper's internal id\n\nprovisions_all_devices (response) — true for enterprise profiles that provision all devices without explicit device registration\n\nsha256_hash (response) — Hash of the file, used for duplicate detection on upload\n\n**Common Use Cases**\n\nReviewing the version history of a profile to confirm which version is currently active in a blueprint\n\nIdentifying expired versions to clean up via the delete endpoint\n\nRetrieving a specific version_id needed to fetch or delete an individual version\n\n**Best Practices**\n\nVersions are ordered by expiration_date descending; the first result is the most recently expiring (current) version\n\nUse sha256_hash to detect duplicate uploads before uploading a new version\n\nWhen renewing profiles, upload the new version first, update the blueprint to reference the new version, then delete the old version\n", "tags": [ "apps_management_Provisioning Profiles" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of provisioning profile versions" }, "prev": { "type": "string", "description": "URL for previous page of results" }, "next": { "type": "string", "description": "URL for next page of results" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/apps_management_ProvisioningProfileVersionWithDownloadResponse" } } } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } } }, "/v2/provisioning-profiles/{id}/versions/{versionId}": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "parameters": [ { "in": "path", "required": true, "name": "id", "schema": { "type": "string", "format": "uuid", "description": "Unique identifier for the provisioning profile" } }, { "in": "path", "required": true, "name": "versionId", "schema": { "type": "string", "format": "uuid", "description": "Unique identifier for the specific version of the provisioning profile" } } ], "summary": "Get provisioning profile version by ID", "description": "⚠️ Apple devices only.\n\nRetrieve a specific version of an iOS provisioning profile by both the parent profile UUID and the version UUID, including a signed download URL for that version's file.\nReturns the full version record: Apple-extracted fields (UUID, expiration date, entitlements, platforms, developer certificates, time_to_live), Esper audit fields, and a signed download_url for the .mobileprovision file. Use this when you need the complete details or download URL for a precise profile version rather than just the most recent one.\n\n**About Get Provisioning Profile Version by ID**\n\nProvisioning profile versions in Esper track individual .mobileprovision uploads associated with a given App ID. A profile can accumulate multiple versions over its lifetime as certificates are renewed or profile configurations change. This endpoint targets a single version by its versionId, making it useful for confirming the exact state of a version currently attached to a blueprint or for generating a fresh download link for a specific version.\n\n**Key Fields / Path Parameters**\n\nid (required) — Esper UUID of the parent provisioning profile\n\nversionId (required) — Esper UUID of the specific profile version\n\nuuid (response) — Apple's own UUID for this version, distinct from Esper's id\n\nexpiration_date (response) — When this version's Apple authorization expires\n\ntime_to_live (response) — Days remaining from creation date to expiration\n\nprovisions_all_devices (response) — true for enterprise profiles covering all devices\n\nentitlements (response) — JSON object of app capabilities granted by this profile\n\ndownload_url (response) — Signed S3 URL for downloading this version's file; time-limited\n\n**Common Use Cases**\n\nRetrieving the full entitlements and certificate details for a specific profile version before attaching it to a blueprint\n\nGenerating a fresh signed download URL for a known profile version\n\nConfirming expiration and time_to_live for a version currently in use by managed devices\n\n**Best Practices**\n\nUse the versions list endpoint (GET /v2/provisioning-profiles/{id}/versions) to discover valid versionId values\n\nThe download_url is time-limited; fetch it fresh when a download is needed\n\nCheck provisions_all_devices to confirm whether the version requires individual device registration or covers all devices (enterprise behavior)\n", "tags": [ "apps_management_Provisioning Profiles" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/apps_management_ProvisioningProfileVersionWithDownloadResponse" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "parameters": [ { "in": "path", "required": true, "name": "id", "schema": { "type": "string", "format": "uuid", "description": "Unique identifier for the provisioning profile" } }, { "in": "path", "required": true, "name": "versionId", "schema": { "type": "string", "format": "uuid", "description": "Unique identifier for the specific version of the provisioning profile to delete" } } ], "summary": "Delete provisioning profile version by ID", "description": "⚠️ Apple devices only.\n\nDelete a specific version of an iOS provisioning profile by profile UUID and version UUID, removing it from the tenant's profile inventory.\nOn success, returns the deleted version record. A version that is currently referenced by a published blueprint cannot be deleted — remove the profile from the blueprint first before deleting the version. Deletion removes the version from Esper's records; the .mobileprovision file will no longer be accessible via Esper.\n\n**About Delete Provisioning Profile Version**\n\nEsper stores provisioning profiles as parent records with one or more versioned uploads underneath. Deletion operates at the version level, not the profile level — deleting all versions of a profile does not automatically remove the parent profile record. This granular control allows teams to retire expired versions while keeping the profile record intact for future uploads. The Console enforces a guard against deleting versions attached to published blueprints; the API similarly returns an error in that case.\n\n**Key Fields / Path Parameters**\n\nid (required) — Esper UUID of the parent provisioning profile\n\nversionId (required) — Esper UUID of the specific version to delete\n\nResponse body contains the deleted version's full record (same schema as the GET version endpoint)\n\n**Common Use Cases**\n\nRemoving an expired profile version to keep the tenant's profile inventory clean\n\nDeleting a version uploaded by mistake before it is attached to any blueprint\n\nCycling out old versions after uploading a renewed profile and updating blueprints to reference the new version\n\n**Best Practices**\n\nConfirm the version is not referenced by any published blueprint before calling this endpoint; the API will reject the deletion if it is\n\nUse the versions list endpoint (GET /v2/provisioning-profiles/{id}/versions) to audit versions before deleting\n\nWhen rotating expired profiles, follow this order: upload renewal → update blueprint → delete expired version\n\n**Workflow**\n\nUse GET /v2/provisioning-profiles/{id}/versions to identify the versionId to remove\n\nConfirm the version is not attached to any published blueprint (detach it first if so)\n\nCall DELETE /v2/provisioning-profiles/{id}/versions/{versionId}\n\nVerify deletion by confirming the version no longer appears in the versions list\n", "tags": [ "apps_management_Provisioning Profiles" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/apps_management_ProvisioningProfileVersionWithDownloadResponse" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } } }, "/v2/preferred-regions": { "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "summary": "Set Preferred Regions for Tenant", "description": "⚠️ Apple devices only.\n\nCreates or replaces the tenant's preferred App Store region list, setting up to five ISO 3166-1 alpha-2 country codes that represent the regions where your organization operates.Submitting an empty countries array clears all preferred region preferences for the tenant. The list set here defines the available region options when assigning a storefront to individual VPP apps via PUT /v2/itunesapps/{appleAppId}/preferred-region. In the Console, this configuration lives in Apple MDM Management settings.\n\n**About Preferred Regions**\n\nMulti-region organizations that distribute VPP apps across countries need to ensure each app's App Store storefront matches the operating region of its target devices. The preferred regions list is the tenant-level foundation for that configuration — it defines the pool of allowed storefronts (up to five) from which per-app regions are then selected. This is a replace-style operation: submitting a new list overwrites the previous one entirely rather than appending to it. Audit (GET /v2/preferred-regions) before updating to avoid accidentally removing an actively used region.\n\n**Key Fields**\n\ncountries (required) — array of ISO 3166-1 alpha-2 country codes in uppercase (e.g., [\"AU\", \"IN\", \"US\"]); maximum five entries; submit an empty array ([]) to clear all preferred regions\n\ntenant_id (response) — UUID of the tenant whose preferred regions were updated\n\ncountries (response) — the saved country code list\n\ncreated_by / updated_by — UUID of the user who created or last modified the list\n\ncreated_at / updated_at — timestamps of creation and last update\n\n**Common Use Cases**\n\nInitial setup of the preferred region list when onboarding iOS VPP management for a multi-country deployment\n\nAdding a new country to the allowed storefront pool when the organization expands to a new region\n\nRemoving stale regions from the list by resubmitting a trimmed country array\n\n**Best Practices**\n\nKeep the list to only the countries where you actively deploy VPP apps — the five-region cap is a hard limit\n\nBefore updating, call GET /v2/preferred-regions and check which regions are actively assigned to apps via GET /v2/itunesapps; removing a region that apps depend on will break their storefront assignments\n\nUse uppercase two-letter codes (e.g., \"US\", not \"us\") to match Apple's App Store country code format\n\n**Workflow**\n\nCall GET /v2/preferred-regions to retrieve the current list and confirm what, if anything, needs to change\n\nPOST to /v2/preferred-regions with the complete desired countries array (this replaces the existing list)\n\nAssign individual app storefronts from the updated pool using PUT /v2/itunesapps/{appleAppId}/preferred-region\n", "tags": [ "apps_management_Preferred Regions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_SetPreferredRegionsRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/apps_management_TenantPreferredRegions" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } }, "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "summary": "Get Preferred Regions for Tenant", "description": "⚠️ Apple devices only.\n\nRetrieves the tenant's current list of preferred App Store regions, returning an empty countries array if no regions have been configured. Use this endpoint to inspect the tenant's configured storefronts before assigning or updating per-app regions, and to verify that a desired country code is available before calling PUT /v2/itunesapps/{appleAppId}/preferred-region.\n\n**About Preferred Regions**\n\nThe preferred regions list defines the pool of up to five App Store storefronts a tenant can use when assigning regions to individual VPP apps. This read endpoint surfaces the current state of that list — including the country codes, the user who last modified it, and timestamps. An empty countries array indicates no preferred regions have been set, meaning per-app region assignments cannot be made until regions are configured via POST /v2/preferred-regions. In the Console, this configuration is visible in Apple MDM Management settings.\n\n**Key Fields**\n\ntenant_id (response) — UUID of the tenant\n\ncountries (response) — array of uppercase ISO 3166-1 alpha-2 country codes currently configured (e.g., [\"AU\", \"IN\", \"US\"]); empty array if none set\n\ncreated_by / updated_by — UUID of the user who created or last modified the list\n\ncreated_at / updated_at — timestamps of creation and last update\n\n**Common Use Cases**\n\nVerifying which App Store storefronts are currently available before assigning a region to a VPP app\n\nAuditing the tenant's region configuration as part of an iOS fleet compliance check\n\nChecking whether a preferred region list has been set up at all during initial iOS VPP onboarding\n\n**Best Practices**\n\nCall this endpoint before any PUT /v2/itunesapps/{appleAppId}/preferred-region operation to confirm the target country code is in the list\n\nInclude this in onboarding checklists: an empty countries response means VPP region assignments are not yet possible\n\nUse the updated_at timestamp to detect whether the list has changed since your last sync\n\n**Workflow**\n\nGET /v2/preferred-regions to retrieve the current country list\n\nConfirm the desired storefront country code is present before assigning it to a VPP app\n\nIf the list is empty or missing the needed country, configure it via POST /v2/preferred-regions first\n", "tags": [ "apps_management_Preferred Regions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/apps_management_TenantPreferredRegions" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } } }, "/v2/esper-apps/{appId}/versions/{versionId}": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "parameters": [ { "in": "path", "required": true, "name": "appId", "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "required": true, "name": "versionId", "schema": { "type": "string", "format": "uuid" } } ], "summary": "Get esper app version details by ID", "description": "Retrieves details for a specific version of an Esper App.\n\nGiven an app ID and version ID, returns the full EsperAppVersionResponse for that version — including its download URL, hashes, size, and platform metadata. \n\n**About Esper Apps**\n\nEsper Apps are Esper's own curated/system apps (as opposed to customer-uploaded tenant apps), spanning multiple platforms per the app_type field: TENANT_IOS, ESPER_IOS, ESPER_ANDROID, ESPER_LINUX, and ESPER_WINDOWS. Each app can have multiple versions, and this endpoint returns one specific version's detail.\n\n**Key Fields / Query Parameters**\n\n- appId — UUID of the Esper App (path)\n- versionId — UUID of the specific app version (path)\n- X-Caller-Id — required request header\n- app_type — platform/type of the app (TENANT_IOS, ESPER_IOS, ESPER_ANDROID, ESPER_LINUX, ESPER_WINDOWS)\n- signature_hash — SHA-256 fingerprint of the app's signing key, only present for Android apps\n\n**Common Use Cases**\n\n- Fetching download/version metadata for a specific Esper App version before deploying it\n- Verifying an app version's file hash or size prior to distribution\n", "tags": [ "apps_management_Esper Apps" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/apps_management_EsperAppVersionResponse" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } } }, "/v2/tenant-esper-apps": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "apps_management_apiKey": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "number" } }, { "in": "query", "name": "offset", "schema": { "type": "number" } }, { "in": "query", "name": "package_name", "schema": { "type": "string" } }, { "in": "query", "name": "ordering", "schema": { "type": "string", "enum": [ "created_at (ascending)", "-created_at (descending)", "version_code (ascending)", "-version_code (descending)" ] } }, { "in": "query", "name": "architecture", "schema": { "type": "string", "enum": [ "x86", "x86_64", "armeabi", "arm64_v8a", "armeabi_v7a", "universal" ] } }, { "in": "query", "name": "version_code", "schema": { "type": "string", "description": "Filter by version code" } } ], "summary": "Get esper apps for a tenant", "description": "Retrieves a paginated list of Esper-provided apps available to the tenant.\n\nReturns each app's TenantEsperAppsItem record, filterable by package name, version code, and architecture.\n\n**About Get Esper Apps**\n\nEsper Apps are apps published by Esper itself, rather than uploaded by the tenant, and made available for installation on managed devices, such as Windows-side utility or agent apps. This catalog is separate from Tenant Apps (tenant-uploaded iOS and Windows apps) and from Android's Application V1 catalog.\n\n**Key Fields / Query Parameters**\n\npackage_name — filters by package name\n\narchitecture — filters by CPU architecture, for example x86_64, arm64_v8a, or universal\n\nversion_code — filters by a specific version code\n\nordering — orders by created_at or version_code, ascending or descending\n\n**Common Use Cases**\n\nBrowsing available Esper-provided apps before assigning one to a device or blueprint\n\nFinding the correct architecture-specific build of an Esper app for a device\n\n**Best Practices**\n\nFilter by architecture to avoid selecting a build incompatible with the target device's hardware\n\n**Workflow**\n\nCall this endpoint with the filters relevant to the app you need\n\nIdentify the correct version_code and architecture for your target devices\n\nReference the app in a blueprint or command to install it\n", "tags": [ "apps_management_Tenant Esper Apps" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "count": { "type": "integer", "description": "number of results returned" }, "prev": { "type": "string", "description": "URL for previous page of results" }, "next": { "type": "string", "description": "URL for next page of results" }, "results": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/apps_management_TenantEsperAppsItem" } ] } } } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } } }, "/v2/oem-config-schema": { "get": { "x-badges": [ { "name": "Beta", "color": "yellow" } ], "security": [ { "apps_management_apiKey": [] } ], "summary": "Get OEM Config Schema", "description": "Retrieves the OEM config schema for a given OEM type and app package name. Use it to get the structure that describes which OEM-specific managed configuration keys an app supports and how they're formatted.\n\nBy default this returns the latest active schema; pass version_code to pin to a specific schema version, and set include_schema=false when you only need metadata and want to avoid downloading the (potentially large) schema_json payload.\n\n**About OEM Config Schema**\n\nOEM config schemas describe device-manufacturer-specific managed configuration options (separate from an app's standard managed configuration) so that OEM-provided settings can be surfaced and applied consistently through Esper. Schemas are versioned per OEM type and package name, with one version marked active at a time.\n\n**Key Fields / Query Parameters**\n\n- oem_type — the OEM/manufacturer identifier the schema applies to\n- package_name — the Android package name of the app the schema is for\n- version_code — optional, retrieves a specific schema version instead of the latest active one\n- include_schema — set to false to omit the schema_json payload and return metadata only\n\n**Common Use Cases**\n\n- Fetching the current OEM config schema before building a UI or payload for OEM-specific managed configuration\n- Checking metadata only (via include_schema=false) to confirm a schema exists or see its version without pulling the full payload\n\n**Best Practices**\n\n- Use include_schema=false when you only need to check schema existence or version, since schema_json payloads can be large\nRetrieve the OEM config schema for a given OEM type and package name.\nReturns the latest active schema by default. Specify `version_code` to retrieve a specific version.\nSet `include_schema=false` to receive metadata only (avoids the large `schema_json` payload).\n", "operationId": "getOEMConfigSchema", "tags": [ "apps_management_OEM Config Schema" ], "parameters": [ { "in": "header", "required": true, "name": "Authorization", "schema": { "type": "string" }, "description": "Bearer token for authentication" }, { "in": "query", "required": true, "name": "oem_type", "schema": { "type": "string", "enum": [ "ZEBRA", "HONEYWELL", "DATALOGIC", "SAMSUNG", "SUNMI" ] }, "description": "OEM manufacturer type", "example": "ZEBRA" }, { "in": "query", "required": true, "name": "package_name", "schema": { "type": "string" }, "description": "OEM config package name (e.g. com.zebra.oemconfig.common)", "example": "com.zebra.oemconfig.common" }, { "in": "query", "required": false, "name": "version_code", "schema": { "type": "string" }, "description": "Specific version code to retrieve. When omitted, returns the latest active schema.", "example": "10" }, { "in": "query", "required": false, "name": "include_schema", "schema": { "type": "boolean", "default": true }, "description": "Set to false to return metadata only, omitting the schema_json field (avoids large payload)" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "When version_code is specified: public, max-age=3600 (response is immutable for that version). When version_code is omitted (latest lookup): no-store (the current selection can change)." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "default": 200 }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/apps_management_OEMConfigSchema" } } } } } }, "400": { "description": "Bad Request — missing or invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found — no schema found for the given oem_type, package_name, and version_code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apps_management_Error_500_Internal_Server_Error" } } } } } } }, "/commands/v0/commands/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "List command requests", "description": "Returns a paginated list of command requests within the enterprise. Each record includes the command type, targeted devices or groups, schedule details, arguments, and current status. This endpoint provides visibility into commands that have been issued, whether they are queued, in progress, successful, or failed. Common use cases: Auditing commands sent across the enterprise Tracking scheduled vs immediate commands Reviewing historical command activity Troubleshooting command execution at scale Best Practices: Use pagination parameters to manage large datasets. Filter or search (if supported) to narrow results when investigating specific command IDs or timeframes. For device-level execution results, pair this endpoint with command status or event feed views.\n", "operationId": "listCommandRequests", "tags": [ "commands_Command Request" ], "parameters": [ { "in": "query", "name": "devices", "description": "Filter by device IDs. Accepts comma separated values.", "schema": { "type": "string" } }, { "in": "query", "name": "groups", "description": "Filter by group IDs. Accepts comma separated values.", "schema": { "type": "string" } }, { "in": "query", "name": "command", "description": "Filter by command name", "schema": { "type": "string" } }, { "in": "query", "name": "schedule", "description": "Filter by schedule type", "schema": { "type": "string", "enum": [ "IMMEDIATE", "WINDOW", "RECURRING" ] } }, { "in": "query", "name": "exclude_internal_commands", "description": "Filter to exclude internal commands", "schema": { "type": "boolean", "default": false } }, { "in": "query", "name": "limit", "schema": { "type": "number" } }, { "in": "query", "name": "offset", "schema": { "type": "number" } } ], "security": [ { "commands_apiKey": [] } ], "responses": { "200": { "description": "Command request list for the Tenant", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/commands_CommandRequest" } } } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commands_Error_401_Unauthorized" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commands_Error_500_Internal_Server_Error" } } } } } }, "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Create a command request", "description": "Issues a device or group-level command using the stable command API. This endpoint supports multi-OS environments and scheduling options, and should be used for all new command integrations. Common use cases: Installing or uninstalling apps, pushing certificates, modifying device settings, sending notifications, enforcing policies, and other device actions supported by Esper. Best Practices: Ensure the command is supported for the device’s OS before sending. Decide whether to target specific devices (DEVICE) or a device group (GROUP). Determine whether the command should run IMMEDIATE or use scheduling options (if supported by the command). Validate command_args carefully—payload structure differs by command. Understand the command lifecycle (queued → acknowledged → in progress → success/failure). Monitor execution and final state in the Event Feed after issuing the request. Important: Response bodies can vary depending on the command. For detailed examples and command-specific payload guidance, refer to the API Commands help documentation: https://help.esper.io/hc/en-us/articles/29710806069393-Creating-API-Commands\n\n\nYou can send the command immediately or [schedule command](https://help.esper.io/hc/en-us/articles/16693582666769-Scheduling-API-Commands) for supported devices.\n\n\nScheduled commands are currently compatible with Android devices.\n", "operationId": "createCommandRequest", "tags": [ "commands_Command Request" ], "security": [ { "commands_apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commands_CommandRequest_POST" } } } }, "responses": { "201": { "description": "Command request successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/commands_CommandRequest" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commands_Error_400_Bad_Data" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commands_Error_401_Unauthorized" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commands_Error_500_Internal_Server_Error" } } } } } } }, "/commands/v0/commands/{id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get a command request", "description": "Retrieves a single command request by its ID.\n\nReturns the full CommandRequest object, including the command type, its targeted devices or groups, the schedule used, and the arguments that were sent when the command was created.\n\n**About Get Command Request**\nA command request represents the original call made to POST /commands/v0/commands/; it captures what was asked for (the command, its targets, and its schedule), while the actual execution outcome per device is tracked separately by Command Status records. Use this endpoint to re-inspect exactly what was requested, for example when auditing or troubleshooting a command that didn't behave as expected.\n\n**Common Use Cases**\n\nReviewing the original arguments and targets of a command after it was issued\n\nConfirming whether a command was scheduled or issued immediately\n\n**Best Practices**\n\nPair this with GET /commands/v0/commands/{id}/stats/ to see the aggregate execution outcome alongside the original request details\n\nUse the id returned from POST /commands/v0/commands/ rather than a device-level command status id, since these are different identifiers\n\n**Workflow**\n\nCapture the id returned when the command request was created\n\nCall this endpoint to retrieve the full request detail\n\nCall the stats endpoint for the same id to see aggregate execution status\n", "operationId": "getCommandRequest", "tags": [ "commands_Command Request" ], "security": [ { "commands_apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the command request object", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Command request information", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/commands_CommandRequest" } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commands_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commands_Error_404_Not_Found" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commands_Error_500_Internal_Server_Error" } } } } } } }, "/commands/v0/commands/{id}/stats/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get stats of a command request", "description": "Retrieves an aggregated count of devices in each status for a given command request.\n\nInstead of listing every individual device status, this endpoint rolls the command's execution up into a count per state, for example how many devices are still queued versus how many succeeded or failed.\n\n**About Command Request Stats**\nWhen a command request targets many devices or a group, tracking each device's status individually can be unwieldy. This endpoint returns the CommandRequestStats object, an array of state and total pairs, giving a quick read on how a command is progressing across its full target set without paging through every device status record.\n\n**Common Use Cases**\n\nBuilding a progress summary for a command that was issued to a large group\n\nQuickly checking whether a command has finished executing across all targeted devices\n\nDetermining whether any devices have failed a command without listing them individually first\n\n**Best Practices**\n\nUse this endpoint for a high-level progress check, then fall back to GET /commands/v0/status/ with a request filter if you need the specific devices behind a given count\n\nPoll this endpoint rather than the full status list when you only need aggregate numbers, to reduce response size\n\n**Workflow**\n\nIssue the command with POST /commands/v0/commands/ and capture the returned id\n\nPoll this endpoint to track aggregate progress by state\n\nIf failures appear, filter GET /commands/v0/status/ by request and state to identify the specific devices\n", "operationId": "getCommandRequestStats", "tags": [ "commands_Command Request" ], "security": [ { "commands_apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the command request object", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Aggregrated status information for a command request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/commands_CommandRequestStats" } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commands_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commands_Error_404_Not_Found" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commands_Error_500_Internal_Server_Error" } } } } } } }, "/commands/v0/status/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get status list for command request", "description": "Retrieves a paginated, filterable list of individual command status records across the tenant.\n\nEach record represents one command's execution on one device, including its current state and the reason for that state. Filter by request, device, or state to narrow the list to the commands you're investigating.\n\n**About List Command Status**\nWhile a command request can target many devices at once, each device gets its own CommandStatus record tracking its individual progress through the command lifecycle, moving through Command Queued, Command Initiated, Command Acknowledged, Command In Progress, and a terminal state such as Command Success, Command Failure, Command TimeOut, or Command Cancelled. This endpoint is the primary way to see exactly which devices succeeded or failed within a given command request.\n\n**Key Fields / Query Parameters**\n\nrequest — filters by one or more command request IDs, accepts comma-separated values\n\ndevice — filters by one or more device IDs, accepts comma-separated values\n\nstate — filters by command state, for example Command Failure or Command Queued\n\nexclude_internal_commands — excludes internally generated commands from the results when set to true\n\n**Common Use Cases**\n\nListing every device that failed a specific command request\n\nChecking whether a specific device has picked up a command it was sent\n\nAuditing all command activity for a device over time by filtering on device alone\n\n**Best Practices**\n\nCombine request and state filters to jump straight to the failed devices within a large command request\n\nUse exclude_internal_commands to keep results focused on customer-issued commands when auditing\n\n**Workflow**\n\nIdentify the request id from the command request, or the device id you want to investigate\n\nCall this endpoint with the appropriate filters\n\nUse the returned command status id with GET /commands/v0/status/{id}/ for full detail on a specific record\n", "operationId": "getCommandRequestStatuses", "tags": [ "commands_Command Status" ], "security": [ { "commands_apiKey": [] } ], "parameters": [ { "in": "query", "name": "request", "description": "Filter status result by command request IDs. Accepts comma separated values.", "schema": { "type": "string" } }, { "in": "query", "name": "device", "description": "Filter status result by device IDs. Accepts comma separated values.", "schema": { "type": "string" } }, { "in": "query", "name": "state", "description": "Filter by command state", "schema": { "type": "string", "enum": [ "Command Queued", "Command Initiated", "Command Acknowledged", "Command In Progress", "Command TimeOut", "Command Success", "Command Failure", "Command Scheduled", "Command Cancelled" ] } }, { "in": "query", "name": "exclude_internal_commands", "description": "Filter to exclude internal commands", "schema": { "type": "boolean", "default": false } }, { "in": "query", "name": "limit", "schema": { "type": "number" } }, { "in": "query", "name": "offset", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Status list for a command request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/commands_CommandStatus" } } } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commands_Error_401_Unauthorized" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commands_Error_500_Internal_Server_Error" } } } } } } }, "/commands/v0/status/{id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get a command status", "description": "Retrieves a single command status record by its ID.\n\nReturns the full CommandStatus object for one device's execution of one command, including its current state, the associated device and request IDs, and the reason for its current state.\n\n**About Get Command Status**\nThis is the most granular status check available for a command's execution on a specific device. Use it once you already have a command status id, typically obtained by filtering GET /commands/v0/status/ down to the record you care about.\n\n**Common Use Cases**\n\nChecking the current state and reason for one device's execution of a command\n\nConfirming a command has reached a terminal state before considering it complete\n\n**Best Practices**\n\nUse the reason field to understand why a command failed rather than only checking state\n\nCache this result briefly rather than polling continuously if the state is already terminal\n\n**Workflow**\n\nFilter GET /commands/v0/status/ by device or request to find the specific command status id\n\nCall this endpoint with that id for the full record\n", "operationId": "getCommandStatus", "tags": [ "commands_Command Status" ], "security": [ { "commands_apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the command status object", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Command status information", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/commands_CommandStatus" } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commands_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commands_Error_404_Not_Found" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commands_Error_500_Internal_Server_Error" } } } } } }, "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Update command status", "description": "Updates the state of an individual command status record. Supports only CANCEL. Cancellations are not always guaranteed and depends on the command's exact state.\n\n**About Update Command Status**\n\nEach CommandStatus record tracks the execution of one command against one device and is created automatically when a command request targets that device. This endpoint lets you override the current lifecycle state directly rather than waiting for the device to report back. It's typically used by internal tooling and integrations that need to reconcile command state (such as cancelling a command stuck in Command Queued) rather than as part of a normal command-issuing workflow.\n\n**Key Fields / Request Body**\n\nstate — the new command state; accepts Command Cancelled\n\nreason — free text explaining why the state was changed\n\n**Common Use Cases**\n\nCancelling a command that is stuck in a queued state before it reaches the device\n\nForcing a command into a terminal state when a device is known to be offline or decommissioned\n\n\n**Best Practices**\n\nUse GET /commands/v0/status/{id}/ first to confirm the command's current state before changing it\n\nAlways include a reason so the change is auditable in the command history\n\nPrefer letting the device report its own status through the normal command lifecycle; only override manually when necessary\n\n**Workflow**\n\nCall GET /commands/v0/status/{id}/ to review the command's current state and device\n\nDetermine the correct terminal or intermediate state to apply\n\nPUT the new state and reason to this endpoint\n\nConfirm the update by re-fetching the command status record\n", "operationId": "updateCommandStatus", "tags": [ "commands_Command Status" ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the command status object", "required": true, "schema": { "type": "string" } } ], "security": [ { "commands_apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commands_CommandStatus_PUT" } } } }, "responses": { "200": { "description": "Command status successfully updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/commands_CommandStatus" } } } } } }, "304": { "description": "Command status was not modified because the requested state transition is not allowed." }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commands_Error_400_Bad_Data" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commands_Error_401_Unauthorized" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commands_Error_500_Internal_Server_Error" } } } } } } }, "/v2/command-inbox/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get queued commands to be executed by the physical device.", "description": "Retrieves the commands currently queued for a specific device to execute.\n\nThis is the device-facing endpoint the Esper agent itself calls to pick up its pending work; it returns commands in the Command Queued state for the given device_id, along with the command arguments and basic device metadata.\n\n**About Command Inbox**\n\nWhile GET /commands/v0/status/ gives an administrative view of command execution across the tenant, the command inbox is the device-side queue that the Esper agent polls to find out what it needs to run next. It is scoped to a single device_id and reflects only commands that have not yet been picked up.\n\n**Key Fields / Query Parameters**\n\ndevice_id — the device whose queued commands should be returned, required\n\n**Common Use Cases**\n\nVerifying that a command was actually queued for delivery to a specific device\n\nDiagnosing a device that isn't executing commands by checking whether they are reaching its inbox at all\n\n**Best Practices**\n\nIf a command doesn't appear here after being issued, check the device's connectivity and last-seen time before assuming the command failed to queue\n\nUse this alongside GET /commands/v0/status/{id}/ to distinguish between a command that never reached the device and one that reached it but failed to execute\n\n**Workflow**\n\nIssue a command targeting the device through POST /commands/v0/commands/\n\nCall this endpoint with the device_id to confirm the command is queued\n\nIf the command doesn't appear, check the device's last-seen status before retrying\n", "operationId": "getCommandInbox", "tags": [ "commands_Command Status" ], "parameters": [ { "in": "query", "name": "device_id", "description": "Filter status result by device IDs.", "required": true, "schema": { "type": "string" } } ], "security": [ { "commands_apiKey": [] } ], "responses": { "200": { "description": "List of Queued Command Status", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/commands_CommandInbox" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commands_Error_400_Bad_Data" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commands_Error_401_Unauthorized" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commands_Error_500_Internal_Server_Error" } } } } } } }, "/v2/converge": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "List converge action", "description": "Retrieves a paginated list of Converge actions issued in the tenant.\n\nEach record reflects a single device's Converge request, including which blueprint and version it targeted and its current aggregate status. Filter by device_ids to scope the list to specific devices.\n\n**About List Converge Actions**\n\nConverge is the mechanism that assigns a device to a blueprint and blueprint version and brings it into alignment with that configuration, covering apps, files, restrictions, and platform settings. Each Converge action moves through QUEUED, PROCESSING, IN_PROGRESS, and a terminal SUCCESS or FAILURE state as Esper applies the blueprint. This endpoint is the tenant-wide view of that activity, separate from the alpha Operations API, which handles Converge issued at fleet scale through POST /v0/operations/.\n\n**Key Fields / Query Parameters**\n\ndevice_ids — filters results to one or more device IDs, accepts comma-separated values\n\n**Common Use Cases**\n\nReviewing the Converge history for a specific device\n\nAuditing recent Converge activity across the tenant\n\n**Best Practices**\n\nFilter by device_ids when troubleshooting a specific device rather than paging through the full tenant-wide list\n\nFor large-scale Converge issued through the Operations API, use GET /v0/operations/ and its device-level endpoints instead of this list\n\n**Workflow**\n\nCall this endpoint with device_ids to scope to the devices you're investigating\n\nIdentify the converge id for the action you need\n\nCall GET /v2/converge/{id} for full detail, or /v2/converge/{id}/commands to see the underlying commands it fired\n", "operationId": "listConverges", "tags": [ "drift_Converge" ], "parameters": [ { "in": "query", "name": "device_ids", "description": "Filter by device IDs. Accepts comma separated values.", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "number" } }, { "in": "query", "name": "offset", "schema": { "type": "number" } } ], "security": [ { "drift_apiKey": [] } ], "responses": { "200": { "description": "Converge action list for the Tenant", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/drift_Converge" } } } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_Error_401_Unauthorized" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_Error_500_Internal_Server_Error" } } } } } }, "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Create a converge action", "description": "POST converge (V2). Assigns a device to a specific blueprint (and blueprint version) and triggers the converge workflow. Converge brings the device into alignment with the selected blueprint configuration, including apps, files, restrictions, and platform settings. What this endpoint does Assigns the device to the provided blueprint_id. Targets a specific blueprint_version_id. Queues a converge action (status: QUEUED) for execution. Optionally applies provisioning-related behavior via converge_with_provision_option. Workflow Use Get all blueprints (V2) to retrieve the desired blueprint_id and blueprint_version_id. Use a device listing endpoint to retrieve the device_id or group_id. Send a POST request to /api/v2/converge with the required identifiers. Monitor the converge/command status to confirm successful application.\n", "operationId": "createConverge", "tags": [ "drift_Converge" ], "security": [ { "drift_apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_Converge_POST" } } } }, "responses": { "201": { "description": "Converge action successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/drift_Converge" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_Error_400_Bad_Data" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_Error_401_Unauthorized" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_Error_500_Internal_Server_Error" } } } } } } }, "/v2/converge/{id}": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get converge action", "description": "Retrieves the full detail of a single Converge action by its ID.\n\nReturns the blueprint and version targeted, the device it applies to, its current status, and the reason for that status.\n\n**About Get Converge Action**\n\nThis is the detail view behind a single entry in the Converge list, useful for confirming exactly which blueprint_info a device was converged to and why a Converge action succeeded or failed. If a Converge action is marked FAILURE, check /v2/converge/{id}/commands to see which underlying command caused it.\n\n**Common Use Cases**\n\nConfirming which blueprint version a device was actually converged to\n\nInvestigating why a specific Converge action failed\n\n**Best Practices**\n\nCheck the reason field first when a Converge action shows FAILURE, then drill into its commands for the underlying cause\n\nCross-reference blueprint_info against the intended blueprint_version_id to catch cases where a device converged to an unexpected version\n\n**Workflow**\n\nObtain the converge id from the Converge list or from creating a new Converge action\n\nCall this endpoint to review its status and blueprint_info\n\nIf status is FAILURE, call /v2/converge/{id}/commands to see the commands fired and their outcomes\n", "operationId": "getConverge", "tags": [ "drift_Converge" ], "security": [ { "drift_apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the converge object", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Converge information", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/drift_Converge" } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_Error_404_Not_Found" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_Error_500_Internal_Server_Error" } } } } } } }, "/v2/converge/{id}/commands": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "List commands fires for converge action", "description": "Retrieves the underlying commands that were fired to carry out a specific Converge action.\n\nA single Converge action can result in multiple individual commands being dispatched to a device (for example, installing apps and applying settings); this endpoint lists each of those commands along with its own state.\n\n**About Converge Commands**\n\nConverge doesn't apply a blueprint to a device directly; it decomposes the blueprint's configuration into individual commands and dispatches them. This endpoint exposes that breakdown, which is the most direct way to identify exactly which underlying action caused a Converge action to fail.\n\n**Key Fields / Query Parameters**\n\ncommand_state — each result's current state, for example Command Failure or Command Success\n\n**Common Use Cases**\n\nIdentifying which specific command caused a Converge action to fail, for example a failed app install versus a failed settings change\n\nAuditing the full set of commands a Converge action generated\n\n**Best Practices**\n\nCheck each command's command_state and reason individually rather than relying on the Converge action's overall status alone, since one failed command among several is enough to fail the whole Converge action\n\nCross-reference command_request_id with GET /commands/v0/status/ if you need device-level command status detail beyond what's returned here\n\n**Workflow**\n\nIdentify a Converge action with a FAILURE status from the Converge list or detail endpoint\n\nCall this endpoint with that converge id\n\nReview each command's command_state to find the one that failed\n", "operationId": "listConvergeCommands", "tags": [ "drift_Converge Command" ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the converge object", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "number" } }, { "in": "query", "name": "offset", "schema": { "type": "number" } } ], "security": [ { "drift_apiKey": [] } ], "responses": { "200": { "description": "List of commands fired for converge action for the tenant", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/drift_ConvergeCommand" } } } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_Error_404_Not_Found" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_Error_500_Internal_Server_Error" } } } } } } }, "/v2/blueprint-drift/summary": { "get": { "summary": "Fetch Blueprint Drift summary counts for a tenant", "description": "Fetches Blueprint Drift summary counts for a tenant.\n\nReturns the number of devices grouped by their highest Blueprint Drift severity, giving a tenant-wide, at-a-glance view of fleet configuration compliance. Reponse varies by customer and feature availibility. Non-Architect customer where Blueprint Drift is not enabled returns an empty response. Architect customers where Blueprint Drift is not enabled due to not meeting the Esper Agent eligibility criteria returns a Version Mismatch response. Architect customers where Blueprint Drift is enabled returns the full Blueprint Drift response, including drift details.\n\n**About Blueprint Drift Summary**\nBlueprint Drift detects when a device's actual configuration diverges from the Blueprint it was assigned, using state reported via the device state-report ingestion endpoint. This summary endpoint aggregates that per-device drift status into fleet-wide severity counts.\n\n**Common Use Cases**\n- Powering a fleet-wide compliance dashboard showing how many devices have drifted from their Blueprint\n- Prioritizing remediation by severity across the fleet\n- Tracking drift trends over time by polling this summary periodically\n\n**Best Practices**\n- Use this summary for dashboard-level reporting, and drill into the status/per-device endpoints when investigating specific devices\n- Poll on a reasonable interval appropriate for a compliance dashboard rather than continuously\n- Pair with the per-device status endpoint to identify which specific devices need attention within a severity bucket\n\n**Workflow**\n1. GET this endpoint for the tenant-wide severity breakdown\n2. Use GET /v2/blueprint-drift/status to identify which devices fall into a severity bucket of interest\n3. Use GET /v2/blueprint-drift/{deviceId}/status for per-setting detail on a specific device\n", "operationId": "getBlueprintDriftSummary", "tags": [ "drift_Blueprint Drift" ], "security": [ { "drift_apiKey": [] } ], "responses": { "200": { "description": "Blueprint Drift summary counts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_BlueprintDriftSummaryResponse" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_Error_400_Bad_Data" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_Error_401_Unauthorized" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_Error_500_Internal_Server_Error" } } } } } } }, "/v2/blueprint-drift/status": { "get": { "summary": "Fetch Blueprint Drift status for devices", "description": "Fetches Blueprint Drift status for a set of devices.\n\nReturns each requested device's current Blueprint Drift state (compliant, drifted, or unknown) in a single call, given a list of device IDs. Reponse varies by customer and feature availibility. Non-Architect customer where Blueprint Drift is not enabled returns an empty response. Architect customers where Blueprint Drift is not enabled due to not meeting the Esper Agent eligibility criteria returns a Version Mismatch response. Architect customers where Blueprint Drift is enabled returns the full Blueprint Drift response, including drift details.\n\n**About Blueprint Drift Status**\nBlueprint Drift detects when a device's actual configuration diverges from its assigned Blueprint. This endpoint is the per-device counterpart to the fleet-wide summary, letting you check drift status for a specific set of devices at once.\n\n**Key Fields / Query Parameters**\n\n- `device_ids` — List of device UUIDs to check drift status for\n\n**Common Use Cases**\n- Checking drift status for a specific group of devices before or after a remediation effort\n- Confirming devices returned to compliant status after a config fix\n- Building a device-list view filtered or annotated by drift status\n\n**Best Practices**\n- Batch device_ids in a single call rather than checking devices one at a time\n- Treat unknown status as meaning insufficient state data has been reported yet, not necessarily non-compliant\n- Use the per-setting audit endpoint for any device showing drifted status to see exactly what differs\n\n**Workflow**\n1. Gather the device_ids to check\n2. GET this endpoint with those device_ids\n3. For any device showing drifted, call GET /v2/blueprint-drift/{deviceId}/status for per-setting detail\n", "operationId": "getBlueprintDriftStatus", "tags": [ "drift_Blueprint Drift" ], "security": [ { "drift_apiKey": [] } ], "parameters": [ { "in": "query", "name": "device_ids", "required": true, "schema": { "type": "string", "maxLength": 10000, "pattern": "^([0-9a-fA-F\\\\-]{36})(,([0-9a-fA-F\\\\-]{36}))*$" }, "description": "Comma-separated list of device UUIDs (max 100 ids). Devices not found return with state: unknown in the response.\n", "example": "550e8400-e29b-41d4-a716-446655440001,550e8400-e29b-41d4-a716-446655440002" } ], "responses": { "200": { "description": "Blueprint Drift status result set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_BlueprintDriftStatusResponse" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_Error_400_Bad_Data" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_Error_401_Unauthorized" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_Error_500_Internal_Server_Error" } } } } } } }, "/v2/blueprint-drift/{deviceId}/status": { "get": { "summary": "Fetch per-setting Blueprint Drift Audit for a device", "description": "Fetches a per-setting Blueprint Drift audit for a single device.\n\nReturns a row for every setting evaluated against the device's assigned Blueprint, so you can see exactly which individual settings have drifted rather than just an overall status. Reponse varies by customer and feature availibility. Non-Architect customer where Blueprint Drift is not enabled returns an empty response. Architect customers where Blueprint Drift is not enabled due to not meeting the Esper Agent eligibility criteria returns a Version Mismatch response. Architect customers where Blueprint Drift is enabled returns the full Blueprint Drift response, including drift details.\n\n**About Blueprint Drift Per-Setting Audit**\nBlueprint Drift detects when a device's actual configuration diverges from its assigned Blueprint. This endpoint provides the most granular view — a setting-by-setting comparison — used when the summary or batch status endpoints indicate a device has drifted and you need to know exactly what changed.\n\n**Key Fields / Query Parameters**\n- `deviceId` — UUID of the device to audit\n\n**Common Use Cases**\n- Diagnosing exactly which settings caused a device to be flagged as drifted\n- Verifying a specific setting was corrected after a remediation action\n- Providing detailed compliance evidence for a single device during an audit\n\n**Best Practices**\n- Use this endpoint only after the summary or batch status endpoints indicate the device is drifted, to avoid unnecessary per-setting calls at scale\n- Cross-reference drifted settings against the device's assigned Blueprint configuration to plan remediation\n- Re-check after remediation to confirm the specific settings returned to compliant\n\n**Workflow**\n1. Identify a drifted device via the summary or batch status endpoint\n2. GET this endpoint with the device's deviceId for the per-setting breakdown\n3. Remediate the drifted settings and re-check to confirm compliance\n", "operationId": "getDeviceBlueprintDriftSettings", "tags": [ "drift_Blueprint Drift" ], "security": [ { "drift_apiKey": [] } ], "parameters": [ { "in": "path", "name": "deviceId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Device identifier" } ], "responses": { "200": { "description": "Per-setting Blueprint Drift details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_BlueprintDriftDeviceSettingsResponse" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_Error_400_Bad_Data" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_Error_401_Unauthorized" } } } }, "404": { "description": "Device not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_Error_404_Not_Found" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/drift_Error_500_Internal_Server_Error" } } } } } } }, "/v2/seamless/upload": { "post": { "summary": "Create a ABM provisioning request by uploading file", "description": "⚠️ Apple devices only. \n\nCreates one or more ABM provisioning requests by uploading a CSV file containing device identifiers, assigning devices to a blueprint and optionally a group.\n\n**About Create ABM Provisioning Request (CSV Upload)**\n\nSeamless provisioning (also referred to as ABM provisioning in Esper) pre-assigns newly enrolled Apple Business Manager devices to a blueprint and group before they reach end users, enabling hands-free setup. This endpoint accepts a multipart/form-data CSV upload (csv_file) containing the device identifiers to provision. On success, it returns a paginated list of SeamlessRequest records — one per device in the file — each including the assigned blueprint, group, and identifier metadata. For provisioning a single device by serial number without a CSV, use POST /api/v2/seamless.\n\n**Key Fields**\n\ncsv_file (body, required) — Binary CSV file containing device identifiers, one device per row: unique_ids, unique_id_type, group_id, assigned_blueprint_id, and two optional columns, alias (5th) and tags (6th)\n\nid (response) — SeamlessRequest UUID\n\nassigned_blueprint_id (response) — Blueprint UUID assigned to the devices\n\ngroup_id (response) — Group UUID assigned to the devices (nullable)\n\nalias (response) — Alias assigned to the device from the CSV's optional 5th column (nullable); omitting or leaving this column blank never clears an existing device alias\n\ntags (response) — Tag names assigned to the device from the CSV's optional 6th column (nullable); a single cell may contain multiple comma-separated tag names (quote the cell if it contains a comma); a maximum of 5 tags per device is supported\n\nunique_ids (response) — The device identifiers from the CSV\n\nunique_id_type (response) — Integer type code identifying the identifier format used\n\ntenant_id (response) — Tenant UUID\n\n**Common Use Cases**\n\nBulk pre-assigning a shipment of Apple devices to a blueprint and deployment group before enrollment\n\nAutomating ABM provisioning for large device deployments using exported device lists\n\nSetting up hands-free enrollment workflows for iOS devices entering an ABM-managed fleet\n\n**Best Practices**\n\nValidate CSV formatting before upload — a 400 response indicates invalid file format or contents\n\nFor single-device provisioning or API-driven workflows without a file, use POST /api/v2/seamless with a JSON body instead\n\nCapture the returned SeamlessRequest records to confirm each device was registered with the correct blueprint and group assignments\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "device_onboarding_ABM Provisioning" ], "security": [ { "device_onboarding_apiKey": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "csv_file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "ABM provisioning request successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/device_onboarding_SeamlessRequest" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_onboarding_Error_400_Bad_Data" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_onboarding_Error_401_Unauthorized" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_onboarding_Error_500_Internal_Server_Error" } } } } } } }, "/v2/seamless": { "post": { "summary": "Create a ABM provisioning request using device serial number", "description": "⚠️ Apple devices only. \n\nCreates an ABM provisioning request for a single device using its serial number supplied in a JSON request body, pre-assigning it to a blueprint and optionally a group, alias, and tags.\n\n**About Create ABM Provisioning Request (Serial Number)**\n\nThis endpoint is the JSON-body alternative to the CSV upload path for seamless ABM provisioning. It accepts a SeamlessRequestBody containing the assigned_blueprint_id, an optional group_id, an optional alias, an optional tags array, and a seamless_info object with unique_ids (a single device identifier) and unique_id_type. This endpoint provisions exactly one device per request; for bulk provisioning of multiple devices, use POST /api/v2/seamless/upload. On success it returns a single SeamlessRequest record. This is the preferred method for programmatic or API-driven provisioning workflows where a device identifier is available at runtime rather than in a pre-prepared file.\n\n**Key Fields**\n\nassigned_blueprint_id (body, required) — UUID of the blueprint to assign to the device\n\ngroup_id (body, optional) — UUID of the group to assign the device to\n\nalias (body, optional) — Human-readable alias to assign to the device; omitting this field never clears an existing device alias\n\ntags (body, optional) — Array of tag names to assign to the device (maximum 5); tag names are resolved to (or created as) tags for the tenant asynchronously\n\nseamless_info.unique_ids (body) — A single device identifier (e.g., a serial number)\n\nseamless_info.unique_id_type (body) — Integer type code identifying the identifier format\n\nid (response) — SeamlessRequest UUID\n\nassigned_blueprint_id (response) — Confirmed blueprint assignment\n\ngroup_id (response) — Confirmed group assignment (nullable)\n\nalias (response) — Confirmed alias assignment (nullable)\n\ntags (response) — Confirmed tag names assignment (nullable)\n\n**Common Use Cases**\n\nProgrammatically pre-assigning a specific device to a blueprint as part of an automated provisioning pipeline\n\nRegistering a known device serial number for zero-touch enrollment without preparing a CSV file\n\nIntegrating ABM provisioning into a device lifecycle management workflow driven by an external system\n\n**Best Practices**\n\nEnsure assigned_blueprint_id references a published blueprint version — assigning an unpublished blueprint will result in a device that cannot complete hands-free enrollment\n\nThis endpoint accepts exactly one device identifier per request; a comma-separated or otherwise multi-value unique_ids is rejected with a 400 — use POST /api/v2/seamless/upload with a CSV to provision multiple devices in a single call\n\nFor large-scale bulk provisioning, POST /api/v2/seamless/upload with a CSV may be more practical\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "device_onboarding_ABM Provisioning" ], "security": [ { "device_onboarding_apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_onboarding_SeamlessRequestBody" } } } }, "responses": { "200": { "description": "Seamless request successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/device_onboarding_SeamlessRequest" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_onboarding_Error_400_Bad_Data" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_onboarding_Error_401_Unauthorized" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_onboarding_Error_500_Internal_Server_Error" } } } } } } }, "/onboarding/v0/depsyncs/": { "get": { "summary": "List all DEP sync requests for the tenant", "description": "⚠️ Apple devices only. DEP (Device Enrollment Program) is an Apple provisioning technology, now part of Apple Business Manager.\n\nRetrieves a paginated list of all DEP sync requests for the tenant, including each request's status and any device-level failure details.\n\n**About List DEP Sync Requests**\n\nApple's Device Enrollment Program (DEP), accessed through Apple Business Manager, assigns managed devices to an MDM server. A DEP sync request triggers Esper to pull the latest device assignments from Apple's DEP service, ensuring that newly enrolled or reassigned Apple devices are reflected in the tenant. Each DEPSyncRequestForGetResponse record includes the request's lifecycle status (QUEUED, INPROGRESS, COMPLETE, SUCCESS, or FAILURE), the user or service that created the request (created_by), and the timestamps for when the request was created and last updated. On failure, a failure_reason and a devices object may contain details about specific devices that failed to sync. Use POST /api/onboarding/v0/depsyncs/ to trigger a new sync, and GET /api/onboarding/v0/depsyncs/{id}/ to retrieve a specific request.\n\n**Key Response Fields**\n\nid — DEP sync request UUID\n\nstatus — QUEUED, INPROGRESS, COMPLETE, SUCCESS, or FAILURE\n\nfailure_reason — High-level reason for sync failure (present on FAILURE status)\n\ndevices.failure — Array of {serial, reason} objects for devices that failed to process\n\ncreated_by — User who triggered the sync\n\ncreated_at / updated_at — Timestamps\n\n**Common Use Cases**\n\nReviewing the history of DEP sync operations to confirm when devices were last successfully synced from Apple\n\nIdentifying which specific devices failed in a DEP sync and why\n\nAuditing DEP sync activity for compliance or onboarding reporting\n\n**Best Practices**\n\nOn FAILURE status, inspect both failure_reason for the overall cause and devices.failure for per-device detail — they may differ\n\nPaginate with limit and offset for tenants with a long sync history\n", "operationId": "listDEPSyncRequest", "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "device_onboarding_DEP Sync Request" ], "security": [ { "device_onboarding_apiKey": [] } ], "responses": { "200": { "description": "DEP sync request list for the Tenant", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/device_onboarding_DEPSyncRequestForGetResponse" } } } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_onboarding_Error_401_Unauthorized" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_onboarding_Error_500_Internal_Server_Error" } } } } } }, "post": { "summary": "Create a DEP sync request", "description": "⚠️ Apple devices only. DEP (Device Enrollment Program) is an Apple provisioning technology, now part of Apple Business Manager.\n\nTriggers a new DEP sync request, instructing Esper to pull the latest device assignments from Apple's DEP service for the tenant.\nAbout Create DEP Sync Request\nThis endpoint initiates a DEP sync — the process by which Esper fetches the current set of Apple-assigned devices from Apple Business Manager and updates the tenant's device enrollment records accordingly. The request body is an empty JSON object; no parameters are required. The sync runs asynchronously: the 200 response returns a DEPSyncRequest record with a QUEUED or initial status, and the sync progresses through INPROGRESS to COMPLETE, SUCCESS, or FAILURE. Poll GET /api/onboarding/v0/depsyncs/{id}/ to track progress, or use GET /api/onboarding/v0/depsyncs/ to review status across all sync requests.\n\n**Key Fields**\n\nRequest body — Empty JSON object ({})\n\nid (response) — UUID of the newly created DEP sync request\n\nstatus (response) — Initial status: QUEUED or INPROGRESS\n\ncreated_by / created_at — Audit fields\n\n**Common Use Cases**\n\nTriggering a DEP sync after adding new devices to Apple Business Manager to make them available in Esper\n\nForcing a refresh of device enrollment assignments following an ABM organizational change\n\nProgrammatically scheduling regular DEP syncs as part of a device onboarding pipeline\n\n**Best Practices**\n\nAvoid triggering DEP syncs in rapid succession — syncs run asynchronously and queuing multiple requests simultaneously is unlikely to produce faster results\n\nAfter triggering, poll GET /api/onboarding/v0/depsyncs/{id}/ using the returned id to track the sync to completion before taking dependent actions\n\nFor GET responses with full failure detail (including per-device failure reasons), use GET /api/onboarding/v0/depsyncs/{id}/ — the POST response uses the lighter DEPSyncRequest schema without device-level failure data\n\n**Workflow**\n\nTrigger the sync with an empty JSON POST body\n\nCapture the returned id\n\nPoll GET /api/onboarding/v0/depsyncs/{id}/ until status reaches SUCCESS, COMPLETE, or FAILURE\n", "operationId": "createDEPSyncRequest", "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "device_onboarding_DEP Sync Request" ], "security": [ { "device_onboarding_apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "DEP sync request successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/device_onboarding_DEPSyncRequest" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_onboarding_Error_400_Bad_Data" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_onboarding_Error_401_Unauthorized" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_onboarding_Error_500_Internal_Server_Error" } } } } } } }, "/onboarding/v0/depsyncs/{id}/": { "get": { "summary": "Get a DEP sync request", "description": "⚠️ Apple devices only. DEP (Device Enrollment Program) is an Apple provisioning technology, now part of Apple Business Manager.\n\nRetrieves the current status and full detail of a specific DEP sync request by its UUID, including per-device failure information if the sync encountered errors.\n\n**About Get DEP Sync Request**\nThis is the detail and polling endpoint for a single DEP sync request. It returns a DEPSyncRequestForGetResponse — the richer schema compared to the POST response — which includes the failure_reason field and the devices.failure array listing individual device serials and their specific failure reasons when the sync status is FAILURE. Use this endpoint to determine when a sync has completed and to diagnose any device-level issues that occurred during the sync. The status field progresses from QUEUED through INPROGRESS to a terminal state: COMPLETE, SUCCESS, or FAILURE.\n\n**Key Fields**\n\nid (path) — DEP sync request UUID (required)\n\nstatus — QUEUED, INPROGRESS, COMPLETE, SUCCESS, or FAILURE\n\nfailure_reason — Overall failure description (present when status is FAILURE)\n\ndevices.failure — Array of {serial, reason} objects for each device that failed to process (present when failure_reason is included)\n\ncreated_by — User who triggered the sync\n\ncreated_at / updated_at — Timestamps\n\n**Common Use Cases**\n\nPolling a DEP sync to completion after triggering it with POST /api/onboarding/v0/depsyncs/\n\nRetrieving per-device failure detail when a sync reaches FAILURE status\n\nConfirming the exact completion time of a sync for audit or pipeline sequencing purposes\n\n**Best Practices**\n\nPoll at a reasonable interval (e.g., every 30 seconds) — DEP syncs are Apple-dependent and duration varies with device count and Apple service response time\n\nWhen status is FAILURE, always check both failure_reason (overall) and devices.failure (per-device) — a sync may fail for an overall reason, for per-device reasons, or both\n\nUse updated_at as the authoritative timestamp for when the sync reached its terminal state\n", "operationId": "getDEPSyncRequest", "x-badges": [ { "name": "Stable", "color": "green" } ], "tags": [ "device_onboarding_DEP Sync Request" ], "security": [ { "device_onboarding_apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the DEP sync request object", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "DEP sync request information", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/device_onboarding_DEPSyncRequestForGetResponse" } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_onboarding_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_onboarding_Error_404_Not_Found" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device_onboarding_Error_500_Internal_Server_Error" } } } } } } }, "/tenant/v0/apnscertificates/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get all APNs certificate meta data for the Tenant", "description": "⚠️ iOS/iPadOS/tvOS only. APNs (Apple Push Notification service) certificates are required for Esper to communicate with and manage Apple devices.\n\nRetrieves a paginated list of APNs certificate records for the tenant, with optional filtering by state.\n\nReturns APNSCertInfo records containing each certificate's state, Apple ID, topic, creation timestamp, and expiry date. Default page size is 10.\n\n**About List APNs Certificates**\n\nAPNs certificates enable the Esper MDM server to send push notifications to iOS and iPadOS managed devices — without a valid certificate, device management commands cannot be delivered. Each APNSCertInfo record represents a certificate in one of two states: CSR_GENERATED (the CSR has been generated via POST /api/tenant/v0/apnscertificates/ but the signed certificate has not yet been uploaded) or COMPLETED (the signed certificate has been uploaded via PUT /api/tenant/v0/apnscertificates/{id}/ and is active). The meta.cert_expiry_on field is critical for proactive certificate renewal — APNs certificates expire annually and must be renewed before expiry to avoid loss of device management capability.\n\n**Response Fields**\n\nstate (query) — Filter by CSR_GENERATED or COMPLETED\n\nid — APNs certificate record UUID\n\napple_id — Apple ID associated with the certificate\n\nmeta.topic — APNs topic string for the certificate\n\nmeta.cert_created_at — Timestamp when the certificate was created at Apple\n\nmeta.cert_expiry_on — Certificate expiry datetime — monitor this for renewal\n\nstate — CSR_GENERATED or COMPLETED\n\n**Common Use Cases**\n\nAuditing all APNs certificates in the tenant and their expiry dates for renewal planning\n\nIdentifying certificates stuck in CSR_GENERATED state that have not been completed\n\nConfirming which Apple ID is associated with each active certificate\n\n**Best Practices**\n\nMonitor meta.cert_expiry_on proactively — APNs certificates expire annually and must be renewed before expiry to maintain uninterrupted iOS device management\n\nFilter by state=CSR_GENERATED to identify in-progress certificate setups that have not been completed\n\nRenewing an APNs certificate must use the same Apple ID as the original; verify apple_id before beginning renewal\n", "operationId": "listAPNsCerts", "tags": [ "tenant_APNs certificate" ], "security": [ { "tenant_apiKey": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 10 }, "description": "Number of records to return" }, { "in": "query", "name": "offset", "schema": { "type": "integer", "default": 0 }, "description": "Number of records to skip" }, { "in": "query", "name": "state", "schema": { "type": "string", "enum": [ "CSR_GENERATED", "COMPLETED" ] } } ], "responses": { "200": { "description": "APNs certificate meta data list for the Tenant", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/tenant_APNSCertInfo" } } } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_401_Unauthorized" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_500_Internal_Server_Error" } } } } } }, "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get the CSR file to upload to the apple identity console", "description": "⚠️ iOS/iPadOS/tvOS only. This is step 1 of the APNs certificate setup workflow.\n\nGenerates a CSR (Certificate Signing Request) file for the tenant's Esper server, returning it as a downloadable .plist binary for upload to Apple's identity portal.\n\n**About Generate APNs CSR**\n\nThis endpoint initiates the APNs certificate setup process. The request body is an empty JSON object; no parameters are required. The response is not JSON — it returns a binary application/x-plist file (the CSR) that must be downloaded and uploaded to Apple's Push Certificates Portal to obtain a signed APNs certificate. The signed certificate is then uploaded back to Esper via PUT /api/tenant/v0/apnscertificates/{id}/ to complete the setup. Calling this endpoint also creates a new APNSCertInfo record in CSR_GENERATED state, retrievable by the returned id. Each call generates a new CSR and a new certificate record — do not call this multiple times for the same setup.\n\n**Full APNs Certificate Workflow**\n\nStep 1: (This step) Esper API — POST /api/tenant/v0/apnscertificates/ → downloads the .plist CSR file\n\nStep 2: (Outside of the API workflow) Apple Portal (out-of-band) — log into Apple's Push Certificates Portal, upload the .plist CSR, and download the signed .pem certificate Apple returns\n\nStep 3: Esper API — PUT /api/tenant/v0/apnscertificates/{id}/ → upload the signed cert + Apple ID back to Esper\n\n**Key Fields**\n\nRequest body — Empty JSON object ({})\n\nResponse — Binary application/x-plist CSR file (download and save; do not attempt to parse as JSON)\n\nThe corresponding APNSCertInfo record (with id and state=CSR_GENERATED) is created and retrievable via GET /api/tenant/v0/apnscertificates/\n\n**Common Use Cases**\n\nStarting the APNs certificate setup process for a new tenant or after certificate expiry\n\nGenerating a new CSR as part of the annual APNs certificate renewal workflow\n\n**Best Practices**\n\nDo not call this endpoint multiple times for the same setup — each call creates a new record and CSR, which can result in orphaned CSR_GENERATED records\n\nUse the same Apple ID throughout the workflow — the Apple ID used at the Apple portal must match what is submitted in the PUT step\n\nTreat the response as a file download; store the .plist before proceeding to the Apple portal\n", "operationId": "getAPNsCSR", "tags": [ "tenant_APNs certificate" ], "security": [ { "tenant_apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Created", "content": { "application/x-plist": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_400_Bad_Data" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_401_Unauthorized" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_500_Internal_Server_Error" } } } } } } }, "/tenant/v0/apnscertificates/{id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get APNs certificate meta information", "description": "⚠️ iOS/iPadOS/tvOS only.\n\nRetrieves the metadata record for a specific APNs certificate by its UUID.Returns a single APNSCertInfo object with the certificate's state, associated Apple ID, APNs topic, creation and expiry timestamps, and audit fields.\n\n**About Get APNs Certificate**\n\nDirect lookup for a single APNs certificate record, returning the same APNSCertInfo schema as the list endpoint. Use this endpoint to check the state and expiry of a specific certificate when its id is already known — for example, after generating a CSR to confirm the record was created, or to check meta.cert_expiry_on for renewal planning. A state of CSR_GENERATED indicates the setup workflow has been started but the signed certificate has not yet been uploaded; COMPLETED means the certificate is active.\n\n**Key Fields**\n\nid (path) — APNs certificate record UUID (required)\n\nstate — CSR_GENERATED or COMPLETED\n\napple_id — Apple ID associated with the certificate\n\nmeta.topic — APNs topic string\n\nmeta.cert_expiry_on — Certificate expiry datetime\n\nmeta.cert_created_at — Certificate creation timestamp at Apple\n\n**Common Use Cases**\n\nConfirming a new APNs certificate record was created after calling the CSR generation endpoint\n\nChecking the expiry date of a specific active certificate for renewal scheduling\n\nVerifying the Apple ID and topic for a certificate before renewal\n\n**Best Practices**\n\nUse meta.cert_expiry_on to schedule renewal — APNs certificates expire annually and must be renewed before expiry to maintain iOS device management\n\nIf state is CSR_GENERATED and no PUT has been performed, the certificate setup is incomplete — proceed with uploading the signed certificate via PUT /api/tenant/v0/apnscertificates/{id}/\n", "operationId": "getAPNsCert", "tags": [ "tenant_APNs certificate" ], "security": [ { "tenant_apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the APNs certificate meta object", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "APNs certificate meta information", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/tenant_APNSCertInfo" } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_404_Not_Found" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_500_Internal_Server_Error" } } } } } }, "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Upload APNs certificate", "description": "⚠️ iOS/iPadOS/tvOS only. This is step 3 of the APNs certificate setup workflow.\n\nUploads the signed APNs certificate obtained from Apple's Push Certificates Portal to Esper, completing the APNs setup for the tenant.\n\n**About Upload APNs Certificate**\n\nThis endpoint completes the APNs certificate workflow by accepting the signed certificate file and the Apple ID used to sign it. The id path parameter refers to the APNSCertInfo record created when the CSR was generated via POST /api/tenant/v0/apnscertificates/. The request uses multipart/form-data with two required fields: file (the signed certificate binary) and apple_id (the Apple ID used at Apple's Push Certificates Portal). On success, the certificate record transitions from CSR_GENERATED to COMPLETED state and the tenant's iOS devices can receive push-delivered management commands. The apple_id submitted here must match the one used at Apple's portal — a mismatch will prevent successful activation.\n\n**Key Fields**\n\nid (path) — APNs certificate record UUID from the CSR generation step (required)\n\nfile (body, required) — Signed APNs certificate binary obtained from Apple's Push Certificates Portal\n\napple_id (body, required) — Apple ID used to sign the certificate at Apple's portal\n\n**Common Use Cases**\n\nCompleting initial APNs certificate setup after uploading the CSR to Apple and downloading the signed certificate\n\nRenewing an expiring APNs certificate by uploading the newly signed renewal certificate\n\n**Best Practices**\n\nEnsure apple_id exactly matches the Apple ID used at Apple's Push Certificates Portal — mismatches will prevent activation and cannot be corrected without regenerating the CSR\n\nFor annual renewal, use the same Apple ID as the original certificate — renewing with a different Apple ID creates a new certificate rather than renewing the existing one, which can disrupt existing device enrollments\n\nAfter upload, confirm the record's state has transitioned to COMPLETED using GET /api/tenant/v0/apnscertificates/{id}/ before relying on push delivery for device management\n\n**Workflow**\n\nGenerate CSR via POST /api/tenant/v0/apnscertificates/ → obtain id\n\nUpload CSR to Apple Push Certificates Portal with the intended Apple ID → download signed certificate\n\nPUT signed certificate + Apple ID to this endpoint using the id from step 1\n", "operationId": "uploadAPNsCert", "tags": [ "tenant_APNs certificate" ], "security": [ { "tenant_apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the APNs certificate meta object", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/tenant_APNSCert_PUT" } } } }, "responses": { "200": { "description": "Uploaded APNs certificate meta Information", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/tenant_APNSCertInfo" } } } } } }, "400": { "description": "APNs certificate update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_400_Bad_Data" } } } }, "401": { "description": "APNs certificate update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_404_Not_Found" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_500_Internal_Server_Error" } } } } } }, "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Delete a APNs certificate", "description": "⚠️ iOS/iPadOS/tvOS only.\n\nDeletes an APNs certificate record from the Esper tenant by its ID.\n\nOnce deleted, Esper can no longer send push notifications to iOS devices provisioned under that certificate; devices will lose MDM connectivity until a new certificate is uploaded and enrolled.\n\n**About Delete APNs Certificate**\n\nAPNs (Apple Push Notification service) certificates are required for all iOS MDM communication between Esper and Apple-managed devices. Deleting a certificate invalidates the Esper-side record; however, the corresponding certificate entry in the Apple Push Certificates Portal is unaffected and must be managed separately. This operation is irreversible — if you need to re-establish iOS MDM for the tenant, you must create a new APNs certificate from scratch. Only tenants with iOS provisioning enabled will have APNs certificate records.\n\n**Key Fields / Query Parameters**\n\nid (path, required) — The UUID of the APNs certificate meta object to delete, as returned by the list or create APNs certificate endpoints.\n**Common Use Cases**\n\nRemoving a certificate tied to a deprecated Apple ID or service account before replacing it with a new one\n\nCleaning up stale certificate records after migrating to a new Apple Push Certificates account\n\nDecommissioning iOS management for a tenant\n\n**Best Practices**\n\nEnsure all affected iOS devices have been unenrolled or migrated before deleting a certificate, as deletion immediately breaks MDM connectivity for those devices.\n\nUse a dedicated service account Apple ID for APNs certificates so that ownership is not tied to an individual who may leave the organization.\n\nBefore deleting, retrieve the certificate details via GET /api/tenant/v0/apnscertificates/{id}/ to confirm you have the correct record.\n\n**Workflow**\n\nList existing APNs certificates via GET /api/tenant/v0/apnscertificates/ to identify the correct certificate id.\n\nUnenroll or migrate all iOS devices relying on that certificate.\n\nSend DELETE /api/tenant/v0/apnscertificates/{id}/ to remove the certificate record from Esper.\n\nUpload and enroll a new APNs certificate if continued iOS MDM management is required.\n", "operationId": "deleteAPNsCert", "tags": [ "tenant_APNs certificate" ], "security": [ { "tenant_apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the APNs certificate meta object", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted APNs certificate", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object" } } } } } }, "401": { "description": "APNs certificate delete error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_404_Not_Found" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_500_Internal_Server_Error" } } } } } } }, "/tenant/v0/vpptokens/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "tenant_apiKey": [] } ], "summary": "Get all VPP tokens for the tenant", "description": "⚠️ iOS/iPadOS/tvOS only.\n\nReturns all Volume Purchase Program (VPP) tokens registered to the Esper tenant.\n\nUse this endpoint to audit which VPP tokens are currently on file, check their metadata and expiry status, and identify tokens that need renewal before they affect app distribution.\n\n**About List VPP Tokens**\n\nVPP tokens enable Esper to distribute paid and free apps from the Apple App Store to managed iOS devices on behalf of an Apple Business organization. Each token is associated with a specific location in Apple Business, and Esper recommends tying one token to one location to avoid app installation conflicts. Tokens expire annually and must be renewed before expiry to maintain uninterrupted app management. The response includes pagination fields (count, next, previous) and an array of VPPToken objects.\n\n**Key Fields / Query Parameters**\n\nid — UUID of the VPP token record in Esper.\n\nmeta — Object containing token metadata, including expiry information.\n\ncreated_at / updated_at — Timestamps for auditing when the token was uploaded or last modified.\n\n**Common Use Cases**\n\nRetrieving all VPP tokens to check expiry dates before the annual renewal window\n\nAuditing which Apple Business locations have active tokens registered in Esper\n\nVerifying a VPP token was successfully stored after upload\n\n**Best Practices**\n\nMonitor meta for expiry dates and renew tokens before they lapse; expired VPP tokens will block app installations and updates on enrolled iOS devices.\n\nAssociate each VPP token with a dedicated, Esper-specific Apple Business location to prevent conflicts with other MDM platforms.\n\nIf you manage multiple regions, use the VPP country selection feature in Apple MDM Management to configure up to five countries per token.\n", "tags": [ "tenant_VPP Token Management" ], "responses": { "200": { "description": "VPP tokens for the Tenant", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "default": 200 }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/tenant_VPPToken" } } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_401_Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_500_Internal_Server_Error" } } } } } }, "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "tenant_apiKey": [] } ], "summary": "Store a VPP token", "description": "⚠️ iOS/iPadOS/tvOS only.\n\nUploads a VPP token file to the Esper tenant to enable Apple App Store app distribution on managed iOS devices.\n\nSubmit the token as multipart/form-data; on success, Esper stores the token and returns the new VPPToken record with its assigned id for use in subsequent operations.\n\n**About Upload VPP Token**\n\nA VPP (Volume Purchase Program) token is a .vpptoken file downloaded from an Apple Business location's Apps & Books settings. Uploading it to Esper grants the tenant the ability to assign and install App Store apps on enrolled iOS devices without requiring individual Apple IDs on each device. Esper recommends creating a dedicated Apple Business location specifically for your Esper MDM integration before downloading and uploading the token. If migrating from another MDM platform, the existing VPP token should be migrated to avoid losing app licenses.\n\n**Key Fields / Query Parameters**\n\nfilename (form field, binary) — The .vpptoken file downloaded from Apple Business.\n\n**Common Use Cases**\n\nInitial setup of iOS app management after configuring Apple MDM Management in Esper\n\nMigrating a VPP token from a previous MDM platform to Esper\n\nAdding a second VPP token for a new Apple Business location or region\n\n**Best Practices**\n\nCreate and use a dedicated Apple Business location for Esper before downloading the VPP token to avoid conflicts with other MDM platforms sharing the same token.\n\nDownload the token from the correct MDM server entry in Apple Business (it will match the location name).\n\nAfter upload, verify the token was stored correctly via GET /api/tenant/v0/vpptokens/ before assigning apps to devices.\n\n**Workflow**\n\nIn Apple Business, create a location dedicated to Esper MDM and navigate to Settings > Payments & Billing > Apps & Books.\n\nSelect the linked Esper MDM server and download the .vpptoken file.\n\nPOST the file as multipart/form-data to /api/tenant/v0/vpptokens/.\n\nConfirm the returned VPPToken record and note the id for future reference.\n", "tags": [ "tenant_VPP Token Management" ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "default": 201 }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/tenant_VPPToken" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_401_Unauthorized" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_500_Internal_Server_Error" } } } } } } }, "/tenant/v0/vpptokens/{id}": { "delete": { "x-badges": [ { "name": "Stable", "color": "green" } ], "security": [ { "tenant_apiKey": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "required": true } ], "summary": "Delete VPP Token", "description": "⚠️ iOS/iPadOS/tvOS only.\n\nDeletes a VPP token from the Esper tenant by its ID.\n\nOnce deleted, Esper can no longer distribute or manage Apple App Store apps associated with that token's Apple Business location; previously installed apps remain on devices but cannot be updated or reassigned through Esper.\n\n**About Delete VPP Token**\n\nVPP tokens link Esper to a specific Apple Business location for app license management. Removing a token from Esper does not revoke app licenses in Apple Business, but it ends Esper's ability to manage those licenses going forward. This action is appropriate when retiring an Apple Business location, replacing a token with a renewed one, or decommissioning iOS app management entirely. Use the id returned from GET /api/tenant/v0/vpptokens/ or POST /api/tenant/v0/vpptokens/ to identify the correct token.\n\n**Key Fields / Query Parameters**\n\nid (path, required, integer) — The identifier of the VPP token record to delete.\n\n**Common Use Cases**\n\nRemoving an expired token before uploading a renewed one\n\nCleaning up a stale token from a retired Apple Business location\n\nDecommissioning iOS app management for the tenant\n\n**Best Practices**\n\nBefore deleting, verify that no active iOS devices are relying on app licenses managed through this token.\n\nUpload a replacement token via POST /api/tenant/v0/vpptokens/ immediately after deletion to minimize disruption to app management.\n\nConfirm the correct token using GET /api/tenant/v0/vpptokens/ before deleting, especially in tenants with multiple VPP tokens.\n", "tags": [ "tenant_VPP Token Management" ], "responses": { "204": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "response code", "default": 204 }, "message": { "type": "string", "description": "response message" }, "content": { "type": "object" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_401_Unauthorized" } } } }, "404": { "description": "Resource Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_404_Not_Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_500_Internal_Server_Error" } } } } } } }, "/tenant/v0/deptokens/": { "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Generate the public key file", "description": "⚠️ iOS/iPadOS/tvOS only.\n\nGenerates and downloads the Esper public key file (.pem) required to register an MDM server entry and create a DEP token in Apple Business Manager.\n\nThis is the first step in the DEP token setup workflow: the returned public key file must be uploaded to Apple Business Manager to generate the encrypted server token (.p7m) that is then uploaded back to Esper.\n\n**About Generate DEP Public Key**\n\nDevice Enrollment Program (DEP) tokens allow Esper to communicate with Apple Business Manager (ABM) to automatically enroll DEP-provisioned iOS devices. The process begins with generating an Esper public key, which ABM uses to encrypt the server token it returns. This key exchange is required by Apple as a security measure in the MDM server registration flow. The response is a plain-text PEM file delivered as an attachment (Esper_Public_Key.pem), not a JSON object. The resulting DEP token record is created in state CSR_GENERATED until the server token is uploaded via PUT /api/tenant/v0/deptokens/{id}/.Key Fields / Query Parameters\n\nRequest body is optional (DEP_Token_POST schema is an empty object).\nResponse is a text/plain PEM-formatted public key file with Content-Disposition: attachment; filename=\"Esper_Public_Key.pem\".\n\n**Common Use Cases**\n\nInitial DEP token setup for a new Esper tenant provisioning iOS devices through Apple Business\n\nRegenerating a public key when rotating DEP credentials\n\nStarting the renewal process for an expiring DEP token\n\n**Best Practices**\n\nUpload the public key to ABM promptly; do not share the file externally.\n\nAfter uploading to ABM and downloading the resulting server token, proceed to PUT /api/tenant/v0/deptokens/{id}/ to complete the registration — use GET /api/tenant/v0/deptokens/ to retrieve the id of the newly created CSR_GENERATED record.\n\nUse a consistent Apple Business account across all DEP token operations to avoid mismatch errors.\n\n**Workflow**\n\nCall POST /api/tenant/v0/deptokens/ to generate and download Esper_Public_Key.pem.\n\nIn Apple Business Manager, go to Devices > Management > Add device management service and upload the Esper public key.\n\nSave the MDM server entry, then download the resulting server token (.p7m) via the ellipsis menu.\n\nUpload the .p7m to Esper via PUT /api/tenant/v0/deptokens/{id}/ using the id of the CSR_GENERATED record.\n", "operationId": "DEPToken", "tags": [ "tenant_DEP Tokens" ], "security": [ { "tenant_apiKey": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_DEP_Token_POST" } } } }, "responses": { "200": { "description": "Public key generation for ABM", "headers": { "Content-Disposition": { "schema": { "type": "string", "example": "attachment; filename=\"Esper_Public_Key.pem\"" } } }, "content": { "text/plain; charset=utf-8": { "schema": { "type": "string", "properties": { "content": { "type": "string" } }, "example": "-----BEGIN PUBLIC KEY----- MIGeMA0GCSqGSIb3DQEBAQUAA4GMADCBiAKBgE7FsxhVgAauNzV2S+B2O2TVpcKc /aPylhD8Abq0/5swcu3XFseP/GVttTH7JzSLLKdpyculA/DWfc73OP+r4LeswbAc pyvI8uDVCexU7YsND00Vs/L1i9RZXpCBk0oNECjIKQ6ex7ccI6VzZaTH6DallGkY eUcBApaAiL5QILTlAgMBAAE= -----END PUBLIC KEY-----" } } } }, "400": { "description": "Public key generation error - Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_400_Bad_Data" } } } }, "401": { "description": "Public key generation error - Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_401_Unauthorized" } } } }, "500": { "description": "Public key generation error - Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_500_Internal_Server_Error" } } } } } }, "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get all DEP tokens", "description": "\n⚠️ iOS/iPadOS/tvOS only.\n\nReturns a paginated list of all DEP tokens registered to the Esper tenant, with optional filtering by token state.\n\nUse this endpoint to audit DEP token status across the tenant, identify tokens pending completion, and retrieve id values needed for upload or individual retrieval operations.\n\n**About List DEP Tokens**\n\nDEP tokens are credentials that authorize Esper to communicate with Apple Business Manager for automatic iOS device enrollment. Each token progresses through two states. CSR_GENERATED (the Esper public key has been generated but the ABM server token has not yet been uploaded) and COMPLETED (the full token exchange is done and the integration is active). A tenant may have multiple DEP tokens, each corresponding to a different ABM MDM server entry or Apple Business location.\n\n**Key Fields / Query Parameters**\n\nstate (query, optional) — Filter results by token state-- CSR_GENERATED or COMPLETED.\n\nid — UUID of the DEP token record; used in GET /api/tenant/v0/deptokens/{id}/ and PUT /api/tenant/v0/deptokens/{id}/.\n\ntoken_name — Human-readable label assigned to the token during upload.\n\nmeta.token_expiry_on — Expiry date of the DEP token; tokens expire annually and must be renewed.\n\n**Common Use Cases**\n\nAuditing all DEP tokens to identify any CSR_GENERATED records that represent incomplete setup flows\n\nMonitoring token expiry dates ahead of the annual renewal window\n\nRetrieving token id values to pass to the individual token endpoints\n\n**Best Practices**\n\nFilter by state=CSR_GENERATED periodically to surface abandoned token setup flows that were started but never completed.\n\nTrack meta.token_expiry_on across all tokens; expired DEP tokens prevent automatic enrollment of new iOS devices.\n\nUse the returned id values to fetch full details via GET /api/tenant/v0/deptokens/{id}/ before performing uploads or updates.\n", "operationId": "ListDEPTokens", "tags": [ "tenant_DEP Tokens" ], "security": [ { "tenant_apiKey": [] } ], "parameters": [ { "in": "query", "name": "state", "schema": { "type": "string", "enum": [ "CSR_GENERATED", "COMPLETED" ] } } ], "responses": { "200": { "description": "Lists all dep tokens for a tenant", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string" }, "prev": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/tenant_DEP_Token_GET" } } } } } } } } }, "401": { "description": "Get DEP tokens error - Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_401_Unauthorized" } } } }, "500": { "description": "Get DEP tokens error - Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_500_Internal_Server_Error" } } } } } } }, "/tenant/v0/deptokens/{id}/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get dep token by id", "description": "Retrieves the details of a single DEP token by its UUID.\n\nReturns metadata including the token name, current state, expiry date, and audit timestamps — useful for checking the status of a specific token before renewal or upload operations.\n\n**About Get DEP Token by ID**\n\nDEP tokens in Esper go through a two-step setup: public key generation (CSR_GENERATED) followed by ABM server token upload (COMPLETED). This endpoint lets you inspect a specific token's full record without fetching the entire list, which is especially useful in tenants with multiple active DEP tokens. The state field confirms whether the token exchange with Apple Business Manager is complete and the integration is ready for device enrollment.\n\n**Key Fields / Query Parameters**\n\nid (path, required, UUID) — The unique identifier of the DEP token record.\n\nstate — Current token state: CSR_GENERATED or COMPLETED.\n\ntoken_name — The label assigned to the token during upload.\n\nmeta.token_expiry_on — Token expiry date; critical for renewal planning.\n\ncreated_at / updated_at — Audit timestamps for when the token was created and last modified.\n\n**Common Use Cases**\n\nChecking whether a specific DEP token setup is complete before onboarding iOS devices\n\nRetrieving expiry information for a single token as part of a renewal workflow\n\nConfirming token state has transitioned to COMPLETED after uploading the ABM server token via PUT /api/tenant/v0/deptokens/{id}/\n\n**Best Practices**\n\nCall this endpoint after completing the ABM server token upload to confirm the state has transitioned to COMPLETED before attempting to enroll devices.\n\nUse meta.token_expiry_on to set renewal reminders well in advance — expired DEP tokens block automatic device enrollment.\n", "operationId": "DEPTokenBasedOnID", "parameters": [ { "name": "id", "in": "path", "description": "ID of the token object", "required": true, "schema": { "type": "string", "format": "UUID" } } ], "tags": [ "tenant_DEP Tokens" ], "security": [ { "tenant_apiKey": [] } ], "responses": { "200": { "description": "Get DEP token by id", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "schema": { "$ref": "#/components/schemas/tenant_DEP_Token_GET" } } } } } } } }, "401": { "description": "Get DEP token by id error - Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_404_Not_Found" } } } }, "500": { "description": "Get DEP token by id error - Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_500_Internal_Server_Error" } } } } } }, "put": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Upload dep token to a tenant", "description": "Uploads a DEP token for a tenant's Apple Business Manager public key.\n\nUploads the .p7m token file downloaded from Apple Business Manager (ABM), associating it with the tenant's existing DEP public key record identified by id.\n\n**About DEP Tokens**\nDEP (Apple's Device Enrollment Program, now part of Apple Business Manager) requires exchanging a public key with Apple and uploading the resulting signed token back to Esper to complete the DEP server token setup. This is a required step before DEP profiles can be used for zero-touch iOS enrollment.\n\n**Key Fields / Query Parameters**\n- `id` — ID of the DEP public key record this token corresponds to\n- `file` — The .p7m token file downloaded from the ABM console\n- `token_name` — Name to assign to this DEP token\n\n**Common Use Cases**\n- Completing initial DEP/ABM setup for zero-touch iOS device enrollment\n- Renewing an expiring DEP server token from Apple Business Manager\n- Re-establishing DEP connectivity after a token was revoked or rotated in ABM\n\n**Best Practices**\n- Download the .p7m file directly from the ABM console for the matching public key — tokens are not interchangeable across public key records\n- Track token expiration and renew proactively in ABM before it lapses, since DEP enrollment stops working once a token expires\n- Give tokens a clear token_name if the tenant manages more than one ABM connection\n\n**Workflow**\n1. Generate/download the DEP public key from Esper and upload it to Apple Business Manager\n2. Download the resulting .p7m token file from ABM\n3. PUT that file to this endpoint with the corresponding id and a token_name\n", "operationId": "DEPTokenUpload", "parameters": [ { "name": "id", "in": "path", "description": "ID of the token object", "required": true, "schema": { "type": "string", "format": "UUID" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": ".p7m file from abm console" }, "token_name": { "type": "string" } }, "required": [ "file", "token_name" ] } } } }, "tags": [ "tenant_DEP Tokens" ], "security": [ { "tenant_apiKey": [] } ], "responses": { "200": { "description": "Upload dep token for a public key by id", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "schema": { "$ref": "#/components/schemas/tenant_DEP_Token_GET" } } } } } } } }, "400": { "description": "Upload DEP token by id error - Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_400_Bad_Data" } } } }, "401": { "description": "Upload DEP token by id error - Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_404_Not_Found" } } } }, "500": { "description": "Upload DEP token by id error - Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_500_Internal_Server_Error" } } } } } } }, "/tenant/v0/depprofiles/": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get all DEP profiles for the tenant", "description": "Retrieves all DEP profiles configured for the tenant.\n\nReturns the tenant's Device Enrollment Program (DEP) profiles, which define the enrollment/setup experience for iOS devices enrolled via Apple Business Manager.\n\n**About DEP Profiles**\nA DEP profile controls what a user sees and can configure during initial setup of a DEP-enrolled iOS device — including which setup screens are shown and whether setup advances automatically. DEP profiles require a working DEP token connection to Apple Business Manager.\n\n**Common Use Cases**\n- Reviewing existing DEP profiles before assigning one to a batch of newly-ordered devices\n- Auditing the enrollment experience configured for different device cohorts\n- Finding a DEP profile to reuse for a new zero-touch iOS deployment\n\n**Best Practices**\n- Confirm the tenant's DEP token is valid before relying on DEP profiles for enrollment\n- Review show_setup_items and auto_advance_setup settings against the intended end-user experience\n- Create purpose-specific profiles (e.g., kiosk vs. BYOD-style setup) rather than reusing one profile for very different use cases\n\n**Workflow**\n1. GET this endpoint to review existing DEP profiles\n2. Create a new profile via POST if none of the existing ones fit\n3. Assign the desired profile to devices through Apple Business Manager / Esper's DEP enrollment flow\n", "operationId": "getDEPProfileList", "tags": [ "tenant_DEP Profile" ], "security": [ { "tenant_apiKey": [] } ], "responses": { "200": { "description": "DEP profile information for the Tenant", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/tenant_DEPProfile" } } } } } } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_401_Unauthorized" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_500_Internal_Server_Error" } } } } } }, "post": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Create a DEP profile", "description": "Creates a new DEP profile for the tenant.\n\nCreates a Device Enrollment Program profile controlling which setup screens are shown to the user during initial iOS device setup, and whether setup advances automatically.\n\n**About DEP Profiles**\nA DEP profile controls the out-of-box setup experience for iOS devices enrolled via Apple Business Manager. Different profiles can be created for different deployment scenarios (e.g., single-purpose kiosk devices versus general-use devices).\n\n**Key Fields / Query Parameters**\n- `show_setup_items` — List of setup items to show during device enrollment; if omitted or empty, all items are skipped\n- `auto_advance_setup` — Whether to automatically advance through setup screens; defaults to true if not specified, and only applies when applicable setup items are shown\n\n**Common Use Cases**\n- Creating a streamlined, hands-off setup profile for single-purpose kiosk devices\n- Defining a setup experience that shows specific configuration screens for general-use devices\n- Building distinct profiles for different device cohorts (e.g., retail vs. warehouse)\n\n**Best Practices**\n- Set show_setup_items deliberately — leaving it empty skips all setup screens, which is appropriate for kiosk-style zero-touch deployments but not general-use devices\n- Test a new profile on a single device before assigning it to a large DEP device order\n- Keep auto_advance_setup aligned with whether an unattended setup experience is desired\n\n**Workflow**\n1. Decide which setup screens (if any) end users should see\n2. POST the show_setup_items and auto_advance_setup configuration to this endpoint\n3. Assign the resulting profile to devices via Apple Business Manager / Esper's DEP enrollment flow\n", "operationId": "createDEPProfile", "tags": [ "tenant_DEP Profile" ], "security": [ { "tenant_apiKey": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_DEPProfileCreateRequest" } } } }, "responses": { "200": { "description": "Updated the DEP profile for the tenant", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "content": { "$ref": "#/components/schemas/tenant_DEPProfile" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_400_Bad_Data" } } } }, "401": { "description": "Authorization information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_401_Unauthorized" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_500_Internal_Server_Error" } } } } } } }, "/v2/emm/enrollment/begin/": { "post": { "description": "Generates a Google EMM sign-up URL to begin enterprise enrollment.\n\nStarts the Google EMM enrollment flow by generating a sign-up URL that the tenant admin visits to bind their organization to Google's Enterprise Mobility Management infrastructure; callback_url specifies where Google redirects after sign-up.\n\n**About Google EMM Enrollment**\nEnrolling in Google EMM is a prerequisite for managing GMS-enabled Android devices (silent app install, managed Play Store, managed configurations). This endpoint is the first step of that enrollment flow, generating the URL that begins the Google-hosted sign-up process.\n\n**Key Fields / Query Parameters**\n- `callback_url` — URL Google redirects to after the admin completes sign-up\n\n**Common Use Cases**\n- Kicking off Google EMM enrollment for a new tenant during onboarding\n- Building a custom onboarding UI that embeds Google's enrollment sign-up flow\n- Re-initiating enrollment if a previous attempt was abandoned before completion\n\n**Best Practices**\n- Ensure callback_url is reachable and correctly handles the completion_token/enterprise_token Google returns\n- Complete the flow promptly — sign-up URLs and tokens are typically time-limited\n- Store the resulting tokens securely, since they're required to complete enrollment\n\n**Workflow**\n1. POST a callback_url to this endpoint to receive the Google sign-up URL\n2. Direct the tenant admin to that URL to complete sign-up on Google's side\n3. Handle the redirect to callback_url and call POST /v2/emm/enrollment/complete/ with the returned tokens\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Generate sign-up URL", "tags": [ "tenant_Google Enterprise" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_BeginGoogleEMMEnrollmentRequest" } } } }, "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer token for authorization", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Successfully generated sign-up URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_BeginGoogleEMMEnrollmentResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_401_Unauthorized" } } } }, "409": { "description": "Conflict: Google Enterprise already exists and is enrolled to Google EMM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_409_Conflict" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_500_Internal_Server_Error" } } } } } } }, "/v2/emm/details/": { "get": { "description": "Returns the Google EMM enrollment status of the enterprise.\n\nReturns the current state of the tenant's Google Enterprise binding, including its google_enterprise_id and enrollment state.\n\n**About Google Enterprise Enrollment Status**\nThis endpoint reflects where a tenant is in the Google EMM enrollment lifecycle — from not yet enrolled, through the sign-up flow, to fully enrolled with an active google_enterprise_id.\n\n**Key Fields / Query Parameters**\n- `google_enterprise_id` — Google's identifier for the enrolled enterprise, once enrollment is complete\n- `state` — Current enrollment state\n\n**Common Use Cases**\n- Checking whether a tenant has completed Google EMM enrollment before enabling GMS device management features\n- Displaying enrollment status in a custom admin/onboarding UI\n- Troubleshooting why GMS-dependent features are unavailable for a tenant\n\n**Best Practices**\n- Check this before attempting any GMS-device operations that assume an active EMM binding\n- Use this to detect an incomplete enrollment and prompt the admin to finish the sign-up flow\n- Treat a missing or inactive state as a signal to restart enrollment via /v2/emm/enrollment/begin/\n\n**Workflow**\n1. GET this endpoint to check current enrollment state\n2. If not enrolled, begin the flow via POST /v2/emm/enrollment/begin/\n3. Once state indicates enrollment is complete, proceed with GMS device management features\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Return the enrollment status of the Enterprise", "tags": [ "tenant_Google Enterprise" ], "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer token for authorization", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved enrollment status", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/tenant_GoogleEnterpriseDetails" } } } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_401_Unauthorized" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_500_Internal_Server_Error" } } } } } }, "post": { "description": "Creates a new Google Enterprise record with the provided enrollment details.\n\nCreates the Google Enterprise binding record for the tenant, typically as part of completing or recording the outcome of the EMM enrollment flow.\n\n**About Google Enterprise Record**\nThis endpoint stores the Google-side enterprise binding details (tokens, state, callback/signup URLs) tying the tenant to its Google EMM enrollment. It's generally used internally by the enrollment flow rather than called directly once enrollment is already complete.\n\n**Key Fields / Query Parameters**\n- `google_enterprise_id` — Google's identifier for the enterprise\n- `state` — Enrollment state to record\n- `callback_url / signup_url` — URLs used during the enrollment flow\n- `completion_token / enterprise_token` — Tokens exchanged during enrollment\n\n**Common Use Cases**\n- Recording the outcome of a Google EMM enrollment flow\n- Re-establishing a Google Enterprise record after a data recovery scenario\n- Advanced/custom EMM onboarding tooling that manages enrollment state directly\n\n**Best Practices**\n- Prefer driving enrollment through /v2/emm/enrollment/begin/ and /complete/ rather than constructing this record manually, unless building custom onboarding tooling\n- Keep completion_token and enterprise_token secure — do not log them in plaintext\n- Confirm no existing record already exists for the tenant before creating a new one\n\n**Workflow**\n1. Complete the standard enrollment flow (begin → Google sign-up → complete) where possible\n2. Use this endpoint directly only for advanced scenarios needing manual record creation\n3. Verify the resulting state via GET /v2/emm/details/\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Creates a new Google Enterprise with the provided details", "tags": [ "tenant_Google Enterprise" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_GoogleEnterpriseDetails" } } } }, "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer token for authorization", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_GoogleEnterpriseDetails" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_401_Unauthorized" } } } }, "409": { "description": "Conflict: Google Enterprise already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_409_Conflict" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_500_Internal_Server_Error" } } } } } } }, "/v2/emm/web-token/": { "post": { "description": "Creates a Google Web Token for embedding the Console Google Play Store.\n\nGenerates a web token scoped to the tenant's Google Enterprise, used to render the Console Google Play Store UI at the specified parent_url.\n\n**About Google EMM Web Token**\nGoogle requires a short-lived web token to securely embed its managed Play Store UI (what Esper calls the Console Google Play Store) inside a parent web page. This endpoint generates that token for a given Google Enterprise binding.\n\n**Key Fields / Query Parameters**\n- `google_enterprise_id` — Required — ID of the Google enterprise the token is scoped to\n- `parent_url` — Required — must be a valid HTTPS URL; the page that will embed the Console Google Play Store using this token\n\n**Common Use Cases**\n- Embedding the Console Google Play Store inside a custom admin portal\n- Refreshing an expired web token to keep an embedded Play Store view working\n- Building a custom app-approval workflow that surfaces the managed Play Store UI\n\n**Best Practices**\n- Always use HTTPS for parent_url, since Google validates the scheme\n- Treat the returned token as short-lived — regenerate it rather than caching indefinitely\n- Confirm the google_enterprise_id corresponds to a fully enrolled Google Enterprise before requesting a token\n\n**Workflow**\n1. Confirm the tenant's Google EMM enrollment is complete (GET /v2/emm/details/)\n2. POST the google_enterprise_id and parent_url to this endpoint\n3. Use the returned token to render the Console Google Play Store iframe/embed at parent_url\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Create a Google Web Token", "tags": [ "tenant_Google Enterprise" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_CreateWebTokenRequest" } } } }, "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer token for authorization", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_CreateWebTokenResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_401_Unauthorized" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_500_Internal_Server_Error" } } } } } } }, "/v2/emm/enrollment/complete/": { "post": { "description": "Completes Google EMM enrollment for a Google Enterprise.\n\nFinalizes enrollment using the completion_token and enterprise_token returned by Google after the admin completed sign-up, activating the Google Enterprise binding for the tenant.\n\n**About Google EMM Enrollment**\nThis is the second and final step of the Google EMM enrollment flow, following POST /v2/emm/enrollment/begin/ and the admin completing sign-up on Google's hosted page.\n\n**Key Fields / Query Parameters**\n- `completion_token` — Token returned by Google after sign-up completion\n- `enterprise_token` — Token returned by Google identifying the enterprise binding\n\n**Common Use Cases**\n- Finalizing enrollment as the callback step after an admin completes Google's sign-up flow\n- Completing enrollment programmatically in a custom onboarding integration\n- Retrying completion if an earlier attempt failed transiently\n\n**Best Practices**\n- Call this promptly after receiving the tokens from Google's redirect, since they are typically time-limited\n- Handle failures by checking enrollment status (GET /v2/emm/details/) rather than assuming the tokens can be reused indefinitely\n- Do not log completion_token/enterprise_token in plaintext\n\n**Workflow**\n1. Receive completion_token and enterprise_token via the callback_url redirect from Google\n2. POST both tokens to this endpoint to finalize enrollment\n3. Confirm success via GET /v2/emm/details/\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Complete EMM enrollment for a Google Enterprise", "tags": [ "tenant_Google Enterprise" ], "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer token for authorization", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "completion_token": { "type": "string" }, "enterprise_token": { "type": "string" } }, "required": [ "completion_token", "enterprise_token" ] } } } }, "responses": { "200": { "description": "Successfully completed EMM enrollment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_GoogleEnterpriseDetails" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_401_Unauthorized" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_404_Not_Found" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_500_Internal_Server_Error" } } } } } } }, "/v2/emm/accounts/": { "get": { "description": "Returns the Google Service Account associated with the enterprise.\n\nReturns the Google Service Account record used for server-to-server authentication with Google's EMM APIs on behalf of the tenant.\n\n**About Google Service Account**\nSome Google EMM operations require server-to-server authentication via a Google Service Account rather than a user-facing OAuth flow. This endpoint exposes the service account record Esper has stored for the tenant's Google Enterprise.\n\n**Common Use Cases**\n- Confirming a Google Service Account is configured before relying on server-to-server EMM operations\n- Auditing which service account is currently active for a tenant\n- Troubleshooting EMM automation failures that may stem from a missing or inactive service account\n\n**Best Practices**\n- Check is_active status when troubleshooting EMM automation issues\n- Treat the service account's data/public_data fields as sensitive credential material\n- Create a new service account via POST if none exists or the current one needs to be rotated\n\n**Workflow**\n1. GET this endpoint to check for an existing, active service account\n2. If none exists or it needs rotation, POST to create a new one\n3. Confirm the new account is active before relying on it for automation\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Return the Google Service Account of the Enterprise", "tags": [ "tenant_Google Enterprise" ], "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer token for authorization", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved Google Service Account", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "count": { "type": "integer" }, "previous": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/tenant_GoogleServiceAccountDetails" } } } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_401_Unauthorized" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_500_Internal_Server_Error" } } } } } }, "post": { "description": "Creates a new Google Service Account with the provided details.\n\nCreates and stores a Google Service Account record for the tenant's Google Enterprise, used for server-to-server authentication with Google's EMM APIs.\n\n**About Google Service Account**\nSome Google EMM operations require server-to-server authentication via a Google Service Account. This endpoint registers that account's credential material with Esper so it can be used for those operations going forward.\n\n**Key Fields / Query Parameters**\n- `google_enterprise_id` — ID of the Google enterprise this service account belongs to\n- `key_id` — Identifier for the service account key\n- `data` — Service account credential data\n- `is_active` — Whether this service account should be treated as active\n\n**Common Use Cases**\n- Setting up server-to-server EMM authentication for a newly enrolled Google Enterprise\n- Rotating a service account's credentials by creating a replacement record\n- Recovering EMM automation after a previous service account was revoked\n\n**Best Practices**\n- Treat the data and public_data fields as sensitive credential material — avoid logging them\n- Deactivate or remove old service account records when rotating credentials, to avoid ambiguity about which is active\n- Confirm the new account works (via a test EMM API call) before decommissioning an older one\n\n**Workflow**\n1. Obtain the new service account credentials from Google\n2. POST them to this endpoint to register the account with Esper\n3. Confirm the account is active via GET /v2/emm/accounts/ and test EMM automation\n", "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Creates a new Google Service Account with the provided details", "tags": [ "tenant_Google Enterprise" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_GoogleServiceAccountDetails" } } } }, "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer token for authorization", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_GoogleServiceAccountDetails" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_401_Unauthorized" } } } }, "409": { "description": "Conflict: Google Service Account already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_409_Conflict" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_500_Internal_Server_Error" } } } } } } }, "/v2/mdmserviceconfig": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get MDM service configuration", "description": "Returns Esper's MDM service configuration for Apple device discovery.\n\nThis is an unauthenticated discovery endpoint implemented per Apple's MDMServiceConfig specification; it returns the URL a device uses to begin Automated Device Enrollment (ADE).\n\n**About MDM Service Config**\n\nApple devices use this well-known, unauthenticated endpoint during Automated Device Enrollment to discover which MDM server (Esper, in this case) to enroll with, per Apple's published device management service spec. Because it's a discovery step that happens before a device has any credentials, it intentionally requires no authentication.\n\n**Common Use Cases**\n\n- Supporting Apple's Automated Device Enrollment (ADE) flow so devices can discover Esper's MDM enrollment URL\n- Verifying Esper's MDM discovery response matches Apple's expected MDMServiceConfig format during ADE setup or troubleshooting\nUnauthenticated discovery endpoint per Apple's [MDMServiceConfig](https://developer.apple.com/documentation/devicemanagement/providing-information-about-your-device-management-service) spec.\nReturns the URL a device uses to begin Automated Device Enrollment.\n", "operationId": "getMDMServiceConfig", "tags": [ "tenant_MDM Service Config" ], "responses": { "200": { "description": "MDM service configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "dep_enrollment_url": { "type": "string" }, "dep_anchor_certs_url": { "type": "string" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_400_Bad_Data" } } } } } } }, "/v2/mdmserviceconfig/anchor-certs": { "get": { "x-badges": [ { "name": "Stable", "color": "green" } ], "summary": "Get DEP anchor certificates", "description": "Returns the anchor certificates Esper's MDM service configuration points to for DEP (Device Enrollment Program) enrollment. This is an unauthenticated endpoint, referenced by the dep_anchor_certs_url value in MDM service config — it is not meant to be called directly for day-to-day integration work.\n\n**About MDM Service Config**\n\nMDM service config supplies the URLs and metadata Apple's DEP enrollment flow needs to trust and reach Esper's MDM service, including this anchor-certs URL. Esper currently uses a trusted, publicly-signed SSL certificate rather than a custom anchor certificate, so this endpoint always returns an empty body — there is no custom anchor cert to retrieve yet.\n\n**Common Use Cases**\n\n- Resolved automatically as part of the DEP enrollment/MDM service config handshake, rather than called directly by integrators.\nUnauthenticated endpoint referenced by dep_anchor_certs_url. We use a\ntrusted SSL certificate and don't support custom anchor certs yet, so\nthis always returns an empty body.\n", "operationId": "getDepAnchorCerts", "tags": [ "tenant_MDM Service Config" ], "responses": { "200": { "description": "Empty body (no custom anchor certificates configured)" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenant_Error_400_Bad_Data" } } } } } } }, "/v1/foundry/builds/": { "get": { "summary": "Get Foundry builds", "description": "Returns a deduplicated list of all Esper Foundation OS version strings currently present across enrolled devices in the tenant.\n\nUse this endpoint to inventory which Foundation OS versions are deployed across your fleet — useful for identifying version spread, spotting devices running outdated builds, and scoping update operations.\n\n**About Get All Distinct Foundation Versions**\n\nEsper Foundation is a customized Android-based operating system for x86 and ARM devices, providing long-term support, regular security patches, and broad hardware compatibility. Foundation version strings follow the format [Android version].[Major Foundation version].[Minor Foundation version].[Build version] — for example, 7.10.21.02 indicates Android 7, Major Foundation version 10, Minor version 21, build 02. This endpoint returns each distinct version once regardless of how many devices share it, giving a fleet-wide view of OS version distribution. It requires the read:foundationversions scope.\n\n**Key Fields / Query Parameters**\n\nsearch — Partial string match (case-insensitive) to filter returned version strings\n\nlimit — Number of results per page; defaults to 10\n\noffset — Starting index for pagination\n\nfoundation_version — The version string returned per result, in [Android].[Major].[Minor].[Build] format\n\n**Common Use Cases**\n\nAuditing Foundation OS version spread across a fleet before planning an update campaign\n\nIdentifying whether devices running builds below a minimum supported version are present in the tenant\n\nCross-referencing deployed versions against the latest approved builds visible in Esper Software Updates for Foundation\n\n**Best Practices**\n\nUse search to quickly check whether a specific Foundation version is present rather than paginating the full list\n\nCombine results with device list endpoints filtered by Foundation version to enumerate specific devices on a given OS version\n\nCall this before scheduling OTA operations to establish a version distribution baseline\n\n**Workflow**\n\nCall GET /api/v2/foundationversions to retrieve all distinct Foundation OS versions present in the tenant\n\nCompare results against the latest approved build in Esper Software Updates for Foundation to identify outdated versions\n\nUse device list endpoints filtered by Foundation version to target devices on older builds for update via Pipeline, auto-update, or API-based FOTA\n", "security": [ { "foundation_AuthToken": [] } ], "operationId": "getFoundryBuilds", "tags": [ "foundation_FoundryBuilds" ], "parameters": [ { "in": "query", "name": "foundation_major_number", "description": "Filter by Esper Foundation Major Number, Foundation Numbers are integers starting at 1.", "schema": { "type": "string" } }, { "in": "query", "name": "build_arch", "description": "Filter by build architecture name, build architectures {arm, arm64, x86_64, x86}", "schema": { "type": "string" } }, { "in": "query", "name": "android_major_version", "description": "Filter by Android Major Version, Android Major Versions are integers starting at 1 and going to Current Android Release", "schema": { "type": "integer" } }, { "in": "query", "name": "device_model_id", "description": "Device model id", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "approved", "description": "Filter builds which have been approved for OTA update", "schema": { "type": "boolean" } }, { "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "type": "integer" } }, { "in": "query", "name": "ordering", "schema": { "type": "string" } }, { "in": "query", "name": "locked", "description": "Filter the locked builds. To be used with build_fingerprint_hash and device_model_id", "schema": { "type": "boolean" } }, { "in": "query", "name": "build_fingerprint_hash", "description": "hash of the build fingerprint of the existing build", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of Foundry builds", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "returned response code" }, "content": { "properties": { "count": { "type": "integer", "description": "counter of number of builds retrieved" }, "next": { "type": "string", "format": "url", "description": "url of the next ten builds" }, "previous": { "type": "string", "format": "url", "description": "url of the previous ten builds" }, "results": { "items": { "$ref": "#/components/schemas/foundation_Build_V1" } } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/foundation_Error_401_Unauthorized" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/foundation_Error_500_Internal_Server_Error" } } } } } } }, "/v1/foundry/builds/{build_id}/": { "get": { "summary": "Get Foundry Build", "description": "Returns a paginated list of Foundation OS builds registered in the Foundry system, with filters for architecture, Android version, device model, approval status, and more.\n\nUse this endpoint to browse available Foundation builds for a specific device model — for example, to find all approved builds before initiating a Pipeline deployment or configuring auto-update.\n\n**About Get Foundry Builds**\n\nFoundry is Esper's build management backend for Foundation OS. Each Foundry build represents a compiled OS image tied to a specific device model, CPU architecture, and Foundation version. Builds go through a lifecycle — released, to_be_deprecated, or unavailable — and must be explicitly approved before they can be used for OTA deployment or auto-update. The Console surfaces these builds in the Esper Software Updates > Esper Foundation tab; this endpoint provides the same catalog programmatically.\n\n**Key Fields / Query Parameters**\n\nfoundation_major_number — Filter by Foundation major version number (integer starting at 1)\n\nbuild_arch — Filter by CPU architecture: arm, arm64, x86, or x86_64\n\nandroid_major_version — Filter by Android major version (integer)\n\ndevice_model_id — Filter builds for a specific device model (UUID)\n\napproved — When true, returns only builds approved for OTA deployment\n\nlocked — Filter for builds currently locked to a device model; use with build_fingerprint_hash and device_model_id\n\nbuild_fingerprint_hash — Hash of an existing build's fingerprint, used to identify a currently installed build\n\nbuild_state — Lifecycle status: released, to_be_deprecated, or unavailable\n\n**Common Use Cases**\n\nListing all approved Foundation builds for a device model before scheduling a Pipeline deployment or enabling auto-update\n\nAuditing available builds by architecture and Android version across supported hardware\n\nIdentifying builds approaching deprecation (to_be_deprecated) to plan timely update campaigns\n\n**Best Practices**\n\nAlways filter by approved=true when looking for builds eligible for deployment — unapproved builds cannot be used for OTA or auto-update\n\nFilter by device_model_id to scope results to your target hardware, since builds are model-specific\n\nMonitor build_state values and proactively migrate devices off to_be_deprecated builds before they become unavailable\n\nWorkflow\n\nCall GET /v1/foundry/builds/ with device_model_id and approved=true to list eligible builds for your target hardware\n\nReview build_arch, foundation_major_number, and android_major_version to identify the desired build\n\nUse the returned build_id to approve the build (PUT /v1/foundry/builds/{build_id}/) or lock it for auto-update (PUT /v1/foundry/device-models/{device_model_id}/)\n", "security": [ { "foundation_AuthToken": [] } ], "tags": [ "foundation_FoundryBuilds" ], "parameters": [ { "name": "build_id", "in": "path", "description": "A build UUID specifying the Foundry Build", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Specified Foundry build", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/foundation_Build_V1" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/foundation_Error_401_Unauthorized" } } } }, "404": { "description": "Build not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/foundation_Error_404_Not_Found" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/foundation_Error_500_Internal_Server_Error" } } } } } }, "put": { "summary": "Update Foundry build", "description": "Retrieves full details for a single Foundation OS build by its unique Foundry build ID.\n\nUse this endpoint to inspect a specific build's metadata — including its architecture, Foundation version numbers, Android SDK level, approval status, and lifecycle state — before approving it or locking it to a device model for auto-update.\n\n**About Get Foundry Build**\n\nFoundry builds are the individual compiled OS images that make up the Foundation update catalog. Each build is identified by a UUID (build_id) and carries detailed metadata about the OS it contains: Foundation major/minor/build version numbers, Android version, CPU architecture, build hash, and whether it has been approved for OTA deployment. This endpoint returns the full Build_V1 object for a single build, providing the complete picture needed for approval or deployment decisions.\n\nKey Fields / Query Parameters\n\nbuild_id (path, required) — UUID of the Foundry build to retrieve\n\nfoundation_major_number / foundation_minor_number / foundation_build_number — Foundation version components of the build\n\nandroid_major_version / android_sdk_level — Android version metadata\n\nbuild_arch — CPU architecture (arm, arm64, x86, x86_64)\n\napproved — Whether the build has been approved for OTA deployment\n\nbuild_state — Lifecycle status: released, to_be_deprecated, or unavailable\n\ndeprecated_on — Date the build was or will be deprecated\n\nrelease_notes — JSON-formatted release notes for the build\n\n**Common Use Cases**\n\nConfirming a build's approval status and lifecycle state before using its build_id in a device model auto-update configuration\n\nReviewing release notes and version metadata for a specific build ahead of a planned deployment\n\nRetrieving build details to display in internal tooling or audit records\n\n**Best Practices**\n\nAlways check approved and build_state before proceeding with deployment — only approved: true builds in released state are safe to deploy\n\nStore the build_fingerprint_hash if you need to identify this build later via the list endpoint's locked filter\n\nReview deprecated_on to understand the support window remaining for this build\n\n**Workflow**\n\nObtain a build_id from GET /v1/foundry/builds/ filtered by device model and architecture\n\nCall GET /v1/foundry/builds/{build_id}/ to confirm approval status, version details, and release notes\n\nProceed to PUT /v1/foundry/builds/{build_id}/ to approve the build, or PUT /v1/foundry/device-models/{device_model_id}/ to lock it for auto-update\n", "security": [ { "foundation_AuthToken": [] } ], "operationId": "updateFoundryBuild", "tags": [ "foundation_FoundryBuilds" ], "parameters": [ { "name": "build_id", "in": "path", "description": "A build UUID specifying the Foundry Build", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/foundation_Foundry_Build_PUT_Request_V1" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/foundation_Build_V1" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/foundation_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/foundation_Error_401_Unauthorized" } } } }, "404": { "description": "Builds not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/foundation_Error_404_Not_Found" } } } } } } }, "/v1/foundry/device-models/": { "get": { "summary": "Get device models", "description": "Returns a list of Foundation-eligible device models registered to the tenant in the Foundry system, with optional filters for manufacturer, model, profile, and Android API level compatibility.\n\nUse this endpoint to enumerate the device models in your tenant's Foundation catalog and retrieve the device_model_id values needed to manage builds and auto-update configuration.\n\n**About Get Device Models**\n\nIn Foundry, a device model record represents a hardware profile eligible to run Foundation OS. Each model is associated with a profile name and variant, a manufacturer and model identifier, and configuration that governs how Foundation builds are deployed to it — including whether auto-update is enabled and which build is currently locked for OTA. Device model IDs are required parameters for filtering builds (GET /v1/foundry/builds/) and for configuring auto-update behavior (PUT /v1/foundry/device-models/{device_model_id}/).\n\n**Key Fields / Query Parameters**\n\nmanufacturer — Filter by device manufacturer name\n\nmodel — Filter by device model name\n\nprofile_name — Filter by Foundation build profile name\n\nprofile_variant — Filter by profile variant identifier\n\nupdate_compatible_android_api_level_begin — Filter models compatible with updates from this Android API level\n\nupdate_compatible_android_api_level_end — Filter models compatible with updates up to this Android API level\n\ndevice_model_id — UUID returned per result; used as a path parameter in build and auto-update endpoints\n\nauto_update — Indicates whether auto-update is currently enabled for the model\n\nlocked_build_id — The build_id currently locked for auto-update on this model (nullable)\n\nlatest — Whether the model is configured to auto-update to the latest approved build\n\n**Common Use Cases**\n\nRetrieving device_model_id values to use when filtering builds or configuring auto-update for specific hardware\n\nAuditing which device models have auto-update enabled and which build each is locked to\n\nFiltering models by manufacturer or Android API level compatibility when planning a Foundation rollout across mixed hardware\n\n**Best Practices**\n\nUse manufacturer and model filters to quickly locate the target device model rather than paginating through the full list\n\nCross-reference locked_build_id with GET /v1/foundry/builds/{build_id}/ to confirm the currently pinned build's approval status and version details\n\nCheck auto_update status on all managed models before approving a new build — enabled models will begin rolling out the update to devices within 24 hours of approval\n\n**Workflow**\n\nCall GET /v1/foundry/device-models/ with manufacturer and model filters to locate your target hardware\n\nNote the device_model_id for use in subsequent build filtering and auto-update configuration calls\n\nReview auto_update, latest, and locked_build_id to understand the current update configuration for each model\n", "security": [ { "foundation_AuthToken": [] } ], "tags": [ "foundation_FoundryDeviceModels" ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "string" } }, { "in": "query", "name": "offset", "schema": { "type": "string" } }, { "in": "query", "name": "manufacturer", "schema": { "type": "string" } }, { "in": "query", "name": "model", "schema": { "type": "string" } }, { "in": "query", "name": "profile_name", "schema": { "type": "string" } }, { "in": "query", "name": "profile_variant", "schema": { "type": "string" } }, { "in": "query", "name": "update_compatible_android_api_level_begin", "schema": { "type": "string" } }, { "in": "query", "name": "update_compatible_android_api_level_end", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of DeviceModels associated with the TenantId coming from the header", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "returned response code" }, "content": { "properties": { "count": { "type": "integer", "description": "counter of number of device models retrieved" }, "next": { "type": "string", "format": "url", "description": "url of the next ten device models" }, "previous": { "type": "string", "format": "url", "description": "url of the previous ten device models" }, "results": { "items": { "$ref": "#/components/schemas/foundation_Device_Model_V1" } } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/foundation_Error_401_Unauthorized" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/foundation_Error_500_Internal_Server_Error" } } } } } } }, "/v1/foundry/device-models/{device_model_id}/": { "put": { "summary": "Update Tenant Device Model", "description": "Configures the auto-update behavior for a Foundation device model — enabling or disabling automatic OS updates and optionally locking updates to a specific approved build or to the latest approved build.\n\nUse this endpoint to control how and when a device model receives Foundation OS updates over the air, as the programmatic equivalent of the auto-update toggle and version selector in Esper Software Updates for Foundation.\n\n**About Update Tenant Device Model**\n\nOnce a Foundation build is approved, auto-update must be separately enabled on the device model before devices begin receiving it. This endpoint manages that configuration. Setting auto_update: true enables OTA delivery; latest: true instructs Foundry to automatically track the newest approved build as it becomes available; locked_build_id pins updates to a specific build UUID. Note that latest and locked_build_id are only processed when auto_update is true. Once auto-update is active, enrolled devices on older builds will receive the update over a rolling 24-hour window — devices not currently communicating with Esper will update when they reconnect.\n\n**Key Fields / Query Parameters**\n\ndevice_model_id (path, required) — UUID of the device model to update\n\nauto_update (body) — true to enable automatic OTA updates for this device model; false to disable\n\nlatest (body) — When true, Foundry automatically locks to the newest approved build whenever one becomes available; processed only when auto_update is true\n\nlocked_build_id (body) — UUID of the specific approved build to lock for auto-update; processed only when auto_update is true\n\n**Common Use Cases**\n\nEnabling auto-update after approving a new Foundation build so enrolled devices begin receiving it within the 24-hour rollout window\n\nPinning a device model to a specific build version (locked_build_id) to control the exact OS version deployed across that hardware\n\nDisabling auto-update (auto_update: false) to pause OTA rollouts while investigating a reported issue with a new build\n\n**Best Practices**\n\nApprove the target build via PUT /v1/foundry/builds/{build_id}/ before enabling auto-update — auto-update only delivers approved builds\n\nUse locked_build_id rather than latest in production environments where you want explicit control over which version is deployed; reserve latest for test or canary device models\n\nEnsure devices are configured to accept system updates (via blueprint System Updates policy) before enabling auto-update here — both the device policy and the Foundry model config must align for updates to apply\n\n**Workflow**\n\nApprove the target build using PUT /v1/foundry/builds/{build_id}/ with approve: true\n\nCall PUT /v1/foundry/device-models/{device_model_id}/ with auto_update: true and either locked_build_id (specific version) or latest: true (track newest approved)\n\nMonitor the Foundation Event Feed (GET /v1/foundry/events/) to confirm the configuration change was recorded and track rollout progress\n", "security": [ { "foundation_AuthToken": [] } ], "tags": [ "foundation_FoundryDeviceModels" ], "parameters": [ { "name": "device_model_id", "in": "path", "description": "An UUID specifying the Device Model", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/foundation_Device_Model_PUT_Request_V1" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/foundation_Build_V1" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/foundation_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/foundation_Error_401_Unauthorized" } } } }, "403": { "description": "locked_build_id not approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/foundation_Error_403_Forbidden" } } } }, "404": { "description": "DeviceModel not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/foundation_Error_404_Not_Found" } } } } } } }, "/v1/foundry/events/": { "get": { "summary": "Get Foundry events", "description": "Returns a paginated list of Foundry events in reverse chronological order, providing an audit trail of Foundation build approvals, auto-update configuration changes, and related actions.\n\nUse this endpoint to programmatically access the Foundation Event Feed — the same activity log visible in the Esper Software Updates > Foundation Event Feed tab — for monitoring, compliance reporting, or automated alerting on Foundation update activity.\n\n**About Get Foundry Events**\n\nThe Foundation Event Feed records significant actions taken within the Foundry system, including build approvals and unapprovals, auto-update \nconfiguration changes, and other state transitions. Each event captures the actor (user or system), the affected resource, the event type and message, and any remarks provided at the time of the action. This log is essential for change management auditing — especially in regulated environments where OS update approvals require traceability. Events are returned in reverse chronological order (most recent first).\n\n**Key Fields / Query Parameters**\n\nlimit — Number of events to return per page\n\noffset — Starting index for pagination\n\nactor — Object identifying the user or system that triggered the event (includes id and name)\n\nevent_type — Classification of the event (e.g., build approval, auto-update change)\n\nevent_message — Human-readable description of what occurred\n\nresource — Object identifying the affected resource (id and type, e.g., a specific build or device model)\n\nmeta.user_remarks — Any comment provided by the actor at the time of the action (e.g., approval rationale from PUT /v1/foundry/builds/{build_id}/)\n\nmeta.change_type — The type of change recorded\n\ncreated_timestamp — Unix timestamp of when the event occurred\n\n**Common Use Cases**\n\nAuditing the history of build approvals and auto-update configuration changes for compliance or change management records\n\nMonitoring for unexpected approval or configuration changes as part of a security or operations workflow\n\nCorrelating Foundation update events with device behavior observed in device telemetry or command history\n\nBest Practices\n\nPaginate with limit and offset to retrieve a bounded window of recent events rather than loading the full history in a single call\n\nPersist events to an external log store if long-term retention is required — Foundry does not guarantee indefinite event history\n\nWhen using PUT /v1/foundry/builds/{build_id}/ or PUT /v1/foundry/device-models/{device_model_id}/, always supply user_remarks — these notes appear in this event feed and significantly improve audit trail quality\n\n**Workflow**\n\nCall GET /v1/foundry/events/ to retrieve recent Foundation activity, paginating as needed\n\nFilter results client-side by event_type or resource.id to isolate events related to a specific build or device model\n\nCross-reference meta.user_remarks and actor fields with internal change management records for compliance verification\n", "security": [ { "foundation_AuthToken": [] } ], "tags": [ "foundation_FoundryEvents" ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of Foundry events in reverse chronological order", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "properties": { "count": { "type": "integer", "description": "counter of number of events retrieved" }, "next": { "type": "string", "format": "url", "description": "url of the next ten events" }, "previous": { "type": "string", "format": "url", "description": "url of the previous ten events" }, "results": { "items": { "$ref": "#/components/schemas/foundation_Foundry_Event_V1" } } } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/foundation_Error_400_Bad_Data" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/foundation_Error_401_Unauthorized" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/foundation_Error_500_Internal_Server_Error" } } } } } } }, "/report/v0/report-types": { "get": { "tags": [ "reports_Reports API" ], "summary": "Get report types", "description": "Retrieve the list of report types available in the tenant.\n\nReturns each report type's internal name, display name, description, the last time it was generated, and the earliest date from which data is available (available_from).\n\n**About Get Report Types**\n\nEsper's Reports system provides pre-built fleet-level snapshots across devices and apps. Before generating a report, use this endpoint to discover which report types are available (device_apps, device, etc.) and to check when each type was last generated and how far back its data reaches. This is the recommended first step in any automated reporting workflow. Report availibility varies by operating system. \n\n**Key Fields**\n\nname — The internal identifier used in the report_type field when creating a report (e.g., device_apps, device)\n\ndisplay_name — The human-readable label shown in the console\n\nlast_generated_at — Timestamp of the most recently completed report of this type\n\navailable_from — The earliest date for which data exists for this report type\n\n**Common Use Cases**\n\nDiscovering available report types before building an automated reporting pipeline\n\nChecking whether a given report type has been generated recently enough to meet data freshness requirements\n\nValidating the name value to use in the report_type field of a Create Report request\n\n**Best Practices**\n\nCall this endpoint at the start of a reporting workflow to confirm the correct report_type value before posting a report request\n\nUse last_generated_at to assess data freshness; reports reflect ingested data and may lag up to 24 hours behind live device state\n\nUse available_from to validate that your desired date range falls within the supported window before submitting a report\n\n**Workflow**\n\nCall GET /report/v0/report-types to retrieve available types and their metadata\n\nNote the name value for the desired report type (e.g., device_apps or device)\n\nPass that name as report_type in a POST /report/v0/reports request\n", "operationId": "getReportTypes", "security": [ { "reports_bearerAuth": [] } ], "responses": { "200": { "description": "Report types", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reports_GetReportTypesResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reports_ReportsErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reports_ReportsErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reports_ReportsErrorResponse" } } } } } } }, "/report/v0/reports": { "post": { "tags": [ "reports_Reports API" ], "summary": "Create Report", "description": "Initiate generation of a device or device apps report and receive a report ID for status polling. Report availability varies by operating system.\n\nReturns a report_id and an initial status of PENDING; poll GET /report/v0/reports/{report_id} to track progress and retrieve results once the status reaches SUCCEEDED.\n\n**About Create Report**\n\nReport generation in Esper is asynchronous. Submitting this request triggers a backend job that ingests and consolidates fleet data — a process that can take several minutes. The is_download flag controls the output mode: set it to false to retrieve an in-memory preview (up to 10,000 rows) or true to generate a full dataset available via a signed download link. Supported report types are device_apps (Android and iOS/iPadOS/tvOS) and device (Android, iOS, Linux, Windows). Note that app reports exclude sideloaded, preloaded, and SDK-installed apps.\n\n**Key Fields / Request Body**\n\nreport_type (required) — device_apps for the Device Apps Report or device for the Device Report\n\nstart_time — Report window start in UTC (e.g., 2024-08-28T00:00:00Z); must be after July 1, 2024 for device_apps\n\nend_time — Must equal start_time (single-day reports only)\n\nis_download — true to generate a full downloadable CSV; false for an in-console preview (first 10,000 rows)\n\nfilters.date — Optional date override in YYYY-MM-DD format; takes precedence over start_time/end_time if provided\n\nfilters.package_name — (device_apps only) Array of package names to filter by; omit for all packages\n\nfilters.app_state — (device_apps only) Filter by app visibility: SHOW, HIDE, DISABLE, or LAUNCHABLE_BUT_HIDDEN\n\nfilters.platform — Filter by platform: Android, Apple, Linux, Windows (platform availability varies by report type)\n\n**Common Use Cases**\n\nGenerating a point-in-time snapshot of all app versions across an Android or iOS fleet\n\nProducing a full CSV export of device state, OS version, location, and provisioning data for all managed platforms\n\nFiltering a device apps report to a specific package name to audit version consistency across devices\n\n**Best Practices**\n\nSet end_time equal to start_time; the API supports single-day reports only\n\nUse filters.date as a simpler alternative to start_time/end_time when generating a same-day report\n\nSet is_download: true when your fleet exceeds 10,000 devices or apps, since the preview response is capped at 10,000 rows\n\nPoll GET /report/v0/reports/{report_id} at a reasonable interval (e.g., every 10–30 seconds) rather than immediately, as report generation can take several minutes\n\n**Workflow**\n\nCall GET /report/v0/report-types to confirm the report_type value and check data availability\n\nPOST to /report/v0/reports with the desired report_type, date range, is_download flag, and any filters\n\nStore the returned report_id and poll GET /report/v0/reports/{report_id} until status is SUCCEEDED or FAILED\n", "operationId": "createReportStatus", "security": [ { "reports_bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reports_Report" } } } }, "responses": { "200": { "description": "Create Report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reports_CreateReportResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reports_ReportsErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reports_ReportsErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reports_ReportsErrorResponse" } } } } } } }, "/report/v0/reports/{report_id}": { "get": { "tags": [ "reports_Reports API" ], "summary": "Get report status", "description": "Poll the status of a report and retrieve its results once generation is complete.\n\nReturns the current status of the report job (PENDING, RUNNING, SUCCEEDED, FAILED, CANCELED, or CLOSED) and, on success, either an inline data preview or a signed external download link depending on the is_download flag set when the report was created.\n\n**About Get Report Status**\n\nThis endpoint is the second half of Esper's two-step asynchronous report pattern. After POST /report/v0/reports returns a report_id, poll this endpoint until status reaches a terminal state. When is_download was false, the successful response includes a data_array of up to 10,000 rows along with a schema object describing column names, positions, and types. When is_download was true, the response instead includes an external_link — a signed URL pointing to the full dataset as a downloadable CSV.\n\n**Key Fields**\n\nreport_id (path, required) — UUID returned by POST /report/v0/reports\n\nstatus — Current job state: PENDING (queued), RUNNING (processing), SUCCEEDED (results available), FAILED, CANCELED, or CLOSED\n\nschema.columns — Array of column metadata objects, each with name, position, type_name, and type_text\n\ndata_array — (preview mode only) 2D array of row data, capped at 10,000 rows\n\nexternal_link — (download mode only) Signed URL to the full CSV export\n\n**Common Use Cases**\n\nPolling report status after initiating generation via POST /report/v0/reports\n\nRetrieving inline row data for small to mid-sized fleets (preview mode, ≤10,000 rows)\n\nObtaining a signed download URL for full fleet exports that exceed the 10,000-row preview cap\n\n**Best Practices**\n\nPoll at a reasonable interval (e.g., every 10–30 seconds) rather than immediately after creating the report, as generation can take several minutes\n\nCheck for terminal statuses (SUCCEEDED, FAILED, CANCELED, CLOSED) and stop polling once reached\n\nIf status is FAILED, re-submit the report via POST /report/v0/reports rather than retrying the same report_id\n\nFor download-mode reports, retrieve the external_link promptly as signed URLs may expire\n\n**Workflow**\n\nReceive the report_id from POST /report/v0/reports\n\nPoll this endpoint at intervals until status is SUCCEEDED (or a failure terminal state)\n\nIf preview mode: read data_array for results and schema for column structure; if download mode: fetch the CSV from external_link\n", "operationId": "getReportStatus", "parameters": [ { "$ref": "#/components/parameters/reports_ReportID" } ], "security": [ { "reports_bearerAuth": [] } ], "responses": { "200": { "description": "Report status", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/reports_CreateReportResponse" }, { "$ref": "#/components/schemas/reports_GetReportResponsePreview" }, { "$ref": "#/components/schemas/reports_GetReportResponseDownload" } ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reports_ReportsErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reports_ReportsErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reports_ReportsErrorResponse" } } } } } } }, "/geofence/v1/geofences": { "post": { "summary": "Create a new geofence", "description": "Creates a new geofence for the tenant, defined by its geographic boundary and the device actions to trigger when a device crosses it.\n\nSubmit the geofence's geometry (location and radius) along with the desired device actions; on success, returns the created geofence instance.\n\n**About Geofences**\n\nA geofence is a virtual geographic boundary that triggers device actions — such as locking down or sounding an alert — when a managed device enters or leaves the defined area. Geofences can also be associated with blueprints so that location determines which configuration is applied to a device.\n\n**Key Fields / Query Parameters**\n\n- geometry (location and radius) — defines the physical boundary of the geofence\n- device actions — the actions (e.g., lock down, beep) applied to devices crossing the boundary\n\n**Common Use Cases**\n\n- Setting up a new location-based restriction, such as locking down devices that leave a warehouse or job site\n- Defining a boundary that later gets tied to blueprint-based configuration changes\n", "operationId": "geofence_createGeofence", "tags": [ "geofence_Geofences" ], "security": [ { "geofence_bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/geofence_GeofenceRequest" }, "examples": { "polygonExample": { "summary": "Polygon Geofence", "value": { "name": "Warehouse Perimeter", "description": "A polygon-shaped geofence", "actions": [ "lockdown" ], "geometry": { "type": "polygon", "coordinates": [ { "latitude": 41.8902, "longitude": 12.4924 }, { "latitude": 41.8903, "longitude": 12.4925 }, { "latitude": 41.8904, "longitude": 12.4926 } ] } } }, "circleExample": { "summary": "Circular Geofence", "value": { "name": "Restricted Area", "description": "A circle-shaped geofence", "actions": [ "beep", "lockdown" ], "geometry": { "type": "circle", "coordinates": [ { "latitude": 41.8902, "longitude": 12.4924 } ], "radius": 100 } } }, "noActionsExample": { "summary": "Geofence with No Actions", "value": { "name": "Monitoring Zone", "description": "A geofence for monitoring only", "actions": [], "geometry": { "type": "circle", "coordinates": [ { "latitude": 41.8902, "longitude": 12.4924 } ], "radius": 50 } } } } } } }, "responses": { "201": { "description": "Geofence created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/geofence_GeofenceResponse" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/geofence_ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/geofence_ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/geofence_ErrorResponse" } } } } } }, "get": { "summary": "List all geofences", "description": "Retrieves a paginated list of geofences configured for the tenant. Use it to enumerate all geofences, optionally narrowed down by ID or name.\n\nSupports filtering by a list of geofence IDs, an exact name match, or a free-text name search, and can optionally include device summary statistics and/or a total count alongside each geofence in the response. Soft-deleted geofences are excluded unless is_deleted=true.\n\n**About Geofences**\n\nA geofence is a virtual geographic boundary (defined by a location and radius) that triggers device actions — such as locking down or sounding an alert — when a managed device enters or leaves the area. Geofences can also be tied to blueprints so that specific device configurations apply based on location.\n\n**Key Fields / Query Parameters**\n\n- geofence IDs — filter to a specific set of geofences by ID\n- name — exact-match filter on geofence name\n- search — free-text search across geofence names\n- is_deleted — when true, list only soft-deleted geofences\n- include device summary statistics — optionally embed device counts for each geofence in the list response\n\n**Common Use Cases**\n\n- Building a geofence management view that lists all configured boundaries\n- Looking up a geofence by name before fetching its device or blueprint details\n- Getting a quick device-count overview per geofence without a separate call\n", "operationId": "geofence_listGeofences", "tags": [ "geofence_Geofences" ], "parameters": [ { "$ref": "#/components/parameters/geofence_OffsetParam" }, { "$ref": "#/components/parameters/geofence_LimitParam" }, { "$ref": "#/components/parameters/geofence_IdsParam" }, { "$ref": "#/components/parameters/geofence_IncludeSummaryParam" }, { "$ref": "#/components/parameters/geofence_IncludeCountParam" }, { "$ref": "#/components/parameters/geofence_SearchParam" }, { "$ref": "#/components/parameters/geofence_NameParam" }, { "$ref": "#/components/parameters/geofence_IsDeletedParam" } ], "security": [ { "geofence_bearerAuth": [] } ], "responses": { "200": { "description": "A list of geofences", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "next": { "type": "string", "nullable": true, "example": "/v1/geofences?offset=10&limit=10" }, "previous": { "type": "string", "nullable": true, "example": null }, "count": { "type": "integer", "nullable": true, "description": "Total count of geofences matching the filters. Only included when include_count=true.", "example": 42 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/geofence_GeofenceListResponse" } } } } } }, "examples": { "example": { "value": { "content": { "next": "/v1/geofences?offset=10&limit=10", "previous": null, "results": [ { "id": "11111111-1111-1111-1111-111111111111", "name": "Sample Polygon Geofence", "description": "A polygon shaped zone", "actions": [ "lockdown" ], "geometry": { "type": "polygon", "coordinates": [ { "latitude": 41.8902, "longitude": 12.4924 }, { "latitude": 41.8903, "longitude": 12.4925 }, { "latitude": 41.8904, "longitude": 12.4926 } ] }, "created_at": "2024-06-24T14:00:00Z", "updated_at": "2024-06-24T15:00:00Z" }, { "id": "22222222-2222-2222-2222-222222222222", "name": "Sample Circular Geofence", "description": "A circle shaped zone", "actions": [ "beep" ], "geometry": { "type": "circle", "coordinates": [ { "latitude": 41.8902, "longitude": 12.4924 } ], "radius": 100 }, "created_at": "2024-06-25T10:00:00Z", "updated_at": "2024-06-25T11:00:00Z" } ] } } }, "withSummary": { "summary": "With device summary", "value": { "content": { "next": null, "previous": null, "count": 1, "results": [ { "id": "11111111-1111-1111-1111-111111111111", "name": "Sample Geofence", "description": "A geofence with device tracking", "actions": [ "lockdown" ], "geometry": { "type": "polygon", "coordinates": [ { "latitude": 41.8902, "longitude": 12.4924 }, { "latitude": 41.8903, "longitude": 12.4925 }, { "latitude": 41.8904, "longitude": 12.4926 } ] }, "created_at": "2024-06-24T14:00:00Z", "updated_at": "2024-06-24T15:00:00Z", "device_summary": { "total_devices": 50, "inside_count": 30, "outside_count": 18, "unknown_count": 2 }, "blueprints": [ { "blueprint_id": "550e8400-e29b-41d4-a716-446655440000", "blueprint_version_number": 1, "device_count": 25 }, { "blueprint_id": "550e8400-e29b-41d4-a716-446655440001", "blueprint_version_number": 2, "device_count": 15 }, { "blueprint_id": "550e8400-e29b-41d4-a716-446655440002", "blueprint_version_number": 1, "device_count": 10 } ] } ] } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/geofence_ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/geofence_ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/geofence_ErrorResponse" } } } } } } }, "/geofence/v1/geofences/{geofence_id}": { "delete": { "summary": "Soft-delete a geofence", "description": "Hides a geofence from list and apply immediately by setting is_deleted and deleted_at. The definition row is kept so devices that still have it can resolve the name (for example `{name} (Deleted)` on Device Overview). Device associations are not removed by this call.\n\n**Common Use Cases**\n\n- Removing a geofence from the console while leftover devices catch up\n- Reusing the same geofence name after delete\n", "operationId": "geofence_deleteGeofence", "tags": [ "geofence_Geofences" ], "security": [ { "geofence_bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/geofence_GeofenceIdParam" } ], "responses": { "200": { "description": "Geofence soft-deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "description": "Empty content object", "example": {} } } } } } }, "400": { "description": "Invalid geofence ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/geofence_ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/geofence_ErrorResponse" } } } }, "404": { "description": "Geofence not found, already deleted, or belongs to another tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/geofence_ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/geofence_ErrorResponse" } } } } } } }, "/geofence/v1/geofences/{geofence_id}/device-summary": { "get": { "summary": "Get device summary for a geofence", "description": "Returns aggregate device statistics for a specific geofence — total device count, how many devices are currently inside the boundary, and how many are outside. Use it for a quick, single-call summary rather than pulling the full device list.\n\nScoped to a single geofence_id and returns counts only, not individual device records — use the devices sub-resource for per-device detail.\n\n**About Geofences**\n\nA geofence is a virtual geographic boundary tied to device location tracking; devices are continuously evaluated as inside or outside the fence to trigger configured actions. This endpoint gives an at-a-glance rollup of that inside/outside state across all devices tied to the geofence.\n\n**Key Fields / Query Parameters**\n\n- geofence_id — path parameter identifying the geofence to summarize\n\n**Common Use Cases**\n\n- Powering a geofence dashboard tile showing total/inside/outside device counts\n- Quickly checking compliance for a location-restricted fleet without listing every device\n", "operationId": "geofence_getDeviceSummary", "tags": [ "geofence_Device State" ], "parameters": [ { "$ref": "#/components/parameters/geofence_XEsperTenantIdHeader" }, { "$ref": "#/components/parameters/geofence_XCallerIdHeader" }, { "$ref": "#/components/parameters/geofence_GeofenceIdParam" } ], "security": [ { "geofence_bearerAuth": [] } ], "responses": { "200": { "description": "Device summary retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/geofence_DeviceSummaryResponse" } } }, "examples": { "example": { "value": { "content": { "total_devices": 100, "inside_count": 60, "outside_count": 35, "unknown_count": 5 } } } } } } }, "400": { "description": "Invalid geofence ID or missing tenant ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/geofence_ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/geofence_ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/geofence_ErrorResponse" } } } } } } }, "/geofence/v1/geofences/{geofence_id}/blueprints": { "get": { "summary": "Get blueprint usage statistics for a geofence", "description": "Returns paginated statistics on blueprint usage within a specific geofence — which blueprints are applied to devices inside that geofence and how many devices use each. Use it to understand how blueprint-driven configuration correlates with a location-based boundary.\n\nScoped to a single geofence_id; each result identifies a blueprint and the count of devices in that geofence currently using it.\n\n**About Geofences**\n\nA geofence is a virtual geographic boundary that can be tied to blueprint-based device configuration, so devices entering or leaving the boundary can be managed differently depending on which blueprint they're running. This endpoint gives visibility into that blueprint-to-geofence relationship.\n\n**Key Fields / Query Parameters**\n\n- geofence_id — path parameter identifying the geofence to report on\n\n**Common Use Cases**\n\n- Auditing which blueprint versions are in use across devices within a specific geofence\n- Verifying blueprint rollout coverage for a location-restricted device population\n", "operationId": "geofence_getBlueprintUsage", "tags": [ "geofence_Device State" ], "parameters": [ { "$ref": "#/components/parameters/geofence_XEsperTenantIdHeader" }, { "$ref": "#/components/parameters/geofence_XCallerIdHeader" }, { "$ref": "#/components/parameters/geofence_GeofenceIdParam" }, { "$ref": "#/components/parameters/geofence_OffsetParam" }, { "$ref": "#/components/parameters/geofence_LimitParam" } ], "security": [ { "geofence_bearerAuth": [] } ], "responses": { "200": { "description": "Blueprint usage statistics retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "next": { "type": "string", "nullable": true, "example": "/v1/geofences/f5316a75-f186-4769-970e-28d6a1a0e110/blueprints?offset=10&limit=10" }, "previous": { "type": "string", "nullable": true, "example": null }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/geofence_BlueprintUsageItem" } } } } } }, "examples": { "example": { "value": { "content": { "next": "/v1/geofences/f5316a75-f186-4769-970e-28d6a1a0e110/blueprints?offset=10&limit=10", "previous": null, "results": [ { "blueprint_id": "550e8400-e29b-41d4-a716-446655440000", "blueprint_version_number": 1, "device_count": 25 }, { "blueprint_id": "550e8400-e29b-41d4-a716-446655440002", "blueprint_version_number": 2, "device_count": 15 } ] } } } } } } }, "400": { "description": "Invalid geofence ID, missing tenant ID, or missing pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/geofence_ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/geofence_ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/geofence_ErrorResponse" } } } } } } }, "/geofence/v1/geofences/{geofence_id}/devices": { "get": { "summary": "Get devices for a geofence", "description": "Returns a paginated list of devices and their current state relative to a specific geofence. Use it when you need the actual device records, not just aggregate counts.\n\nSupports filtering by inside/outside status and by blueprint version ID, so you can drill into, for example, only the devices currently outside the boundary running a particular blueprint version.\n\n**About Geofences**\n\nA geofence is a virtual geographic boundary tied to device location tracking, and can be associated with blueprint-driven configuration so a device's blueprint version may factor into how it's managed inside vs. outside the fence. This endpoint exposes the per-device detail behind the aggregate device-summary statistics.\n\n**Key Fields / Query Parameters**\n\n- geofence_id — path parameter identifying the geofence\n- inside/outside status — filters devices by whether they are currently within the geofence boundary\n- blueprint version ID — filters devices by the blueprint version they're currently running\n\n**Common Use Cases**\n\n- Listing devices that have left a geofenced area for follow-up or remediation\n- Cross-referencing which blueprint versions are running on devices inside vs. outside a boundary\n", "operationId": "geofence_getDevices", "tags": [ "geofence_Device State" ], "parameters": [ { "$ref": "#/components/parameters/geofence_XEsperTenantIdHeader" }, { "$ref": "#/components/parameters/geofence_XCallerIdHeader" }, { "$ref": "#/components/parameters/geofence_GeofenceIdParam" }, { "$ref": "#/components/parameters/geofence_OffsetParam" }, { "$ref": "#/components/parameters/geofence_LimitParam" }, { "$ref": "#/components/parameters/geofence_InsideParam" }, { "$ref": "#/components/parameters/geofence_BlueprintIdParam" }, { "$ref": "#/components/parameters/geofence_BlueprintVersionNumberParam" } ], "security": [ { "geofence_bearerAuth": [] } ], "responses": { "200": { "description": "Device list retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object", "properties": { "next": { "type": "string", "nullable": true, "example": "/v1/geofences/f5316a75-f186-4769-970e-28d6a1a0e110/devices?offset=10&limit=10" }, "previous": { "type": "string", "nullable": true, "example": null }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/geofence_DeviceListingItem" } } } } } }, "examples": { "example": { "value": { "content": { "next": "/v1/geofences/f5316a75-f186-4769-970e-28d6a1a0e110/devices?offset=10&limit=10", "previous": null, "results": [ { "device_id": "660e8400-e29b-41d4-a716-446655440000", "blueprint_id": "550e8400-e29b-41d4-a716-446655440000", "blueprint_version_number": 1, "inside": true, "state_changed_at": "2025-07-24T09:00:00Z" }, { "device_id": "660e8400-e29b-41d4-a716-446655440001", "blueprint_id": "550e8400-e29b-41d4-a716-446655440002", "blueprint_version_number": 2, "inside": false, "state_changed_at": "2025-07-24T08:30:00Z" } ] } } } } } } }, "400": { "description": "Invalid geofence ID, missing tenant ID, invalid query parameters, or missing pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/geofence_ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/geofence_ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/geofence_ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "esper_cloud_api_apiKey": { "type": "http", "scheme": "bearer", "description": "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n curl -X GET \\\n https://-api.esper.cloud/api/enterprise//device/ \\\n -H 'Authorization: Bearer ' \\\n -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n" }, "pipelines_SCAPIAuthToken": { "type": "http", "scheme": "bearer" }, "device_apiKey": { "type": "http", "scheme": "bearer", "description": "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n curl -X GET \\\n https://-api.esper.cloud/api/enterprise//device/ \\\n -H 'Authorization: Bearer ' \\\n -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n" }, "apps_management_apiKey": { "type": "http", "scheme": "bearer", "description": "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n curl -X GET \\\n https://-api.esper.cloud/api/enterprise//device/ \\\n -H 'Authorization: Bearer ' \\\n -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n" }, "commands_apiKey": { "type": "http", "scheme": "bearer", "description": "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n curl -X GET \\\n https://-api.esper.cloud/api/enterprise//device/ \\\n -H 'Authorization: Bearer ' \\\n -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n" }, "drift_apiKey": { "type": "http", "scheme": "bearer", "description": "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n curl -X GET \\\n https://-api.esper.cloud/api/enterprise//device/ \\\n -H 'Authorization: Bearer ' \\\n -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n" }, "device_onboarding_apiKey": { "type": "http", "scheme": "bearer", "description": "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n curl -X GET \\\n https://-api.esper.cloud/api/enterprise//device/ \\\n -H 'Authorization: Bearer ' \\\n -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n" }, "tenant_apiKey": { "type": "http", "scheme": "bearer", "description": "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n curl -X GET \\\n https://-api.esper.cloud/api/enterprise//device/ \\\n -H 'Authorization: Bearer ' \\\n -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n" }, "foundation_AuthToken": { "type": "apiKey", "in": "header", "name": "Authorization" }, "reports_bearerAuth": { "type": "http", "scheme": "bearer" }, "geofence_bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "esper_cloud_api_ApplicationVersion": { "title": "Version", "type": "object", "properties": { "id": { "title": "Id", "type": "string", "format": "uuid", "readOnly": true }, "version_code": { "title": "Version code", "maxLength": 50, "minLength": 1, "type": "string" }, "build_number": { "title": "Build number", "maxLength": 100, "minLength": 1, "type": "string", "nullable": true }, "hash_string": { "title": "Hash string", "type": "string" }, "min_sdk_version": { "title": "Min sdk version", "maxLength": 10, "minLength": 1, "type": "string", "nullable": true }, "target_sdk_version": { "title": "Target sdk version", "maxLength": 10, "minLength": 1, "type": "string", "nullable": true }, "download_url": { "title": "Url", "type": "string", "format": "url" }, "icon_url": { "title": "Url for the icon", "type": "string", "format": "url" }, "release_name": { "title": "Name of the release", "type": "string" }, "release_comments": { "title": "comments about the release", "type": "string" } } }, "esper_cloud_api_Application": { "required": [ "application_name", "enterprise", "package_name" ], "type": "object", "properties": { "id": { "title": "Id", "type": "string", "format": "uuid", "readOnly": true }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_ApplicationVersion" } }, "application_name": { "title": "Application name", "maxLength": 255, "minLength": 1, "type": "string" }, "package_name": { "title": "Package name", "maxLength": 255, "minLength": 1, "type": "string" }, "developer": { "title": "Developer", "maxLength": 255, "minLength": 1, "type": "string", "nullable": true }, "category": { "title": "Category", "maxLength": 255, "minLength": 1, "type": "string", "nullable": true }, "content_rating": { "title": "Content rating", "type": "string", "format": "decimal" }, "compatibility": { "title": "Compatibility", "minLength": 1, "type": "string", "nullable": true }, "created_on": { "title": "Created on", "type": "string", "format": "date-time", "readOnly": true }, "updated_on": { "title": "Updated on", "type": "string", "format": "date-time", "readOnly": true }, "is_active": { "title": "Is active", "type": "boolean" }, "is_hidden": { "title": "Is hidden", "type": "boolean" }, "enterprise": { "title": "Enterprise", "type": "string", "format": "url" } } }, "esper_cloud_api_ErrorResponse": { "type": "object", "properties": { "errors": { "title": "Messages describing the error", "type": "array", "items": { "type": "string" } }, "message": { "title": "Message describing the error", "type": "string" }, "status": { "title": "alias name", "type": "integer" } } }, "esper_cloud_api_AppPermission": { "required": [ "enterprise", "permission" ], "type": "object", "properties": { "id": { "title": "Id", "type": "string", "format": "uuid", "readOnly": true }, "permission": { "title": "Permission", "maxLength": 255, "minLength": 1, "type": "string" }, "grant_state": { "title": "Grant state", "type": "string", "enum": [ "Default", "Denied", "Granted" ] }, "created_on": { "title": "Created on", "type": "string", "format": "date-time", "readOnly": true }, "updated_on": { "title": "Updated on", "type": "string", "format": "date-time", "readOnly": true }, "is_active": { "title": "Is active", "type": "boolean" }, "enterprise": { "title": "Enterprise", "type": "string", "format": "url" }, "app_version": { "title": "App version", "type": "string", "format": "url" } } }, "esper_cloud_api_AppVersion": { "title": "Application Version", "required": [ "enterprise", "permissions", "version_code" ], "type": "object", "properties": { "id": { "title": "Id", "type": "string", "format": "uuid", "readOnly": true }, "installed_count": { "title": "Installed count", "type": "integer", "readOnly": true }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/esper_cloud_api_AppPermission" } }, "app_file": { "title": "App file", "type": "string", "format": "url", "readOnly": true }, "app_icon": { "title": "App icon", "type": "string", "format": "url", "nullable": true, "readOnly": true }, "version_code": { "title": "Version code", "maxLength": 50, "minLength": 1, "type": "string" }, "build_number": { "title": "Build number", "maxLength": 100, "minLength": 1, "type": "string", "nullable": true }, "size_in_mb": { "title": "Size in mb", "type": "number" }, "hash_string": { "title": "Hash string", "type": "string" }, "release_name": { "title": "Release name", "maxLength": 255, "minLength": 1, "type": "string", "nullable": true }, "release_comments": { "title": "Release comments", "minLength": 1, "type": "string", "nullable": true }, "release_track": { "title": "Release track", "type": "string", "nullable": true, "enum": [ "Alpha", "Beta", "Production" ] }, "created_on": { "title": "Created on", "type": "string", "format": "date-time", "readOnly": true }, "updated_on": { "title": "Updated on", "type": "string", "format": "date-time", "readOnly": true }, "min_sdk_version": { "title": "Min sdk version", "maxLength": 10, "minLength": 1, "type": "string", "nullable": true }, "target_sdk_version": { "title": "Target sdk version", "maxLength": 10, "minLength": 1, "type": "string", "nullable": true }, "is_enabled": { "title": "Is enabled", "type": "boolean" }, "is_default": { "title": "Is Default", "type": "boolean" }, "enterprise": { "title": "Enterprise", "type": "string", "format": "url" }, "application": { "title": "Application", "type": "string", "format": "url" }, "approval_status": { "title": "Application status", "type": "string", "enum": [ "AVAILABLE", "ACCEPTED", "APPROVED", "REJECTED" ] } } }, "esper_cloud_api_AppVersionDelete": { "type": "object", "properties": { "request_id": { "title": "Request id", "type": "string", "format": "uuid" }, "templates": { "type": "array", "description": "List of linked templates to an app version", "items": { "type": "object", "properties": { "id": { "title": "Id", "type": "integer", "description": "Id of the linked template" }, "name": { "title": "Name", "type": "string", "description": "Name of the linked template" } } } } } }, "esper_cloud_api_InstallDevices": { "required": [ "id" ], "type": "object", "properties": { "id": { "title": "Id", "type": "string", "format": "uuid" }, "device_name": { "title": "Device name", "type": "string" }, "alias_name": { "title": "alias name", "type": "string", "nullable": true }, "group_name": { "title": "Group name", "maxLength": 255, "minLength": 1, "type": "string" } } }, "esper_cloud_api_GoogleEnterprise": { "type": "object", "required": [ "name" ], "properties": { "id": { "title": "Id", "type": "integer" }, "google_enterprise_id": { "title": "Google Enterprise Id", "type": "string" }, "name": { "title": "Name of Google Enterprise", "type": "string" }, "state": { "type": "integer" }, "callback_url": { "type": "string", "format": "url" }, "signup_url": { "type": "string", "format": "url" }, "completion_token": { "type": "string" }, "enterprise_token": { "type": "string" }, "is_active": { "type": "boolean" }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" }, "enterprise": { "type": "string" } } }, "esper_cloud_api_GoogleWebToken": { "type": "object", "properties": { "id": { "title": "Id", "type": "integer" }, "emm": { "title": "emm Id", "type": "integer" }, "token": { "title": "Webtoken", "type": "string" }, "parent_url": { "type": "string", "format": "url" }, "is_active": { "type": "boolean" }, "created_on": { "type": "string", "format": "date-time" } } }, "esper_cloud_api_GoogleWebTokenUpdate": { "type": "object", "required": [ "emm", "parent_url" ], "properties": { "id": { "title": "Id", "type": "integer" }, "emm": { "title": "emm Id", "type": "integer" }, "token": { "title": "Webtoken", "type": "string" }, "parent_url": { "type": "string", "format": "url" }, "is_active": { "type": "boolean" } } }, "esper_cloud_api_GoogleWebTokenUpdateNoRequirements": { "type": "object", "properties": { "id": { "title": "Id", "type": "integer" }, "emm": { "title": "emm Id", "type": "integer" }, "token": { "title": "Webtoken", "type": "string" }, "parent_url": { "type": "string", "format": "url" }, "is_active": { "type": "boolean" } } }, "esper_cloud_api_GoogleProduct": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "icon_url": { "type": "string", "format": "url" }, "is_active": { "type": "boolean" }, "title": { "type": "string" }, "unapproved": { "type": "boolean" }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" }, "min_sdk_version": { "type": "string" }, "google_product_id": { "type": "string" }, "package_name": { "type": "string", "minLength": 1, "maxLength": 255 }, "google_enterprise": { "type": "integer" } } }, "esper_cloud_api_PatchGoogleProduct": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "icon_url": { "type": "string", "format": "url" }, "is_active": { "type": "boolean" }, "title": { "type": "string" }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" }, "min_sdk_version": { "type": "string" }, "google_product_id": { "type": "string" }, "package_name": { "type": "string", "minLength": 1, "maxLength": 255 }, "google_enterprise": { "type": "integer" } } }, "esper_cloud_api_GoogleProductInstall": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "enterprise": { "type": "string" }, "device": { "type": "string" }, "install_state": { "type": "string" }, "version_code": { "type": "string" }, "install_type": { "type": "integer", "title": "install type- default 0, EMM 1" }, "is_force_install": { "type": "boolean" }, "reason_details": { "type": "string" }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "objects": { "type": "object" } } }, "esper_cloud_api_DeviceStateEnum": { "type": "integer", "format": "int32", "description": "Following are the Device States and their description\n\n```\n* 0 = Device State is Unspecified\n* 1 = Online\n* 20 = Disabled (device has been factory reset or removed from the Esper Dashboard)\n* 30 = Beginning Provisioning\n* 40 = Configuring Google Play (still provisioning)\n* 50 = Applying Policies and Installing Applications (still provisioning)\n* 60 = Offline\n* 70 = Device is undergoing a Factory Reset (reset started from Dashboard)\n* 80 = Device Onboarding in Progress\n* 90 = Device Onboarding Failed\n* 100 = Device Onboarded in Esper\n* 110 = Android For Work Account added\n* 120 = Apps installed\n* 130 = Branding Processed\n* 140 = Permission Policy Processed\n* 150 = Device Policy Processed\n* 160 = Device Settings Processed\n* 170 = Security Policy Processed\n* 180 = Phone Policy Processed\n* 190 = Custom Settings Processed\n* 200 = Registered\n```\n", "enum": [ 0, 1, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130, 140, 150, 160, 170, 180, 190, 200 ] }, "esper_cloud_api_EmmDevice": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "google_device_id": { "type": "string" }, "managementType": { "type": "string" }, "device": { "type": "string", "format": "uuid" }, "google_user": { "type": "integer", "format": "int64" }, "policy": { "type": "integer", "format": "int64" }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean", "default": true } } }, "esper_cloud_api_DeviceInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "url" }, "device_name": { "type": "string" }, "alias_name": { "type": "string", "description": "Device friendly name" }, "policy_name": { "type": "string" }, "status": { "type": "integer", "description": "Current status of device", "format": "int32" }, "state": { "$ref": "#/components/schemas/esper_cloud_api_DeviceStateEnum" }, "current_command": { "type": "string", "description": "Current command associated with device", "format": "uuid" }, "suid": { "type": "string", "description": "Device generated unique id" }, "directory_record_id": { "type": "string", "format": "uuid", "description": "ID of Directory Record associated with the device (if available)" }, "fcm_id": { "type": "string" }, "enterprise": { "type": "string", "format": "url" }, "policy": { "type": "string", "format": "url" }, "user": { "type": "string", "format": "url" }, "groups": { "type": "array", "items": { "type": "string", "format": "url" } }, "tags": { "type": "array", "items": { "type": "string" } }, "api_level": { "type": "integer", "format": "int32" }, "template_name": { "type": "string" }, "mqtt_id": { "type": "string" }, "softwareInfo": { "type": "object", "properties": {} }, "hardwareInfo": { "type": "object", "properties": {} }, "displays": { "type": "object", "properties": {} }, "networkInfo": { "type": "object", "properties": {} }, "memoryInfo": { "type": "object", "properties": {} }, "esper_cient": { "type": "string" }, "device_type": { "type": "string" }, "audioConstraints": { "type": "object", "properties": {} }, "provisioned_on": { "type": "string", "format": "date-time" }, "created_on": { "type": "string", "format": "date-time" }, "current_app_mode": { "type": "integer" }, "kiosk_app_name": { "type": "string" }, "lockdown_state": { "type": "integer" }, "timezone_string": { "type": "string" }, "initialtemplate": { "type": "string" }, "updated_on": { "type": "string", "format": "date-time" }, "emm_device": { "$ref": "#/components/schemas/esper_cloud_api_EmmDevice" }, "is_gms": { "type": "boolean", "default": true }, "is_active": { "type": "boolean", "default": true }, "has_seamlessInfo": { "type": "boolean", "readOnly": true } } }, "esper_cloud_api_DeviceApp": { "required": [ "app_name", "device", "package_name" ], "type": "object", "properties": { "id": { "title": "Id", "type": "string", "format": "uuid", "readOnly": true }, "app_name": { "title": "App name", "minLength": 1, "type": "string" }, "state": { "type": "string" }, "app_type": { "type": "string" }, "package_name": { "title": "Package name", "maxLength": 255, "minLength": 1, "type": "string" }, "whitelisted": { "title": "Whitelisted", "type": "boolean" }, "is_data_clearable": { "title": "Data clearable", "type": "boolean" }, "is_uninstallable": { "title": "Uninstallable", "type": "boolean" }, "product_id": { "title": "Product id", "maxLength": 255, "minLength": 1, "type": "string", "nullable": true }, "version_code": { "title": "Version code", "maxLength": 128, "minLength": 1, "type": "string", "nullable": true }, "version_name": { "title": "Version name", "maxLength": 128, "minLength": 1, "type": "string", "nullable": true }, "created_on": { "title": "Created on", "type": "string", "format": "date-time", "readOnly": true }, "updated_on": { "title": "Updated on", "type": "string", "format": "date-time", "readOnly": true }, "is_active": { "title": "Is active", "type": "boolean" }, "is_kiosk_app": { "type": "boolean" }, "is_esper_controlled": { "type": "boolean" }, "device": { "title": "AndroidDevice", "type": "string", "format": "uuid" } } }, "esper_cloud_api_AppInstallVersion": { "title": "Version", "type": "object", "properties": { "app_version_id": { "title": "App version id", "type": "string", "format": "uuid" }, "version_code": { "title": "Version code", "type": "string" }, "build_number": { "title": "Build number", "type": "string" }, "hash_string": { "title": "Hash string", "type": "string" } } }, "esper_cloud_api_AppInstallApplication": { "title": "Application", "type": "object", "properties": { "application_name": { "title": "Application name", "type": "string" }, "package_name": { "title": "Package name", "type": "string" }, "version": { "$ref": "#/components/schemas/esper_cloud_api_AppInstallVersion" }, "is_enabled": { "title": "Is enabled", "type": "boolean" } } }, "esper_cloud_api_AppInstallStateEnum": { "title": "Install state", "type": "string", "description": "Device App Install State\n\n``` * NOT_INSTALLED = \"Not Installed\"\n* INSTALL_IN_PROGRESS = \"Installation In-Progress\"\n* UNINSTALL_IN_PROGRESS = \"Uninstallation In-Progress\"\n* INSTALL_SUCCESS = \"Install Success\"\n* INSTALL_FAILED = \"Install Failed\"\n* UNINSTALL_SUCCESS = \"Uninstall Success\"\n* UNINSTALL_FAILED = \"Uninstall Failed\"\n```\n", "enum": [ "NOT_INSTALLED", "INSTALL_IN_PROGRESS", "UNINSTALL_IN_PROGRESS", "INSTALL_SUCCESS", "INSTALL_FAILED", "UNINSTALL_SUCCESS", "UNINSTALL_FAILED" ] }, "esper_cloud_api_AppInstall": { "required": [ "application", "device", "enterprise", "install_state" ], "type": "object", "properties": { "id": { "title": "Id", "type": "string", "format": "uuid", "readOnly": true }, "application": { "$ref": "#/components/schemas/esper_cloud_api_AppInstallApplication" }, "install_state": { "$ref": "#/components/schemas/esper_cloud_api_AppInstallStateEnum" }, "reason_details": { "title": "Reason details", "minLength": 1, "type": "string", "nullable": true }, "created_on": { "title": "Created on", "type": "string", "format": "date-time", "readOnly": true }, "updated_on": { "title": "Updated on", "type": "string", "format": "date-time", "readOnly": true }, "is_active": { "title": "Is active", "type": "boolean" }, "enterprise": { "title": "Enterprise", "type": "string", "format": "url" }, "device": { "title": "AndroidDevice", "type": "string", "format": "url" } } }, "esper_cloud_api_DeviceStatus": { "required": [ "data", "device", "enterprise" ], "type": "object", "properties": { "id": { "title": "ID", "type": "integer", "readOnly": true }, "data": { "title": "Data", "type": "string" }, "created_on": { "title": "Created on", "type": "string", "format": "date-time", "readOnly": true }, "device": { "title": "AndroidDevice", "type": "string", "format": "url" }, "enterprise": { "title": "Enterprise", "type": "string", "format": "url" } } }, "esper_cloud_api_EventFeed": { "type": "object", "properties": { "id": { "type": "integer", "description": "Integer representing the event ID" }, "message_id": { "type": "string", "format": "UUID", "description": "UUID string representing message ID" }, "device_status_id": { "type": "string", "format": "UUID", "description": "UUID string representing device status ID" }, "created_on": { "type": "string", "format": "date-time" }, "message": { "type": "string", "description": "Message describing the command, who issued it, and from which state it was issued." }, "device": { "type": "string", "format": "url", "description": "URL to device instance", "example": "https://{example}-api.esper.cloud/api/enterprise/{enterprise_id}/device/{device_id}/" }, "enterprise": { "type": "string", "format": "url", "description": "URL to enterprise instance", "example": "https://{example}-api.esper.cloud/api/enterprise/{enterprise_id}/" } } }, "esper_cloud_api_V0DeviceCommandEnum": { "type": "string", "description": "Following commands are supported\n\n```\n* ADD_TO_WHITELIST: Whitelist an installed sytem app. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper\n* ADD_WIFI_AP : Add wifi access points for device. Requires `wifi_access_points` in command arguments where `wifi_access_points` is the data with access points\n* CLEAR_APP_DATA : Clear data for an installed app. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper\n* CLEAR_APP_CACHE : Clear the cache of an installed app without removing its data. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper. Supported on Android 6.0+ devices with the supervisor installed.\n* INSTALL: Install an app on a device. Requires `app_version` in command arguments where `app_version` is the version id of app uploaded on Esper\n* LOCK: Lock device screen\n* REBOOT: Reboot a device\n* REMOVE_FROM_WHITELIST : Remove an installed system app from whitelist. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper\n* REMOVE_WIFI_AP : Remove Wifi access points for device. Requires `wifi_access_points` in command arguments where `wifi_access_points` is the data with access points\n* UPDATE_WIFI_AP : Update Wi-Fi access point configuration on device. Requires `wifi_ssid` and `wifi_security_type` in command arguments. Device must be connected to the target SSID. Supports EAP (enterprise) and personal (WPA2/WPA/WEP) networks. On failure, attempts to restore the previous configuration. Android only.\n* SET_APP_PERMISSION : Set permission for an installed app. Requires `package_name`, `grant_state`, `permission` in command arguments where `package_name` is the app package uploaded on Esper, `grant_state` should be \"PERMISSION_GRANT_STATE_DEFAULT\", \"PERMISSION_GRANT_STATE_DENIED\", \"PERMISSION_GRANT_STATE_GRANTED\" and `permission` is a valid permission\n* SET_APP_STATE : Set the state of an app - SHOW/HIDE/DISABLE/LAUNCHABLE_BUT_HIDDEN. Requries `app_state` and `package_name` in command arguments where `app_state` is the state of app and `package_name` is the app package uploaded on Esper\n* SET_BLUETOOTH_STATE : Set bluetooth state (ON/OFF) for device. Requires `bluetooth_state` in command arguments where `bluetooth_state` is a boolean.\n* SET_BRIGHTNESS_SCALE : Set brightness for device. Requires `brightness_value` in command arguments where `brightness_value` is an integer (1-100).\n* SET_DEVICE_LOCKDOWN_STATE : Set lockdown state for a device. Requires `state` and `message` in command arguments where `state` is LOCKED/UNLOCKED and `message` is the message to be added with command\n* SET_GPS_STATE :Set the GPS state for a device. Requires `gps_state` in command arguments where `gps_state` should be either 0, 1, 2, 3 or 4 (LOCATION_MODE_HIGH_ACCURACY = 0, LOCATION_MODE_SENSORS_ONLY = 1, LOCATION_MODE_BATTERY_SAVING = 2, LOCATION_MODE_OFF = 3, LOCATION_MODE_ON = 4)\n* SET_KIOSK_APP : Command to set the Kiosk app for a device. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper\n* SET_NEW_POLICY : Apply policy on device. Requires `policy_url` in command arguments where `policy_url` is the URL to the policy\n* SET_ROTATION_STATE : Set screen orientation. Requires `rotate_state` in command arguments where `rotate_state` should be either 0, 1 or 2 (0 = AUTO, 1 = PORTRAIT_ONLY, 2 = LANDSCAPE_ONLY)\n* SET_SCREEN_OFF_TIMEOUT: Set screen off timeout for a device. Requires `screen_off_timeout` in command arguments where `screen_off_timeout` should be either -1 or between 5000 and 1800000\n* SET_STREAM_VOLUME : Set stream volume for a device. Requires `stream` and `volume_level` in command arguments where `stream` should be either 0(Ring), 1(Notification), 2(Alarm) or 3(Music) and `volume_level` should be a value from 0 to 100\n* SET_TIMEZONE : Set the timezone for a device. Requires `timezone_string` in command arguments where `timezone_string` is a valid string representing the timezone\n* SET_WIFI_STATE : Set the wifi state (ON/OFF) for a device. Requires `wifi_state` in command arguments where `wifi_state` is a boolean.\n* UNINSTALL: Uninstall an app from device. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper\n* UPDATE_DEVICE_CONFIG: Push additional configurations to the Device\n* UPDATE_HEARTBEAT: Ping a device\n* UPDATE_LATEST_DPC : Prompt device to update the DPC app to the latest versions.\n* WIPE : Wipes the device.\n* RESET_LOCKSCREEN_PASSWORD: Change the lockscreen password of the device. Requires `new_lockscreen_password` in command arguments where `new_lockscreen_password` is a valid string.\n* CAPTURE_SCREENSHOT: Allows you to take a screenshot of the device's current screen. The \"tag\" is an optional param that can be set to corresponding screenshot.\n* UPDATE_BLUEPRINT: Pushes or reapplies the most current Blueprint version to the device or group.\n* NOTIFY_DEVICE: Allows you to broadcast message to the device. Requires 'title', 'message' and 'url' (optional) as string in command arguments. For scheduled message command requires 'name', 'time_type' as string and 'start_datetime' and 'end_datetime' as date-time.\n* SET_DEVICE_LANGUAGE: Set language for a device. Requires locale value in xx[_Zzzz]_yy where xx is language code, Zzzz is script (optional) and yy is country code.\n* SET_ETHERNET_SETTINGS: Set ethernet settings on supported Device\n* SET_STATIC_IP: Set static ip on the deivce. Requires interface, dhcp_dnabled, static_ip, primary_dns, subnet_mask, gateway, secondary_dns (optional)\n* BEEP_DEVICE: Allows you to make the device beep for a specified duration\n* SET_APP_NOTIFICATIONS: Enable/disable app notifications. Requries `app_notifications_state` and `package_name` in command arguments where `app_notifications_state` is a string that has the value `ENABLED` or `DISABLED` and `package_name` is the app package uploaded on Esper.\n* USE_ONLY_SAVED_WIFI_AP: Allow/disallow device to connect to unregistered WiFi APs. Requires boolean `use_only_saved_ap`.\n* CONVERGE: Allows you to converge the device to the latest version of its assigned blueprint.\n* SYNC_CONTENT: Allows you to sync content to the device. Requires `content_id` in command arguments where `content_id` is the id of the content to be synced. ```\n", "enum": [ "ADD_TO_WHITELIST", "ADD_WIFI_AP", "CLEAR_APP_DATA", "CLEAR_APP_CACHE", "INSTALL", "LOCK", "REBOOT", "REMOVE_FROM_WHITELIST", "REMOVE_WIFI_AP", "SET_APP_PERMISSION", "SET_APP_STATE", "SET_BLUETOOTH_STATE", "SET_BRIGHTNESS_SCALE", "SET_DEVICE_LOCKDOWN_STATE", "SET_GPS_STATE", "SET_KIOSK_APP", "SET_NEW_POLICY", "SET_ROTATION_STATE", "SET_SCREEN_OFF_TIMEOUT", "SET_STREAM_VOLUME", "SET_TIMEZONE", "SET_WIFI_STATE", "UNINSTALL", "UPDATE_DEVICE_CONFIG", "UPDATE_HEARTBEAT", "UPDATE_LATEST_DPC", "UPDATE_WIFI_AP", "WIPE", "RESET_LOCKSCREEN_PASSWORD", "UPDATE_BLUEPRINT", "CAPTURE_SCREENSHOT", "NOTIFY_DEVICE", "SET_DEVICE_LANGUAGE", "SET_ETHERNET_SETTINGS", "SET_STATIC_IP", "BEEP_DEVICE", "SET_APP_NOTIFICATIONS", "USE_ONLY_SAVED_WIFI_AP", "CONVERGE", "SYNC_CONTENT" ] }, "esper_cloud_api_V0CommandArgs": { "title": "Command args", "type": "object", "properties": { "device_alias_name": { "type": "string", "description": "Alternate human-readable name for your Device" }, "custom_settings_config": { "type": "object", "properties": {}, "description": "Managed configurations for your device (passed as JSON object)" }, "app_version": { "type": "string", "description": "The version id of app uploaded on Esper" }, "package_name": { "type": "string", "description": "The app package name uploaded on Esper" }, "policy_url": { "type": "string", "description": "The URL to the policy" }, "wifi_access_points": { "type": "object", "properties": {}, "description": "Wifi access points for the device (passed as JSON object)" }, "state": { "type": "string", "description": "LOCKED/UNLOCKED" }, "message": { "type": "string", "description": "Message to be added with command to notify device." }, "title": { "type": "string", "description": "Message title to be added with command to notify device." }, "url": { "type": "string", "description": "(Optional) Link to notify device." }, "app_state": { "type": "string", "description": "The state of app - SHOW/HIDE/DISABLE/LAUNCHABLE_BUT_HIDDEN" }, "bluetooth_state": { "type": "boolean", "description": "The state of bluetooth - ON/OFF" }, "brightness_value": { "type": "integer", "description": "The brightness value of a device(1-100)" }, "gps_state": { "type": "integer", "description": "The GPS state of a device. Should be either 0, 1, 2, 3 or 4 (LOCATION_MODE_HIGH_ACCURACY = 0, LOCATION_MODE_SENSORS_ONLY = 1, LOCATION_MODE_BATTERY_SAVING = 2, LOCATION_MODE_OFF = 3, LOCATION_MODE_ON = 4)" }, "rotate_state": { "type": "integer", "description": "The screen orientation of a device. Should be either 0, 1 or 2 (0 = AUTO, 1 = PORTRAIT_ONLY, 2 = LANDSCAPE_ONLY)" }, "screen_off_timeout": { "type": "integer", "description": "The value for screen timeout of a device. Should be either -1 or between 5000 and 1800000" }, "stream": { "type": "integer", "description": "The value of the volume stream. Should be either 0(Ring), 1(Notification), 2(Alarm) or 3(Music)" }, "volume_level": { "type": "integer", "description": "The level of volume. Should be a value from 0 to 100" }, "timezone_string": { "type": "integer", "description": "The timezone of a device. Should be a valid timezone string" }, "wifi_state": { "type": "boolean", "description": "The state of WIFI - ON/OFF" }, "wifi_revert_timeout": { "type": "integer", "description": "The WIFI revert timeout. Should be greater than or equal to 1" }, "locale": { "type": "string", "description": "Language and country code in xx[_Zzzz]_yy where xx is language code, Zzzz is script (optional) and yy is country code." }, "ethernet_auth_mode": { "type": "string", "description": "Chosen mode of authentication", "enum": [ "NONE", "EAP_TLS" ] }, "ethernet_ca_cert_alias": { "type": "string", "description": "CA certificate alias. It is mandatory with Auth Mode EAP_TLS" }, "ethernet_client_cert_alias": { "type": "string", "description": "Client certificate alias. It is mandatory with Auth Mode EAP_TLS" }, "ethernet_eap_identity": { "type": "string", "description": "EAP identity" }, "interface": { "type": "string", "description": "The network interface of the device - wlan/eth" }, "dhcp_enabled": { "type": "string", "description": "The dhcp state on the device - true/false" }, "static_ip": { "type": "string", "description": "The static ip to set on the device. Should be a valid ipv4" }, "primary_dns": { "type": "string", "description": "The primary dns to set on the device. Should be a valid ipv4" }, "subnet_mask": { "type": "string", "description": "The subnet mask set on the device. Should between 1-32 both inclusive" }, "secondary_dns": { "type": "string", "description": "The secondary dns to set on the device. Should be a valid ipv4" }, "gateway": { "type": "string", "description": "The gateway to set on the device. Should be a valid ipv4" }, "duration": { "type": "string", "description": "The beep duration specified in seconds. Value must be between 10 and 300, both inclusive." }, "tag": { "type": "string", "description": "The tag is an optional param that can be set to corresponding screenshot. Options are \"tag\"." }, "video_quality": { "type": "string", "description": "The video quality of the respective Remote Viewer session. Options are \"STANDARD\" and \"DATA_SAVER\"." }, "enable_debug_mode": { "type": "boolean", "default": false, "description": "The flag to determine whether device must go into Debug Mode, in order to retrieve bug report when the device is already in Kiosk Mode." }, "converge_with_provision_option": { "type": "boolean", "default": false, "description": "The flag to determine whether device should be converged with provision only or not." }, "auto_update_mode": { "type": "string", "enum": [ "autoUpdateDefault", "autoUpdateHighPriority", "autoUpdatePostponed" ], "default": "autoUpdateHighPriority", "description": "(Optional) Auto update mode for google play application" }, "content_id": { "type": "string", "description": "The id of the content to be synced." } } }, "esper_cloud_api_V0CommandScheduleEnum": { "type": "string", "description": "Following Schedule types are supported\n\n```\n* IMMEDIATE: Schedule the command to execute Immediately\n* WINDOW: Schedule the command to execute within the given window\n* RECURRING: Schedule the command to execute during the scheduled time until it succeeds or expires. After executing successfully, it will not fire again.\n```\n", "enum": [ "IMMEDIATE", "WINDOW", "RECURRING" ] }, "esper_cloud_api_V0CommandScheduleArgsTimeTypeEnum": { "type": "string", "description": "The Time-Type argument, in Schedule args, is to indicate which timezone the Command Framework should utilize when scheduling the command.\nFollowing Schedule Args for Time-Type are supported:\n\n```\n* CONSOLE: Use the local timezone of the user creating the schedule.\n* DEVICE: Use the local timezone of the device, to which the command is issued, wherever it may be.\n```\n", "enum": [ "console", "device" ] }, "esper_cloud_api_V0CommandScheduleArgs": { "title": "Command Schedule Arguments", "type": "object", "properties": { "name": { "type": "string" }, "start_datetime": { "type": "string", "format": "date-time" }, "end_datetime": { "type": "string", "format": "date-time" }, "time_type": { "$ref": "#/components/schemas/esper_cloud_api_V0CommandScheduleArgsTimeTypeEnum" }, "window_start_time": { "type": "string", "description": "It is automatically populated by the time field from the request's start_datetime and cannot be injected via the API request body." }, "window_end_time": { "type": "string", "description": "It is automatically populated by the time field from the request's end_datetime and cannot be injected via the API request body." }, "days": { "type": "array", "items": { "type": "string" } } } }, "esper_cloud_api_V0CommandRequestStatus": { "type": "object", "properties": { "state": { "title": "Command State", "type": "string", "description": "Current State of command", "format": "uuid" }, "total": { "title": "Count", "type": "integer", "description": "No of commands currently in this state", "format": "int64" } } }, "esper_cloud_api_V0CommandRequest": { "type": "object", "properties": { "id": { "title": "Id", "type": "string", "description": "Unique command request identifier", "format": "uuid", "readOnly": true }, "enterprise": { "title": "Enterprise ID", "type": "string", "description": "Esper account identifier", "format": "uuid", "readOnly": true }, "command_type": { "type": "string", "description": "Identifies the type of command\n\n```\n* DEVICE: command request is meant for devices\n* GROUP: command request is meant for groups\n* DYNAMIC: command request is meant for dynamic set of devices\n i.e subset of devices from different groups or otherwise.\n```\n", "enum": [ "DEVICE", "GROUP", "DYNAMIC" ] }, "devices": { "maxItems": 1000, "minItems": 0, "type": "array", "description": "list of devices to run commands", "items": { "type": "string", "format": "uuid" } }, "groups": { "maxItems": 500, "minItems": 0, "type": "array", "description": "list of groups to run commands", "items": { "type": "string", "format": "uuid" } }, "command": { "$ref": "#/components/schemas/esper_cloud_api_V0DeviceCommandEnum" }, "command_args": { "$ref": "#/components/schemas/esper_cloud_api_V0CommandArgs" }, "schedule": { "$ref": "#/components/schemas/esper_cloud_api_V0CommandScheduleEnum" }, "schedule_args": { "$ref": "#/components/schemas/esper_cloud_api_V0CommandScheduleArgs" }, "issued_by": { "type": "string", "description": "command is issued by this user", "format": "url", "readOnly": true }, "created_on": { "title": "Created on", "type": "string", "description": "Timestamp of command request", "format": "date-time", "readOnly": true }, "status": { "title": "Current Status", "type": "array", "description": "Show current status of commands issued during this request", "readOnly": true, "items": { "$ref": "#/components/schemas/esper_cloud_api_V0CommandRequestStatus" } } } }, "esper_cloud_api_DeviceGroup": { "required": [ "name" ], "type": "object", "properties": { "id": { "title": "Id", "type": "string", "description": "Group id", "format": "uuid", "readOnly": true }, "name": { "title": "Name", "type": "string", "description": "Group name" }, "created_on": { "title": "Created on", "type": "string", "description": "Date and time of when the group was created", "format": "date-time", "readOnly": true }, "enterprise": { "title": "Enterprise", "type": "string", "description": "Enterprise url", "format": "url", "readOnly": true }, "parent": { "title": "Parent", "type": "string", "description": "Parent group url", "format": "url" }, "device_count": { "title": "Device count", "type": "integer", "description": "Count of devices in the group", "readOnly": true }, "path": { "title": "Path", "type": "string", "description": "Path of the group", "readOnly": true }, "children_count": { "title": "Children count", "type": "integer", "description": "Count of child groups", "readOnly": true }, "thumbnail": { "title": "thumbnail", "description": "thumbnail associated with the group", "type": "string", "format": "uuid" }, "blueprint": { "title": "Blueprint", "description": "Blueprint associated with the group.", "type": "string", "format": "uuid", "readOnly": true } } }, "esper_cloud_api_DeviceGroupUpdate": { "required": [ "name" ], "type": "object", "properties": { "id": { "title": "Id", "type": "string", "description": "Group id", "format": "uuid", "readOnly": true }, "name": { "title": "Name", "type": "string", "description": "Group name" }, "created_on": { "title": "Created on", "type": "string", "description": "Date and time of when the group was created", "format": "date-time", "readOnly": true }, "enterprise": { "title": "Enterprise", "type": "string", "description": "Enterprise url", "format": "url", "readOnly": true }, "parent": { "title": "Parent", "type": "string", "description": "Parent group id", "format": "uuid" }, "device_ids": { "title": "Device ids", "uniqueItems": true, "type": "array", "description": "Devices ids", "items": { "type": "string", "format": "uuid" } }, "device_count": { "title": "Device count", "type": "integer", "readOnly": true }, "path": { "title": "Path", "type": "string", "description": "Path of the group", "readOnly": true }, "children_count": { "title": "Children Count", "type": "integer", "description": "Count of child groups", "readOnly": true } } }, "esper_cloud_api_DeviceGroupPartialUpdate": { "type": "object", "properties": { "id": { "title": "Id", "type": "string", "description": "Group id", "format": "uuid", "readOnly": true }, "name": { "title": "Name", "type": "string", "description": "Group name" }, "created_on": { "title": "Created on", "type": "string", "description": "Date and time of when the group was created", "format": "date-time", "readOnly": true }, "enterprise": { "title": "Enterprise", "type": "string", "description": "Enterprise url", "format": "url", "readOnly": true }, "parent": { "title": "Parent", "type": "string", "description": "Parent group id", "format": "uuid" }, "device_ids": { "title": "Device ids", "uniqueItems": true, "type": "array", "description": "Device ids", "items": { "type": "string", "format": "uuid" } }, "device_count": { "title": "Device count", "type": "integer", "description": "Count of devices in the group", "readOnly": true }, "path": { "title": "Path", "type": "string", "description": "Path of the group", "readOnly": true }, "children_count": { "title": "Children Count", "type": "integer", "description": "Count of child groups", "readOnly": true } } }, "esper_cloud_api_GroupThumbnail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "image_file": { "type": "string", "readOnly": true }, "thumbnail_url": { "type": "string", "readOnly": true }, "created_on": { "type": "string", "format": "date-time", "readOnly": true } } }, "esper_cloud_api_DeviceSubGroup": { "type": "object", "properties": { "subgroups": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "esper_cloud_api_EnterprisePolicyData": { "title": "Policy Data", "type": "object", "properties": { "keyguardDisabled": { "type": "boolean", "description": "Should KeyGuard be disabled?" }, "safeBootDisabled": { "type": "boolean", "description": "Should SafeBoot be disabled?" }, "statusBarDisabled": { "type": "boolean", "description": "Should Status Bar be disabled?" }, "factoryResetDisabled": { "type": "boolean", "description": "Should Factory Reset be disabled?" }, "screenshotDisabled": { "type": "boolean", "description": "Should Screenshot capability be disabled?" }, "usbConnectivityDisabled": { "type": "boolean", "description": "Should USB connectivity be disabled?" }, "smsDisabled": { "type": "boolean", "description": "Should SMS functionality be disabled?" }, "outgoingCallsDisabled": { "type": "boolean", "description": "Should Outgoing Calls be disabled?" }, "cameraDisabled": { "type": "boolean", "description": "Should Camera be disabled?" }, "nfcBeamDisabled": { "type": "boolean", "description": "Should NFC capability be disabled?" }, "disablePlayStore": { "type": "boolean", "description": "Should Google Play Store be disabled on the device?" }, "usbFileTransferDisabled": { "type": "boolean", "description": "Should USB File transfer capability be disabled?" }, "tetheringDisabled": { "type": "boolean", "description": "Should USB Tethering capability be enabled?" }, "dateTimeConfigDisabled": { "type": "boolean", "description": "Should Date/Time configuration capability be disabled?" }, "appUninstallDisabled": { "type": "boolean", "description": "Should App uninstall capability be disabled?" }, "googleAssistantDisabled": { "type": "boolean", "description": "Should Google Assistant feature be disabled?" }, "disableLocalAppInstall": { "type": "boolean", "description": "Should Side-loading of Applications be disabled?" }, "adbDisabled": { "type": "boolean", "description": "Should Android Debugger be disabled?" }, "phonePolicy": { "type": "object", "properties": { "incomingNumbers": { "type": "array", "description": "List of permitted incoming phone numbers to receive calls from", "items": { "maxLength": 15, "type": "string" } }, "outgoingNumbers": { "type": "array", "description": "List of permitted outgoing phone numbers to make calls to", "items": { "maxLength": 15, "type": "string" } }, "dialer": { "type": "string", "description": "Pick a dialer - System default or Esper Dialer", "enum": [ "DEFAULT", "SHOONYA" ] }, "allowUssdCodes": { "type": "boolean", "default": false, "description": "Allow USSD codes to be dialed. Default is false" } }, "description": "Rules regarding restricting calls from/to phone-numbers" }, "frpGoogles": { "type": "array", "description": "Details regarding Factory Reset Protection capability. List of permitted Google People IDs, emails and such", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of User account provided - USER or ADMIN", "enum": [ "USER", "ADMIN" ] }, "email": { "type": "string", "description": "Email id to be used for Factory protection. This will be asked on the Device's UI", "format": "email" }, "googleId": { "type": "string", "description": "Google People ID associated with the above email (https://developers.google.com/people/api/rest/v1/people/get)" } } } }, "googleAccountPermission": { "type": "object", "properties": { "maxAccount": { "type": "integer", "description": "Maximum number of Google accounts to be associated with this device. (Max = 10)" }, "emails": { "type": "array", "description": "List of emails to be associated", "items": { "type": "string", "format": "email" } }, "domains": { "type": "array", "description": "List of domains that can be associated", "items": { "type": "string" } } }, "description": "Details regarding Google accounts to be associated with the device" }, "devicePasswordPolicy": { "type": "object", "properties": { "passwordQuality": { "type": "string", "description": "What is the type of password quality to apply to the device?", "enum": [ "PASSWORD_QUALITY_ALPHABETIC", "PASSWORD_QUALITY_ALPHANUMERIC", "PASSWORD_QUALITY_BIOMETRIC_WEAK", "PASSWORD_QUALITY_COMPLEX", "PASSWORD_QUALITY_NUMERIC", "PASSWORD_QUALITY_NUMERIC_COMPLEX", "PASSWORD_QUALITY_SOMETHING", "PASSWORD_QUALITY_UNSPECIFIED" ] } }, "description": "Define the Password Policy for the device" }, "minimumPasswordLength": { "minimum": 4, "type": "integer", "description": "What is the minimum length for your device's password" }, "permissionPolicy": { "type": "string", "description": "What permission should be applied by default for all apps, henceforth?", "enum": [ "PERMISSION_POLICY_PROMPT", "PERMISSION_POLICY_AUTO_GRANT", "PERMISSION_POLICY_AUTO_DENY" ] }, "deviceUpdatePolicy": { "type": "object", "properties": { "type": { "type": "string", "description": "What type of installation is preferred?", "enum": [ "TYPE_INSTALL_AUTOMATIC", "TYPE_POSTPONE", "TYPE_INSTALL_WINDOWED", "TYPE_INSTALL_DISABLED" ] }, "maintenanceStart": { "type": "integer", "description": "If the `type` is `TYPE_INSTALL_WINDOWED`, when should the maintenance start?" }, "maintenanceEnd": { "type": "integer", "description": "If the `type` is `TYPE_INSTALL_WINDOWED`, when should the maintenance end?" } }, "description": "Configuration regarding Device OS Updates" }, "settingsAccessLevel": { "type": "string", "description": "Type of Android settings app to be applied? Default System Settings or ESPER Settings App?", "enum": [ "SYSTEM", "SHOONYA", "NONE" ] }, "settingsAppPassword": { "type": "string", "description": "Lock Password (optional) for the ESPER Settings app", "format": "password" } } }, "esper_cloud_api_EnterprisePolicy": { "required": [ "enterprise", "name", "policy" ], "type": "object", "properties": { "uuid": { "title": "UUID", "type": "string", "description": "Unique Policy identifier", "format": "uuid", "readOnly": true }, "enterprise": { "title": "Enterprise url", "type": "string", "description": "Url of the enterprise resource", "format": "url" }, "url": { "title": "Policy URL", "type": "string", "description": "URL link to policy", "format": "url", "readOnly": true }, "name": { "title": "Policy Name", "type": "string", "description": "Name of the Policy" }, "description": { "title": "Policy Description", "type": "string", "description": "Details regarding the Policy" }, "device_count": { "title": "Number of Devices with this policy applied", "type": "integer", "description": "Count of Devices with this policy applied", "readOnly": true }, "google_policy_id": { "title": "Google policy id", "type": "string", "description": "Id of the Google policy", "readOnly": true }, "policy": { "$ref": "#/components/schemas/esper_cloud_api_EnterprisePolicyData" }, "updated_on": { "title": "Updated On", "type": "string", "description": "Last-Updated Timestamp of Policy", "format": "date-time", "readOnly": true }, "created_on": { "title": "Created on", "type": "string", "description": "Creation Timestamp of Policy", "format": "date-time", "readOnly": true }, "is_active": { "title": "Policy Active status", "type": "boolean", "description": "Is this policy currently active" } } }, "esper_cloud_api_EnterprisePolicyPartialUpdate": { "type": "object", "properties": { "uuid": { "title": "UUID", "type": "string", "description": "Unique Policy identifier", "format": "uuid", "readOnly": true }, "enterprise": { "title": "Enterprise url", "type": "string", "description": "Url of the enterprise resource", "format": "url" }, "url": { "title": "Policy URL", "type": "string", "description": "URL link to policy", "format": "url", "readOnly": true }, "name": { "title": "Policy Name", "type": "string", "description": "Name of the Policy" }, "description": { "title": "Policy Description", "type": "string", "description": "Details regarding the Policy" }, "device_count": { "title": "Number of Devices with this policy applied", "type": "integer", "description": "Count of Devices with this policy applied", "readOnly": true }, "policy": { "$ref": "#/components/schemas/esper_cloud_api_EnterprisePolicyData" }, "updated_on": { "title": "Updated On", "type": "string", "description": "Last-Updated Timestamp of Policy", "format": "date-time", "readOnly": true }, "created_on": { "title": "Created on", "type": "string", "description": "Creation Timestamp of Policy", "format": "date-time", "readOnly": true }, "is_active": { "title": "Policy Active status", "type": "boolean", "description": "Is this policy currently active" }, "google_policy_id": { "title": "Google policy id", "type": "string", "description": "Id of the Google policy", "readOnly": true } } }, "esper_cloud_api_V0CommandStatus1": { "type": "object", "properties": { "id": { "title": "Id", "type": "string", "description": "Unique command identifier", "format": "uuid", "readOnly": true }, "request": { "title": "Request Id", "type": "string", "description": "Request Id associated with this command", "format": "uuid", "readOnly": true }, "device": { "title": "AndroidDevice", "type": "string", "description": "Device associated with this command", "format": "url", "readOnly": true }, "state": { "type": "string", "description": "Current state of the command", "enum": [ "Command Queued", "Command Initiated", "Command Acknowledged", "Command In Progress", "Command TimeOut", "Command Success", "Command Failure", "Command Scheduled", "Command Cancelled" ] }, "reason": { "type": "string", "description": "details briefing the reason for current command state" }, "created_on": { "title": "Created on", "type": "string", "description": "Timestamp of command creation", "format": "date-time", "readOnly": true }, "updated_on": { "title": "Updated on", "type": "string", "description": "Last updated timestamp of command", "format": "date-time", "readOnly": true }, "meta": { "type": "object", "properties": { "device": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "device_name": { "type": "string" }, "alias_name": { "type": "string", "nullable": true }, "timezone_string": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Tags associated with the device" }, "managed_by": { "type": "string", "enum": [ "BLUEPRINT", "TEMPLATE" ], "description": "Indicates whether the device is managed by a Blueprint or Template" } } } } } } }, "esper_cloud_api_Content": { "required": [ "id" ], "type": "object", "properties": { "id": { "title": "Id", "type": "integer", "description": "Unique content Identifier", "readOnly": true }, "download_url": { "title": "Content download URL", "type": "string", "description": "URL to download the content", "format": "url" }, "name": { "title": "Name", "type": "string", "description": "Name of the content" }, "key": { "title": "Key", "maxLength": 255, "minLength": 1, "type": "string" }, "is_dir": { "title": "Is Directory", "type": "boolean", "default": false }, "kind": { "title": "Content kind", "maxLength": 255, "type": "string", "description": "The mime type of the content", "nullable": true }, "hash": { "title": "Content Hash", "type": "string", "description": "Hash string of the content" }, "size": { "title": "Content Size", "maxLength": 255, "type": "string", "description": "Size of the content in bytes" }, "path": { "title": "Path", "type": "string", "description": "Path to the content" }, "permissions": { "title": "Permissions", "type": "string", "description": "The permission string for the content" }, "tags": { "title": "Content tags", "type": "array", "description": "Tags for the content", "items": { "maxLength": 255, "type": "string" } }, "description": { "title": "Content description", "type": "string", "description": "Description for the content", "nullable": true }, "created": { "title": "Created on", "type": "string", "format": "date-time", "readOnly": true }, "modified": { "title": "Modified on", "type": "string", "format": "date-time", "readOnly": true }, "enterprise": { "title": "Enterprise", "type": "string", "description": "URL of the enterprise resource", "format": "url" }, "owner": { "title": "Owner", "type": "object", "properties": { "id": { "type": "integer" }, "username": { "type": "string" } }, "description": "Owner of the content" } } }, "esper_cloud_api_AlertChannelsV1": { "type": "object", "properties": { "id": { "type": "integer" }, "properties": { "type": "object", "properties": { "to_address": { "type": "string", "format": "email" } } }, "name": { "type": "string" }, "type": { "type": "string", "description": "format of alert. e.g. email" }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" }, "enterprise": { "type": "string", "format": "uuid" }, "linked_alerts": { "type": "array", "items": { "type": "string" } } } }, "esper_cloud_api_UpdateAlertChannelsV1": { "type": "object", "properties": { "id": { "type": "integer" }, "properties": { "type": "object", "properties": { "to_address": { "type": "string", "format": "email" } } }, "name": { "type": "string" }, "type": { "type": "string", "description": "format of alert. e.g. email" }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" }, "enterprise": { "type": "string", "format": "uuid" } } }, "esper_cloud_api_AlarmRule": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "enterprise": { "type": "string", "format": "uuid" }, "devices": { "properties": { "id": { "type": "string", "format": "uuid" }, "device_name": { "type": "string" }, "alias_name": { "type": "string", "nullable": true } } }, "groups": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string" }, "description": { "type": "string" }, "metric": { "type": "string" }, "conditions": { "properties": { "value": { "type": "number", "format": "double" }, "unit": { "type": "string" }, "comparator": { "type": "string" }, "toggle_state": { "type": "boolean" } } }, "action_emails": { "type": "array", "items": { "type": "string", "format": "email" } }, "actions": { "type": "array", "items": { "type": "string" } }, "alert_channels": { "type": "array", "items": { "type": "string" } }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "realert_interval": { "type": "integer" }, "repeat_times": { "type": "integer" }, "trigger_count": { "type": "integer" }, "daily_trigger_count": { "type": "integer" } } }, "esper_cloud_api_UpdateAlarmRule": { "type": "object", "required": [ "enterprise", "name", "metric", "conditions", "realert_interval" ], "properties": { "id": { "type": "string", "format": "uuid" }, "enterprise": { "type": "string", "format": "uuid" }, "devices": { "type": "array", "items": { "format": "string" } }, "groups": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string" }, "description": { "type": "string" }, "metric": { "type": "string" }, "conditions": { "properties": { "value": { "type": "number", "format": "double" }, "unit": { "type": "string" }, "comparator": { "type": "string" }, "toggle_state": { "type": "boolean" } } }, "action_emails": { "type": "array", "items": { "type": "string", "format": "email" } }, "actions": { "type": "array", "items": { "type": "string" } }, "alert_channels": { "type": "array", "items": { "type": "string" } }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "realert_interval": { "type": "integer" }, "repeat_times": { "type": "integer" }, "trigger_count": { "type": "integer" }, "daily_trigger_count": { "type": "integer" } } }, "esper_cloud_api_AlarmHistory": { "type": "object", "properties": { "device_name": { "type": "string" }, "device_id": { "type": "string", "format": "uuid" }, "group_id": { "type": "array", "items": { "format": "string" }, "description": "lists group id's in uuid format" }, "group_name": { "type": "string" }, "alert_time": { "type": "string", "format": "date-time" }, "latest_seen": { "type": "string", "format": "date-time" } } }, "esper_cloud_api_Wallpaper": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "enterprise": { "type": "string", "format": "uuid" }, "image_file": { "type": "string", "format": "url" }, "thumbnail": { "type": "string", "format": "url" }, "orientation": { "type": "string" }, "is_active": { "type": "boolean" }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" } } }, "esper_cloud_api_TileIcon": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "category": { "type": "string" }, "icon_file": { "type": "string", "format": "url" }, "device_model": { "type": "string" }, "custom": { "type": "boolean" }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" } } }, "esper_cloud_api_ApplyTileIcon": { "type": "object", "properties": { "icon": { "type": "string", "format": "uuid", "nullable": true }, "apply_mode": { "type": "string", "enum": [ "devices", "all_devices", "groups", "device_model" ], "default": "devices" }, "device_model": { "type": "string", "nullable": true }, "devices": { "type": "array", "items": { "format": "string" } }, "groups": { "type": "array", "items": { "type": "string" } } } }, "esper_cloud_api_DeviceLocations": { "type": "object", "properties": { "id": { "type": "integer" }, "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" }, "altitude": { "type": "number", "format": "double" }, "city": { "type": "string" }, "status": { "type": "string" }, "country": { "type": "string" }, "zipcode": { "type": "integer" }, "last_updated_on": { "type": "string", "format": "date-time" }, "device": { "type": "string", "format": "url" }, "enterprise": { "type": "string", "format": "url" } } }, "esper_cloud_api_SecurityStatesEnum": { "type": "integer", "format": "int32", "description": "Following are the Security States and their description\n\n```\n * 1 = SECURE\n * 10 = LOW_RISK\n * 20 = MEDIUM_RISK\n * 30 = HIGH_RISK\n * 100 = DEVICE_STATE_UNSPECIFIED\n```\n", "enum": [ 1, 10, 20, 30, 100 ] }, "esper_cloud_api_DeviceTiles": { "type": "object", "properties": { "id": { "type": "integer" }, "device": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "url": { "type": "string", "format": "url" } } } }, "device_name": { "type": "string" }, "state": { "type": "integer" }, "tags": { "type": "string", "nullable": true }, "device_type": { "type": "string" }, "serial": { "type": "string" }, "imeis": { "type": "object" }, "android_version": { "type": "integer" }, "eea_version": { "type": "string" }, "manufacturer": { "type": "string" }, "api_level": { "type": "integer" }, "template_name": { "type": "string" }, "dpc_version": { "type": "string" }, "alias_name": { "type": "string" }, "provisioned_on": { "type": "string", "format": "date-time" }, "geofence_id": { "type": "string", "format": "uuid" } } }, "network_info": { "type": "object", "properties": { "__faust": { "type": "object", "properties": { "ns": { "type": "string" } } }, "mobileIPv4": { "type": "string", "nullable": true }, "mobileIPv6": { "type": "string", "nullable": true }, "networkType": { "type": "string", "nullable": true }, "numberOfSim": { "type": "integer" }, "simOperator": { "type": "array", "items": { "type": "string" } }, "signalStrength": { "type": "string", "nullable": true }, "networkOperator": { "type": "array", "items": { "type": "string" } }, "mobileNetworkStatus": { "type": "string" }, "currentActiveConnection": { "type": "string" } } }, "model": { "type": "string" }, "location": { "type": "object", "nullable": true }, "battery_level": { "type": "number", "format": "double" }, "security_state": { "type": "string" }, "security_reason": { "type": "string" }, "security_advise": { "type": "string" }, "wifi_ssid": { "type": "string", "nullable": true }, "updated_on": { "type": "string", "format": "date-time" }, "created_on": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "is_gms": { "type": "boolean" }, "status_id": { "type": "integer", "nullable": true }, "serial_no": { "type": "string" }, "android_version": { "type": "integer" }, "eea_version": { "type": "string" }, "dpc_version": { "type": "string" }, "location_city": { "type": "string" }, "network_type": { "type": "string" }, "enterprise": { "type": "string", "format": "url" }, "icon": { "type": "string", "nullable": true } } }, "esper_cloud_api_StatusMetrics": { "type": "object", "properties": { "active": { "type": "integer" }, "in_active": { "type": "integer" }, "low_risk": { "type": "integer" }, "high_risk": { "type": "integer" }, "medium_risk": { "type": "integer" }, "secure": { "type": "integer" }, "low_battery": { "type": "integer" }, "under_provisioning": { "type": "integer" }, "recently_added": { "type": "integer" }, "unspecified": { "type": "integer" }, "total_devices_under_risk": { "type": "integer" } } }, "esper_cloud_api_DeviceStatusReport": { "type": "object", "properties": { "device_id": { "type": "string", "format": "uuid" }, "device_name": { "type": "string" }, "alias_name": { "type": "string", "nullable": true }, "device_model": { "type": "string" }, "device_brand": { "type": "string" }, "android_version": { "type": "string" }, "serial_number": { "type": "string" }, "is_new": { "type": "boolean" }, "last_known_location": { "type": "string" }, "days_active": { "type": "integer" }, "status": { "type": "string", "description": "choices- ACTIVE / INACTIVE / DISABLED" }, "inactive_since_three_days": { "type": "boolean" } } }, "esper_cloud_api_GroupReport": { "type": "object", "properties": { "group_id": { "type": "string", "format": "uuid" }, "group_name": { "type": "string" }, "group_path": { "type": "string" }, "active_devices": { "type": "integer" }, "inactive_devices": { "type": "integer" }, "registered_devices": { "type": "integer" }, "new_devices": { "type": "integer" }, "disabled_devices": { "type": "integer" } } }, "esper_cloud_api_Subscription": { "type": "object", "properties": { "id": { "type": "integer" }, "email_ids": { "type": "array", "items": { "type": "string", "format": "email" } }, "is_subscribed": { "type": "boolean" }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" } } }, "esper_cloud_api_StatusMetricsV2": { "type": "object", "properties": { "last_seen": { "type": "object", "properties": { "less_than_30_minutes": { "type": "integer" }, "less_than_1_day": { "type": "integer" }, "greater_than_1_day": { "type": "integer" } } }, "low_risk": { "type": "integer" }, "high_risk": { "type": "integer" }, "medium_risk": { "type": "integer" }, "secure": { "type": "integer" }, "low_battery": { "type": "integer" }, "under_provisioning": { "type": "integer" }, "recently_added": { "type": "integer" }, "unspecified": { "type": "integer" }, "total_devices_under_risk": { "type": "integer" } } }, "esper_cloud_api_TokenRenewV0": { "type": "object", "properties": { "id": { "title": "Token id", "type": "string", "description": "Id of the token", "format": "integer", "readOnly": true }, "user": { "title": "User id", "type": "string", "description": "Id of the user resource", "readOnly": true }, "enterprise": { "title": "Enterprise id", "type": "string", "description": "Id of the enterprise resource", "format": "uuid", "readOnly": true }, "token": { "title": "API Token", "type": "string", "description": "API token for accessing esper APIs", "readOnly": true }, "expires_at": { "title": "API token expiry", "type": "string", "description": "Date and time of when your API token will get expired", "format": "date-time", "readOnly": true }, "developerapp": { "title": "Developer app id", "type": "string", "description": "Id of the developer app resource that you created using the esper dev console", "format": "uuid", "readOnly": true }, "scope": { "title": "Scope of API token", "type": "string", "description": "This defines what access scopes your API token has", "readOnly": true }, "created_on": { "title": "Created on", "type": "string", "description": "Date and time of when this resource was created", "format": "date-time", "readOnly": true }, "updated_on": { "title": "Updated on", "type": "string", "description": "Date and time of when this resource was updated", "format": "date-time", "readOnly": true } } }, "esper_cloud_api_V0CommandStatus": { "type": "object", "properties": { "id": { "title": "Id", "type": "string", "description": "Unique command identifier", "format": "uuid", "readOnly": true }, "request": { "title": "Request Id", "type": "string", "description": "Request Id associated with this command", "format": "uuid", "readOnly": true }, "command": { "title": "info about the command", "type": "string" }, "command_args": { "type": "object", "description": "arguments in command" }, "issued_by": { "type": "object", "properties": { "id": { "type": "integer" }, "username": { "type": "string" } } }, "device": { "title": "AndroidDevice", "type": "string", "description": "Device associated with this command", "format": "url", "readOnly": true }, "state": { "type": "string", "description": "Current state of the command", "enum": [ "Command Queued", "Command Initiated", "Command Acknowledged", "Command In Progress", "Command TimeOut", "Command Success", "Command Failure", "Command Scheduled", "Command Cancelled" ] }, "reason": { "type": "string", "description": "details briefing the reason for current command state" }, "requeue_value": { "type": "integer", "description": "indicates the command's requeue count for the device, which is limited to a maximum of 3 retries." }, "created_on": { "title": "Created on", "type": "string", "description": "Timestamp of command creation", "format": "date-time", "readOnly": true }, "updated_on": { "title": "Updated on", "type": "string", "description": "Last updated timestamp of command", "format": "date-time", "readOnly": true } } }, "esper_cloud_api_Geofence": { "required": [ "latitude", "longitude", "name" ], "type": "object", "properties": { "id": { "title": "Geofence id", "type": "string", "description": "id of the geofence", "format": "uuid", "readOnly": true }, "name": { "title": "Geofence name", "type": "string", "description": "Name of the geofence" }, "description": { "title": "Geofence description", "type": "string", "description": "A description about the geofence" }, "enterprise": { "title": "Enterprise id", "type": "string", "description": "id of the enterprise resource", "format": "uuid", "readOnly": true }, "latitude": { "title": "Geofence latitude", "type": "string", "description": "Latitude corresponding to the geofence", "format": "decimal" }, "longitude": { "title": "Geofence longitude", "type": "string", "description": "Longitude corresponding to the geofence", "format": "decimal" }, "radius": { "title": "Geofence radius", "type": "integer", "description": "The radius within which the geofence should be applied" }, "radius_unit": { "title": "Unit of radius", "type": "string", "description": "The unit in which the radius is taken, eg - kilometers, meters etc", "enum": [ "KILOMETERS", "METERS", "MILES" ] }, "device_actions": { "title": "Device Actions", "type": "array", "description": "The actions to be performed on the device", "items": { "type": "string", "enum": [ "LOCK_DOWN", "BEEP" ] } }, "device_count": { "title": "Device count", "type": "integer", "description": "Number of devices", "readOnly": true }, "created_by": { "title": "Created by", "type": "string", "description": "The user who created the geofence", "readOnly": true }, "created_on": { "title": "Creation date and time", "type": "string", "description": "Date and time of when the geofence was created", "format": "date-time", "readOnly": true }, "updated_on": { "title": "Updation date and time", "type": "string", "description": "Date and time of when the geofence was updated", "format": "date-time", "readOnly": true } } }, "esper_cloud_api_GeofenceUpdate": { "type": "object", "properties": { "name": { "title": "Geofence name", "type": "string", "description": "Name of the geofence" }, "description": { "title": "Geofence description", "type": "string", "description": "A description about the geofence" }, "latitude": { "title": "Geofence latitude", "type": "string", "description": "Latitude corresponding to the geofence", "format": "decimal" }, "longitude": { "title": "Geofence longitude", "type": "string", "description": "Longitude corresponding to the geofence", "format": "decimal" }, "radius": { "title": "Geofence radius", "type": "integer", "description": "The radius within which the geofence should be applied" }, "radius_unit": { "title": "Unit of radius", "type": "string", "description": "The unit in which the radius is taken, eg - kilometers, meters etc", "enum": [ "KILOMETERS", "METERS", "MILES" ] }, "device_actions": { "title": "Device Actions", "type": "array", "description": "The actions to be performed on the device", "items": { "type": "string", "enum": [ "LOCK_DOWN", "BEEP" ] } } } }, "esper_cloud_api_GeofenceCreate": { "type": "object", "properties": { "name": { "title": "Geofence name", "type": "string", "description": "Name of the geofence" }, "description": { "title": "Geofence description", "type": "string", "description": "A description about the geofence" }, "latitude": { "title": "Geofence latitude", "type": "string", "description": "Latitude corresponding to the geofence", "format": "decimal" }, "longitude": { "title": "Geofence longitude", "type": "string", "description": "Longitude corresponding to the geofence", "format": "decimal" }, "radius": { "title": "Geofence radius", "type": "integer", "description": "The radius within which the geofence should be applied" }, "radius_unit": { "title": "Unit of radius", "type": "string", "description": "The unit in which the radius is taken, eg - kilometers, meters etc", "enum": [ "KILOMETERS", "METERS", "MILES" ] }, "device_actions": { "title": "Device Actions", "type": "array", "description": "The actions to be performed on the device", "items": { "type": "string", "enum": [ "LOCK_DOWN", "BEEP" ] } }, "devices": { "title": "List of device ids", "type": "array", "description": "List of ids of devices on which the geofence is to be applied", "items": { "type": "string" } } } }, "esper_cloud_api_EnterpriseV1": { "required": [ "id", "name", "short_code" ], "type": "object", "properties": { "id": { "title": "Id", "type": "string", "description": "Id of the enterprise", "format": "uuid", "readOnly": true }, "name": { "title": "Name", "maxLength": 255, "minLength": 1, "type": "string", "description": "Name of the enterprise" }, "short_code": { "title": "Short code", "maxLength": 10, "minLength": 1, "type": "string", "description": "A short 10-char representation of the enterprise, separated by hyphens. Field is optional, as system will auto-generate a value if none is provided.", "readOnly": true }, "registered_name": { "title": "Registered name of the enterprise", "maxLength": 255, "minLength": 1, "type": "string", "description": "Registered Name of the enterprise" }, "registered_address": { "title": "Registered address", "maxLength": 255, "minLength": 1, "type": "string", "description": "Registered address of the enterprise." }, "location": { "title": "Enterprise location", "maxLength": 255, "minLength": 1, "type": "string", "description": "City, State, Country location of the enterprise" }, "zipcode": { "title": "Enterprise zipcode", "maxLength": 8, "minLength": 1, "type": "string", "description": "Zip code of enterprise location" }, "contact_person": { "title": "Contact person", "maxLength": 255, "minLength": 1, "type": "string", "description": "Person who is the point of contact for the enterprise", "nullable": true }, "contact_number": { "title": "Contact number", "maxLength": 20, "minLength": 1, "type": "string", "description": "Contact number of the enterprise", "nullable": true }, "contact_email": { "title": "Contact email", "maxLength": 254, "minLength": 1, "type": "string", "description": "Contact email address of the enterprise", "format": "email" }, "wifi_lte_toggle_flag": { "title": "Enable data saver mode", "type": "boolean", "description": "Will only be available if feature is enabled" }, "emm": { "title": "Google EMM", "type": "object", "properties": { "google_enterprise_id": { "type": "string" } }, "description": "This field will have details about emm enrollment if the enterprise is emm enrolled", "nullable": true, "readOnly": true }, "created_on": { "title": "Created on", "type": "string", "description": "Date and time of when this resource was created", "format": "date-time", "readOnly": true }, "updated_on": { "title": "Updated on", "type": "string", "description": "Date and time of when this resource was updated", "format": "date-time", "readOnly": true } } }, "esper_cloud_api_EnterpriseUpdateV1": { "type": "object", "properties": { "id": { "title": "Id", "type": "string", "description": "Id of the enterprise", "format": "uuid", "readOnly": true }, "name": { "title": "Enterprise Name", "maxLength": 255, "minLength": 1, "type": "string", "description": "Name of the enterprise" }, "registered_name": { "title": "Registered name", "maxLength": 255, "minLength": 1, "type": "string", "description": "Registered Name of the enterprise" }, "registered_address": { "title": "Registered address", "maxLength": 255, "minLength": 1, "type": "string", "description": "Registered address of the enterprise." }, "location": { "title": "Enterprise location", "maxLength": 255, "minLength": 1, "type": "string", "description": "City, State, Country location of the enterprise" }, "zipcode": { "title": "Enterprise zipcode", "maxLength": 8, "minLength": 1, "type": "string", "description": "Description of the enterprise" }, "contact_person": { "title": "Contact person", "maxLength": 255, "minLength": 1, "type": "string", "description": "Person who is the point of contact for the enterprise", "nullable": true }, "contact_number": { "title": "Contact number", "maxLength": 20, "minLength": 1, "type": "string", "description": "Contact number of the enterprise", "nullable": true }, "contact_email": { "title": "Contact email", "maxLength": 254, "minLength": 1, "type": "string", "description": "Contact email address of the enterprise", "format": "email" }, "wifi_lte_toggle_flag": { "title": "Enable data saver mode", "type": "boolean", "description": "Will only be available if feature is enabled" } } }, "esper_cloud_api_ApplicationVersionV1": { "title": "Application Version V1", "type": "object", "properties": { "id": { "title": "Id", "type": "string", "format": "uuid", "readOnly": true }, "version_code": { "title": "Version code", "maxLength": 50, "minLength": 1, "type": "string" }, "build_number": { "title": "Build number", "maxLength": 100, "minLength": 1, "type": "string", "nullable": true }, "hash_string": { "title": "Hash string", "type": "string" }, "min_sdk_version": { "title": "Min sdk version", "maxLength": 10, "minLength": 1, "type": "string", "nullable": true }, "target_sdk_version": { "title": "Target sdk version", "maxLength": 10, "minLength": 1, "type": "string", "nullable": true }, "icon_url": { "title": "Url for the icon", "type": "string", "format": "url" }, "release_name": { "title": "Name of the release", "type": "string" } } }, "esper_cloud_api_ApplicationV1": { "required": [ "application_name", "enterprise", "package_name" ], "type": "object", "properties": { "id": { "title": "Id", "type": "string", "format": "uuid", "readOnly": true }, "latest_version": { "$ref": "#/components/schemas/esper_cloud_api_ApplicationVersionV1" }, "application_name": { "title": "Application name", "maxLength": 255, "minLength": 1, "type": "string" }, "package_name": { "title": "Package name", "maxLength": 255, "minLength": 1, "type": "string", "readOnly": true }, "is_hidden": { "title": "Is hidden", "type": "boolean" }, "enterprise": { "title": "Enterprise", "type": "string", "format": "url" } } }, "esper_cloud_api_AppVersionV1": { "title": "Application Version V1", "required": [ "enterprise", "version_code" ], "type": "object", "properties": { "id": { "title": "Id", "type": "string", "format": "uuid", "readOnly": true }, "installed_count": { "title": "Installed count", "type": "integer", "readOnly": true }, "is_g_play": { "title": "Is google play", "type": "boolean" }, "app_file": { "title": "App file url", "type": "string", "format": "url", "nullable": true }, "app_icon": { "title": "App icon url", "type": "string", "format": "url", "nullable": true }, "version_code": { "title": "Version code", "maxLength": 50, "minLength": 1, "type": "string", "nullable": true }, "build_number": { "title": "Build number", "maxLength": 100, "minLength": 1, "type": "string", "nullable": true }, "min_sdk_version": { "title": "Minimum sdk version", "maxLength": 10, "minLength": 1, "type": "string", "nullable": true }, "enterprise": { "title": "Enterprise URL", "type": "string", "format": "url" }, "application": { "title": "Application URL", "type": "string", "format": "url" }, "release_name": { "title": "Name of the release", "maxLength": 255, "type": "string", "nullable": true }, "release_comments": { "title": "Release comments", "type": "string", "nullable": true }, "approval_status": { "title": "Approval Status", "maxLength": 50, "type": "string", "default": "APPROVED", "enum": [ "AVAILABLE", "ACCEPTED", "APPROVED", "REJECTED" ] }, "release_date": { "title": "Release date", "type": "string", "format": "date-time" }, "size_in_mb": { "title": "Size in mb", "type": "number" }, "is_default": { "title": "Is default", "type": "boolean", "default": false }, "created_on": { "title": "Created on", "type": "string", "format": "date-time", "readOnly": true } } }, "esper_cloud_api_TokenInfoV1": { "required": [ "enterprise", "id" ], "type": "object", "properties": { "id": { "title": "Id", "type": "string", "description": "Token id", "format": "integer", "readOnly": true }, "enterprise": { "title": "Enterprise id", "type": "string", "description": "Id of the enterprise resource", "format": "uuid", "readOnly": true }, "user": { "title": "User id", "type": "string", "description": "Id of the user resource", "readOnly": true }, "developer_app": { "title": "Developer app id", "type": "string", "description": "Id of the developer app resource that you created using the esper dev console", "format": "uuid", "readOnly": true }, "source_refresh_token": { "title": "Refresh token", "type": "string", "description": "The refresh token is used to refresh your expired API token", "readOnly": true }, "token": { "title": "API Token", "type": "string", "description": "API token for accessing esper APIs", "readOnly": true }, "expires_on": { "title": "API token expiry", "type": "string", "description": "Date and time of when your API token will get expired", "format": "date-time", "readOnly": true }, "scope": { "title": "Scope of API token", "type": "array", "description": "This defines what access scopes does your API token has", "readOnly": true, "items": { "type": "string" } }, "created_on": { "title": "Created on", "type": "string", "description": "Date and time of when this resource was created", "format": "date-time", "readOnly": true }, "updated_on": { "title": "Updated on", "type": "string", "description": "Date and time of when this resource was updated", "format": "date-time", "readOnly": true } } }, "esper_cloud_api_Group": { "type": "object", "properties": { "id": { "title": "ID", "type": "string", "format": "uuid" }, "name": { "title": "Group Name", "type": "string" }, "path": { "title": "Group Path", "type": "string" }, "device_count": { "type": "integer" } } }, "esper_cloud_api_UserProfile": { "title": "UserProfileInfo", "type": "object", "properties": { "id": { "title": "ID", "type": "integer" }, "enterprise_user_id": { "title": "Enterprise User ID", "type": "string" }, "authn_user_id": { "title": "AuthN User ID", "type": "string", "format": "uuid" }, "authn_connection_id": { "title": "AuthN Connection ID", "type": "string", "format": "uuid" }, "authz_role_id": { "title": "AuthZ Role ID", "type": "string", "format": "uuid" }, "role": { "title": "Role", "type": "string", "enum": [ "Shoonya Admin", "Enterprise Admin", "Enterprise User", "Viewer", "Group Admin", "Group Viewer" ] }, "enterprise": { "title": "Enterprise ID", "type": "string", "format": "uuid" }, "is_customer": { "title": "Is Customer", "type": "boolean" }, "is_endpoint_creator": { "title": "Is Endpoint Creator", "type": "boolean" }, "created_on": { "title": "Created On", "type": "string", "format": "date-time" }, "updated_on": { "title": "Updated On", "type": "string", "format": "date-time" }, "setup_wizard_complete": { "title": "Setup Wizard Complete", "type": "boolean" }, "default_password_changed": { "title": "Default Password Changed", "type": "boolean" }, "is_developer": { "title": "Is Developer", "type": "boolean" }, "can_factory_reset": { "title": "Can Factory Reset", "type": "boolean" }, "groups": { "title": "Groups", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/esper_cloud_api_Group" } } } }, "esper_cloud_api_AuthenticationToken": { "title": "AuthenticationToken", "type": "object", "properties": { "id": { "title": "ID", "type": "integer" }, "token": { "title": "Token", "type": "string" }, "is_active": { "title": "Is Active", "type": "boolean" }, "updated_on": { "title": "Updated On", "type": "string", "format": "date-time" } } }, "esper_cloud_api_EMM": { "title": "UserEMM", "type": "object", "properties": { "id": { "title": "ID", "type": "integer" }, "user": { "title": "User ID", "type": "integer" }, "account_identifier": { "title": "Account Identifier", "type": "string" }, "account_type": { "title": "Account Type", "type": "string" }, "display_name": { "title": "Display Name", "type": "string" }, "google_user_id": { "title": "Google User ID", "type": "string" }, "google_enterprise": { "title": "Google Enterprise", "type": "integer" }, "is_active": { "title": "Is Active", "type": "boolean" }, "created_on": { "title": "Created On", "type": "string", "format": "date-time" }, "updated_on": { "title": "Updated On", "type": "string", "format": "date-time" }, "authentication_token": { "title": "Authentication Token", "type": "object", "$ref": "#/components/schemas/esper_cloud_api_AuthenticationToken", "readOnly": true } } }, "esper_cloud_api_User": { "title": "UserInfo", "type": "object", "properties": { "id": { "title": "ID", "type": "integer" }, "username": { "title": "User name", "type": "string" }, "email": { "title": "Email", "type": "string", "format": "email" }, "first_name": { "title": "First name", "type": "string" }, "last_name": { "title": "Last name", "type": "string" }, "full_name": { "title": "Last name", "type": "string" }, "is_staff": { "type": "boolean", "readOnly": true }, "is_superuser": { "type": "boolean", "readOnly": true }, "is_active": { "title": "Is user active", "type": "boolean" }, "profile": { "title": "User Profile", "type": "object", "$ref": "#/components/schemas/esper_cloud_api_UserProfile" }, "emm": { "title": "EMM details", "type": "object", "$ref": "#/components/schemas/esper_cloud_api_EMM", "readOnly": true }, "last_login": { "title": "Last login", "type": "string" }, "token": { "title": "Token", "type": "string" }, "has_emm": { "title": "Has EMM", "type": "boolean" }, "is_email_verified": { "title": "Is Email Verified", "type": "boolean" } } }, "esper_cloud_api_TenantUserInviteResponse": { "title": "TenantUserInviteResponse", "type": "object", "properties": { "id": { "title": "id", "type": "string" }, "email": { "title": "email", "type": "string", "format": "email" }, "tenant_id": { "title": "id of the tenant", "type": "string" }, "idp_invite_id": { "title": "id of the idp invitation", "type": "string" }, "meta": { "title": "meta data of user", "type": "object" }, "connection_id": { "title": "connection id", "type": "string" }, "send_invitation_email": { "title": "send invitation email", "type": "boolean" }, "created_at": { "title": "created at", "type": "string", "format": "date-time" }, "updated_at": { "title": "updated at", "type": "string", "format": "date-time" } } }, "esper_cloud_api_GenericErrorResponse": { "type": "object", "properties": { "status": { "type": "integer", "format": "int32", "description": "Either 'status' or 'code' will be present, but not both." }, "code": { "type": "integer", "format": "int32", "description": "Either 'status' or 'code' will be present, but not both." }, "error": { "type": "string", "description": "Either 'error' or 'errors' will be present, but not both." }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Either 'error' or 'errors' will be present, but not both." }, "message": { "title": "Message describing the error", "type": "string" } } }, "esper_cloud_api_TenantUserInviteMeta": { "title": "TenantUserInviteMeta", "type": "object", "properties": { "email": { "title": "email", "type": "string", "format": "email" }, "profile": { "title": "profile details", "type": "object", "properties": { "role": { "title": "role", "type": "string", "enum": [ "Enterprise Admin", "Viewer", "Group Admin", "Group Viewer", "Support", "AuthZ Role User" ] }, "enterprise": { "title": "tenant id", "type": "string", "format": "uuid" }, "groups": { "title": "groups associated. required only if role is Group Admin or Group Viewer or AuthZ User Role", "type": "array", "items": { "type": "string", "format": "uuid" } }, "authz_role_id": { "title": "custom role id. required only if role is AuthZ Role User", "type": "string", "format": "uuid" } }, "required": [ "role", "enterprise" ] } }, "required": [ "email", "profile" ] }, "esper_cloud_api_TenantUserInviteRequest": { "title": "TenantUserInviteRequest", "type": "object", "properties": { "email": { "title": "email", "type": "string", "format": "email" }, "meta": { "title": "meta data of user", "type": "object", "$ref": "#/components/schemas/esper_cloud_api_TenantUserInviteMeta" }, "connection_id": { "title": "connection id", "type": "string" } }, "required": [ "email", "meta" ] }, "esper_cloud_api_TenantUserInviteCreateResponse": { "title": "TenantUserInviteResponse", "type": "object", "properties": { "id": { "title": "id", "type": "string" }, "email": { "title": "email", "type": "string", "format": "email" }, "tenant_id": { "title": "id of the tenant", "type": "string" }, "idp_invite_id": { "title": "id of the idp invitation", "type": "string" }, "meta": { "title": "meta data of user", "type": "object" }, "connection_id": { "title": "connection id", "type": "string" }, "send_invitation_email": { "title": "send invitation email", "type": "boolean" }, "invitation_url": { "title": "invitation URL", "type": "string" }, "created_at": { "title": "created at", "type": "string", "format": "date-time" }, "updated_at": { "title": "updated at", "type": "string", "format": "date-time" } } }, "esper_cloud_api_UserList": { "title": "User", "type": "object", "properties": { "id": { "title": "ID", "type": "integer" }, "username": { "title": "User name", "type": "string" }, "email": { "title": "Email", "type": "string", "format": "email" }, "first_name": { "title": "First name", "type": "string" }, "last_name": { "title": "Last name", "type": "string" }, "full_name": { "title": "Last name", "type": "string" }, "is_staff": { "type": "boolean", "readOnly": true }, "is_superuser": { "type": "boolean", "readOnly": true }, "is_active": { "title": "Is user active", "type": "boolean" }, "profile": { "title": "User Profile", "type": "object", "$ref": "#/components/schemas/esper_cloud_api_UserProfile" }, "emm": { "title": "EMM details", "type": "object", "$ref": "#/components/schemas/esper_cloud_api_EMM", "readOnly": true }, "last_login": { "title": "Last login", "type": "string" }, "token": { "title": "Token", "type": "string" }, "has_emm": { "title": "Has EMM", "type": "boolean" } } }, "esper_cloud_api_UserProfileCreate": { "title": "UserProfile", "type": "object", "properties": { "role": { "title": "Role", "type": "string", "enum": [ "Shoonya Admin", "Enterprise Admin", "Enterprise User", "Viewer", "Group Admin", "Group Viewer" ] }, "groups": { "title": "Groups", "type": "array", "items": { "type": "string" } }, "enterprise": { "title": "Enterprise ID", "type": "string", "format": "uuid" }, "is_customer": { "title": "Is Customer", "type": "boolean" }, "is_endpoint_creator": { "title": "Is Endpoint Creator", "type": "boolean" }, "setup_wizard_complete": { "title": "Setup Wizard Complete", "type": "boolean" }, "default_password_changed": { "title": "Default Password Changed", "type": "boolean" }, "is_developer": { "title": "Is Developer", "type": "boolean" }, "can_factory_reset": { "title": "Can Factory Reset", "type": "boolean" } } }, "esper_cloud_api_UserCreate": { "required": [ "username", "profile" ], "title": "UserCreate", "type": "object", "properties": { "username": { "title": "User name", "type": "string" }, "password": { "title": "Password", "type": "string" }, "first_name": { "title": "First name", "type": "string" }, "last_name": { "title": "Last name", "type": "string" }, "is_active": { "title": "Is user active", "type": "boolean" }, "email": { "title": "Email", "type": "string", "format": "email" }, "profile": { "title": "User Profile", "type": "object", "$ref": "#/components/schemas/esper_cloud_api_UserProfileCreate" } } }, "esper_cloud_api_UserUpdate": { "title": "UserUpdation", "type": "object", "properties": { "username": { "title": "User name", "type": "string" }, "password": { "title": "Password", "type": "string" }, "first_name": { "title": "First name", "type": "string" }, "last_name": { "title": "Last name", "type": "string" }, "is_active": { "title": "Is user active", "type": "boolean" }, "email": { "title": "Email", "type": "string", "format": "email" }, "profile": { "title": "User Profile", "type": "object", "$ref": "#/components/schemas/esper_cloud_api_UserProfileCreate" } } }, "esper_cloud_api_UpdateDifferentUserRequest": { "type": "object", "properties": { "authz_role_id": { "title": "Custom role id. Required only if role is AuthZ Role User", "type": "string", "format": "uuid" }, "can_factory_reset": { "title": "If user should be able to factory reset or not", "type": "boolean" }, "has_all_group_access": { "title": "If user has access to all groups or not. Required only if role is AuthZ Role User", "type": "boolean" }, "groups": { "title": "List of group IDs. Can be empty if has_all_group_access is True or if the user role is not Group Admin/Group Viewer", "type": "array", "items": { "type": "string" } }, "role": { "title": "Role. Role should be AuthZ Role User for custom role", "type": "string", "enum": [ "Shoonya Admin", "Enterprise Admin", "Enterprise User", "Viewer", "Group Admin", "Group Viewer", "AuthZ Role User" ] } }, "required": [ "role", "groups" ] }, "esper_cloud_api_UpdateOwnUserRequest": { "type": "object", "properties": { "first_name": { "title": "first name", "type": "string" } }, "required": [ "first_name" ] }, "esper_cloud_api_UserGroups": { "type": "object", "properties": { "group_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "has_all_group_access": { "type": "boolean" } } }, "esper_cloud_api_ConnectivitySection": { "title": "Connectivity", "type": "object", "properties": { "sms_disabled": { "type": "boolean" }, "enable_bluetooth": { "type": "boolean" }, "wifi_state": { "type": "boolean" }, "nfc_beam_disabled": { "type": "boolean" }, "ethernet_settings": { "type": "object", "description": "Ethernet settings to configure ethernet certificate", "required": [ "ethernet_auth_mode" ], "properties": { "ethernet_auth_mode": { "type": "string", "description": "Auth Mode options\n```\n* EAP_TLS: Ethernet auth mode is EAP_TLS\n* NONE: Default Value, if NONE then other fields are option\n```\n", "enum": [ "EAP_TLS", "NONE" ] }, "ethernet_ca_cert_alias": { "type": "string", "description": "It is mandatory field if Auth Mode is “EAP_TLS”." }, "ethernet_client_cert_alias": { "type": "string", "description": "It is mandatory field if Auth Mode is “EAP_TLS”." }, "ethernet_eap_identity": { "type": "string", "description": "It is mandatory field if Auth Mode is “EAP_TLS”." } } }, "wifi_settings": { "type": "array", "items": { "type": "object", "properties": { "wifi_ssid": { "type": "string" }, "wifi_password": { "type": "string" }, "wifi_security_type": { "type": "string", "enum": [ "NONE", "WAP", "WEP", "EAP", "WPA2", "SAE" ] }, "wifi_phase2_auth": { "type": "string", "enum": [ "NONE", "PAP", "MSCHAP", "MSCHAPV2", "GTC", "SIM", "AKA", "AKA_PRIME" ] }, "wifi_eap_method": { "type": "string", "enum": [ "PEAP", "TLS", "TTLS", "PWD", "NONE", "SIM", "AKA", "AKA_PRIME" ] }, "identity": { "type": "string" }, "anonymous_identity": { "type": "string" }, "domain": { "type": "string" }, "hidden": { "type": "boolean" } } } }, "incoming_numbers_with_tags": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } } }, "outgoing_numbers_with_tags": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } } }, "section_type": { "title": "Type", "type": "string", "enum": [ "Inherited", "Independent" ] }, "locked": { "title": "Locked", "description": "Locked", "type": "boolean" } } }, "esper_cloud_api_SoundSection": { "title": "Sound", "type": "object", "properties": { "alarm_volume": { "type": "integer" }, "notification_volume": { "type": "integer" }, "music_volume": { "type": "integer" }, "ring_volume": { "type": "integer" }, "section_type": { "title": "Type", "type": "string", "enum": [ "Inherited", "Independent" ] }, "locked": { "title": "Locked", "description": "Locked", "type": "boolean" } } }, "esper_cloud_api_DisplayBrandingSection": { "title": "Display", "type": "object", "properties": { "screenshot_disabled": { "type": "boolean" }, "status_bar_disabled": { "type": "boolean" }, "rotation_state": { "type": "string", "enum": [ "AUTO", "LANDSCAPE_ONLY", "POTRAIT_ONLY", "INVERTED_PORTRAIT_ONLY", "INVERTED_LANDSCAPE_ONLY" ] }, "brightness_scale": { "type": "integer" }, "wallpapers": { "type": "array", "items": { "type": "object", "properties": { "wallpaper": { "type": "string", "format": "uuid" }, "wallpaper_url": { "type": "string", "readOnly": true }, "thumbnail_url": { "type": "string", "readOnly": true }, "orientation": { "type": "string" }, "screen_types": { "type": "array", "items": { "type": "string", "enum": [ "LOCKSCREEN", "HOMESCREEN" ] } }, "orientations": { "type": "array", "items": { "type": "string", "enum": [ "PORTRAIT", "LANDSCAPE" ] } } } } }, "section_type": { "title": "Type", "type": "string", "enum": [ "Inherited", "Independent" ] }, "locked": { "title": "Locked", "description": "Locked", "type": "boolean" } } }, "esper_cloud_api_HardwareSettingsSection": { "title": "Hardware", "type": "object", "properties": { "gps_state": { "type": "string", "enum": [ "LOCATION_MODE_HIGH_ACCURACY", "LOCATION_MODE_SENSORS_ONLY", "LOCATION_MODE_BATTERY_SAVING", "LOCATION_MODE_OFF", "LOCATION_MODE_ON" ] }, "usb_file_transfer_disabled": { "type": "boolean" }, "tethering_disabled": { "type": "boolean" }, "camera_disabled": { "type": "boolean" }, "usb_connectivity_disabled": { "type": "boolean" }, "section_type": { "title": "Type", "type": "string", "enum": [ "Inherited", "Independent" ] }, "locked": { "title": "Locked", "description": "Locked", "type": "boolean" } } }, "esper_cloud_api_DateTimeSection": { "title": "Date Time", "type": "object", "properties": { "timezone_string": { "type": "string" }, "device_locale": { "type": "string" }, "date_time_config_disabled": { "type": "boolean" }, "section_type": { "title": "Type", "type": "string", "enum": [ "Inherited", "Independent" ] }, "locked": { "title": "Locked", "description": "Locked", "type": "boolean" } } }, "esper_cloud_api_SettingsAppSection": { "title": "Settings App", "type": "object", "properties": { "enable_android_settings_app": { "type": "boolean" }, "settings_access_level": { "type": "string", "enum": [ "NONE", "SHOONYA", "SYSTEM" ] }, "esper_settings_app": { "type": "object", "properties": { "only_dock_accessible": { "type": "boolean" }, "admin_mode_password": { "type": "string" }, "esper_settings_app_policy": { "type": "object", "properties": { "flashlight": { "type": "string" }, "wifi": { "type": "string" }, "auto_rotation": { "type": "string" }, "reboot": { "type": "string" }, "kiosk_app_selection": { "type": "string" }, "esper_branding": { "type": "string" }, "factory_reset": { "type": "string" }, "about": { "type": "string" }, "display": { "type": "string" }, "sound": { "type": "string" }, "keyboard": { "type": "string" }, "input_selection": { "type": "string" }, "accessibility": { "type": "string" }, "mobile_data": { "type": "string" }, "bluetooth": { "type": "string" }, "language": { "type": "string" }, "time_and_date": { "type": "string" }, "clear_app_data": { "type": "string" }, "storage": { "type": "string" }, "data_roaming": { "type": "string" }, "wifi_tethering": { "type": "string" }, "airplane_mode": { "type": "string" }, "accessibility_reset_to_default": { "type": "string" }, "accessibility_high_contrast_text": { "type": "string" }, "accessibility_cc_deuteranomaly": { "type": "string" }, "accessibility_cc_protanomaly": { "type": "string" }, "accessibility_cc_tritanomaly": { "type": "string" }, "accessibility_mono_audio": { "type": "string" }, "accessibility_display_size": { "type": "string" }, "accessibility_talkback": { "type": "string" }, "accessibility_text_to_speech": { "type": "string" } } } } }, "config_json": { "type": "object" }, "section_type": { "title": "Type", "type": "string", "enum": [ "Inherited", "Independent" ] }, "locked": { "title": "Locked", "description": "Locked", "type": "boolean" } } }, "esper_cloud_api_SystemUpdatesSection": { "title": "System Updates", "type": "object", "properties": { "locked": { "title": "Locked", "description": "Locked", "type": "boolean" }, "section_type": { "title": "Type", "type": "string", "enum": [ "Inherited", "Independent" ] }, "type": { "title": "Type", "description": "Type", "type": "string", "enum": [ "TYPE_POSTPONE", "TYPE_INSTALL_AUTOMATIC", "TYPE_INSTALL_WINDOWED", "TYPE_INSTALL_DISABLED" ] }, "maintenance_start": { "type": "integer" }, "maintenance_end": { "type": "integer" } } }, "esper_cloud_api_GoogleServicesSection": { "title": "Google Services", "type": "object", "properties": { "disable_play_store": { "type": "boolean" }, "google_assistant_disabled": { "type": "boolean" }, "managed_google_play_disabled": { "type": "boolean" }, "max_account": { "type": "integer" }, "emails": { "type": "array", "items": { "type": "string" } }, "domains": { "type": "array", "items": { "type": "string" } }, "frp_googles": { "type": "array", "items": { "type": "object", "properties": { "google_id": { "type": "string" }, "email": { "type": "string" }, "type": { "type": "string", "enum": [ "USER", "ADMIN" ] } } } }, "section_type": { "title": "Type", "type": "string", "enum": [ "Inherited", "Independent" ] }, "locked": { "title": "Locked", "description": "Locked", "type": "boolean" } } }, "esper_cloud_api_SecuritySection": { "title": "Security", "type": "object", "properties": { "password_quality": { "type": "string", "enum": [ "PASSWORD_QUALITY_ALPHABETIC", "PASSWORD_QUALITY_ALPHANUMERIC", "PASSWORD_QUALITY_UNSPECIFIED", "PASSWORD_QUALITY_COMPLEX", "PASSWORD_QUALITY_BIOMETRIC_WEAK", "PASSWORD_QUALITY_NUMERIC" ] }, "minimum_password_length": { "type": "integer" }, "adb_disabled": { "type": "boolean" }, "safe_boot_disabled": { "type": "boolean" }, "screen_off_timeout": { "type": "integer" }, "factory_reset_disabled": { "type": "boolean" }, "keyguard_disabled": { "type": "boolean" }, "section_type": { "title": "Type", "type": "string", "enum": [ "Inherited", "Independent" ] }, "locked": { "title": "Locked", "description": "Locked", "type": "boolean" } } }, "esper_cloud_api_ApplicationSection": { "title": "Application", "type": "object", "properties": { "app_mode": { "type": "string", "enum": [ "KIOSK", "MULTI_APP" ] }, "launch_on_start": { "type": "string" }, "start_on_boot": { "type": "string", "nullable": true }, "launcher_less_dpc": { "type": "boolean" }, "disable_local_app_install": { "type": "boolean" }, "app_uninstall_disabled": { "type": "boolean" }, "permission_policy": { "type": "string", "enum": [ "PERMISSION_POLICY_AUTO_GRANT", "PERMISSION_POLICY_PROMPT", "PERMISSION_POLICY_AUTO_DENY" ] }, "locked": { "title": "Locked", "description": "Locked", "type": "boolean" }, "preload_apps": { "type": "array", "items": { "type": "object", "properties": { "package_name": { "type": "string" }, "state": { "type": "string", "enum": [ "SHOW", "HIDE", "DISABLED", "LAUNCHABLE_BUT_HIDDEN" ] } } } }, "apps": { "type": "array", "items": { "type": "object", "properties": { "version_codes": { "type": "array", "items": { "type": "string" }, "readOnly": true }, "is_g_play": { "type": "boolean", "readOnly": true }, "app_version": { "type": "string", "format": "uuid" }, "app_version_url": { "type": "string", "readOnly": true }, "hash_string": { "type": "string", "readOnly": true }, "package_name": { "type": "string", "readOnly": true }, "download_url": { "type": "string", "readOnly": true }, "installation_rule": { "type": "string", "enum": [ "DURING", "POST" ] }, "state": { "type": "string", "enum": [ "SHOW", "HIDE", "DISABLED", "LAUNCHABLE_BUT_HIDDEN" ] }, "managed_config": { "type": "object" } } } }, "section_type": { "title": "Type", "type": "string", "enum": [ "Inherited", "Independent" ] } } }, "esper_cloud_api_ContentSection": { "title": "Content", "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "file": { "type": "integer" }, "file_url": { "type": "string", "readOnly": true }, "hash": { "type": "string", "readOnly": true }, "url": { "type": "string", "readOnly": true }, "destination_path": { "type": "string" } } } }, "section_type": { "title": "Type", "type": "string", "enum": [ "Inherited", "Independent" ] }, "locked": { "type": "boolean" } } }, "esper_cloud_api_BlueprintRevision": { "title": "Blueprint", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "revision": { "type": "string", "readOnly": true }, "created_by": { "type": "string", "readOnly": true }, "current": { "type": "boolean", "readOnly": true }, "type": { "type": "string", "enum": [ "Independent", "Inherited" ] }, "comments": { "type": "string" }, "locked": { "type": "boolean" }, "connectivity": { "$ref": "#/components/schemas/esper_cloud_api_ConnectivitySection" }, "sound": { "$ref": "#/components/schemas/esper_cloud_api_SoundSection" }, "display_branding": { "$ref": "#/components/schemas/esper_cloud_api_DisplayBrandingSection" }, "hardware_settings": { "$ref": "#/components/schemas/esper_cloud_api_HardwareSettingsSection" }, "date_time": { "$ref": "#/components/schemas/esper_cloud_api_DateTimeSection" }, "settings_app": { "$ref": "#/components/schemas/esper_cloud_api_SettingsAppSection" }, "system_updates": { "$ref": "#/components/schemas/esper_cloud_api_SystemUpdatesSection" }, "google_services": { "$ref": "#/components/schemas/esper_cloud_api_GoogleServicesSection" }, "security": { "$ref": "#/components/schemas/esper_cloud_api_SecuritySection" }, "application": { "$ref": "#/components/schemas/esper_cloud_api_ApplicationSection" }, "content": { "$ref": "#/components/schemas/esper_cloud_api_ContentSection" }, "created_on": { "title": "Created on", "description": "Date and time of when the group was created", "type": "string", "format": "date-time", "readOnly": true } } }, "esper_cloud_api_Blueprint": { "title": "Blueprint", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string" }, "description": { "type": "string" }, "locked": { "type": "boolean" }, "group": { "type": "string", "format": "uuid" }, "latest_revision": { "$ref": "#/components/schemas/esper_cloud_api_BlueprintRevision" }, "created_on": { "type": "string", "format": "date-time", "readOnly": true }, "updated_on": { "type": "string", "format": "date-time", "readOnly": true } } }, "esper_cloud_api_UniqueIdentifier": { "title": "UniqueIdentifier", "type": "object", "properties": { "unique_id": { "title": "Unique identifier", "type": "string" }, "type": { "title": "Unique identifier type", "type": "string", "enum": [ "IMEI1", "IMEI2", "SERIAL", "MEI", "WIFI_MAC_ID", "ETHERNET_MAC_ID" ] } } }, "esper_cloud_api_DirectoryRecord": { "title": "DirectoryRecord", "type": "object", "properties": { "id": { "title": "Directory Record ID", "type": "string" }, "name": { "title": "Device name", "type": "string" }, "online_status": { "type": "string", "enum": [ "ONLINE", "OFFLINE", "NONE" ] }, "alias": { "title": "Alias name", "type": "string" }, "tags": { "title": "Tags", "type": "array", "items": { "type": "string" } }, "group_id": { "title": "Group ID", "type": "string", "format": "uuid" }, "device_id": { "title": "Device ID", "type": "string", "format": "uuid" }, "approval_status": { "title": "Approval Status", "type": "string", "enum": [ "WAITING_FOR_APPROVAL", "APPROVED", "REJECTED", "BLOCKED" ] }, "provisioned_on": { "title": "Provisioned on", "type": "string", "format": "date-time", "readOnly": true }, "unique_identifiers": { "title": "Unique Identifiers", "type": "array", "items": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/esper_cloud_api_UniqueIdentifier" } ] } } } }, "esper_cloud_api_UniqueIdentifierCreate": { "title": "UniqueIdentifierCreate", "type": "object", "properties": { "unique_id": { "title": "Unique identifier", "type": "string" }, "type": { "title": "Unique identifier type", "type": "integer", "enum": [ 0, 1, 2, 3, 4, 5 ], "description": "Following are the valid Unique Identifier Types:\n\n```\nIMEI1 = 0\nIMEI2 = 1\nSERIAL = 2\nMEI = 3\nWIFI_MAC_ID = 4\nETHERNET_MAC_ID = 5\n```\n" } } }, "esper_cloud_api_DirectoryRecordCreate": { "title": "DirectoryRecordCreate", "type": "object", "properties": { "unique_identifiers": { "title": "Unique Identifiers", "type": "array", "items": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/esper_cloud_api_UniqueIdentifierCreate" } ] } }, "group_id": { "title": "Group ID", "type": "string", "format": "uuid" }, "alias": { "title": "Alias name", "type": "string" }, "tags": { "title": "Tags", "type": "array", "items": { "type": "string" } } } }, "esper_cloud_api_DirectoryRecordUpdate": { "title": "DirectoryRecordUpdate", "type": "object", "properties": { "unique_identifiers": { "title": "Unique Identifiers", "type": "array", "items": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/esper_cloud_api_UniqueIdentifierCreate" } ] } }, "group_id": { "title": "Group ID", "type": "string", "format": "uuid" }, "alias": { "title": "Alias name", "type": "string" }, "tags": { "title": "Tags", "type": "array", "items": { "type": "string" } } } }, "esper_cloud_api_CustomConnectionList": { "title": "CustomConnectionList", "type": "object", "properties": { "name": { "title": "name", "type": "string" }, "strategy": { "title": "strategy", "enum": [ "samlp", "oidc" ], "description": "Strategy:\n * `samlp` - SAML connection\n * `oidc` - OIDC connection\n" }, "is_default": { "title": "is default", "type": "boolean" } } }, "esper_cloud_api_CustomConnectionsListResponse": { "title": "CustomConnectionsListResponse", "type": "object", "properties": { "connection_id": { "title": "connection id", "type": "string" }, "connection": { "type": "object", "$ref": "#/components/schemas/esper_cloud_api_CustomConnectionList" } } }, "esper_cloud_api_CustomConnectionConfigResponse": { "title": "CustomConnectionConfigResponse", "type": "object", "properties": { "sign_in_url": { "title": "Sign in url", "type": "string", "format": "url", "description": "Required for SAML connection" }, "disable_sign_out": { "title": "Disable sign out", "type": "boolean" }, "sign_out_url": { "title": "Sign out url", "type": "string", "format": "url" }, "x509_certificate": { "title": "x509 certificate", "type": "string", "description": "Required for SAML connection" }, "issuer_url": { "title": "Issuer url", "type": "string", "format": "url", "description": "Required for OIDC connection" }, "client_id": { "title": "client id", "type": "string", "description": "Required for OIDC connection" } } }, "esper_cloud_api_CustomConnectionRequest": { "title": "CustomConnectionRequest", "type": "object", "properties": { "display_name": { "title": "display name", "type": "string" }, "strategy": { "title": "strategy", "enum": [ "samlp", "oidc" ], "description": "Strategy:\n * `samlp` - SAML connection\n * `oidc` - OIDC connection\n" }, "config": { "type": "object", "$ref": "#/components/schemas/esper_cloud_api_CustomConnectionConfigResponse" } } }, "esper_cloud_api_CustomConnectionResponse": { "title": "CustomConnectionResponse", "type": "object", "properties": { "id": { "title": "id", "type": "string" }, "name": { "title": "name", "type": "string" }, "display_name": { "title": "display name", "type": "string" }, "strategy": { "title": "strategy", "enum": [ "samlp", "oidc" ], "description": "Strategy:\n * `samlp` - SAML connection\n * `oidc` - OIDC connection\n" }, "service_provider_acs_url": { "title": "service provider ACS url", "type": "string", "format": "url" }, "service_provider_entity_id": { "title": "service provider entity id", "type": "string" }, "service_provider_logout_url": { "title": "service provider logout url", "type": "string" }, "signing_certificate_link": { "title": "signing certificate link", "type": "string" }, "callback_url": { "title": "callback url", "type": "string", "format": "url" }, "config": { "type": "object", "$ref": "#/components/schemas/esper_cloud_api_CustomConnectionConfigResponse" } } }, "esper_cloud_api_RoleResponse": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "role_type": { "type": "integer" } } }, "esper_cloud_api_Role": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } }, "esper_cloud_api_ScopeResponse": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "scope_type": { "type": "integer" } } }, "esper_cloud_api_PersonalAccessTokenGetResponse": { "title": "PersonalAccessTokenGetResponse", "type": "object", "properties": { "count": { "type": "integer" }, "personal_access_tokens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier of the token." }, "name": { "type": "string", "description": "The name of the token." }, "description": { "type": "string", "description": "A description of the token." }, "created_at": { "type": "string", "format": "timestamp", "description": "Timestamp indicating when the token was created." }, "updated_at": { "type": "string", "format": "timestamp", "description": "Timestamp indicating when the token was updated." }, "prefix": { "type": "string", "description": "The token prefix." }, "token": { "type": "string", "description": "The token value." }, "expiry_at": { "type": "integer", "description": "exipy date for token, -1 indicates no expiry." }, "legacy_token_id": { "type": "integer", "description": "token id corresponding to legacy system" }, "legacy_developer_app_id": { "type": "string", "description": "developer app id corresponding to legacy system" } } } } } }, "esper_cloud_api_PersonalAccessTokenCreateResponse": { "title": "PersonalAccessTokenCreateResponse", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID for the generated token." }, "name": { "type": "string", "description": "Name for the token." }, "description": { "type": "string", "description": "Description for the token." }, "created_at": { "type": "string", "format": "timestamp", "description": "Timestamp indicating when the token was created." }, "updated_at": { "type": "string", "format": "timestamp", "description": "Timestamp indicating when the token was last updated." }, "token": { "type": "string", "description": "The generated access token value." }, "prefix": { "type": "string", "description": "Prefix for the generated token value." }, "expiry_at": { "type": "integer", "description": "exipy date for token." } } }, "esper_cloud_api_PersonalAccessTokenUpdateResponse": { "title": "PersonalAccessTokenUpdateResponse", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID for the generated token." }, "name": { "type": "string", "description": "Name for the token." }, "description": { "type": "string", "description": "Description for the token." }, "created_at": { "type": "string", "format": "timestamp", "description": "Timestamp indicating when the token was created." }, "updated_at": { "type": "string", "format": "timestamp", "description": "Timestamp indicating when the token was last updated." }, "token": { "type": "string", "description": "The generated access token value." }, "prefix": { "type": "string", "description": "Prefix for the generated token value." }, "expiry_at": { "type": "integer", "description": "exipy date for token." }, "legacy_token_id": { "type": "integer", "description": "token id corresponding to legacy system" }, "legacy_developer_app_id": { "type": "string", "description": "developer app id corresponding to legacy system" } } }, "esper_cloud_api_UsersListResponse": { "title": "UsersListResponse", "type": "object", "properties": { "user_id": { "title": "user id", "type": "string" }, "tenant_id": { "title": "tenant id", "type": "string", "format": "uuid" }, "partner_id": { "title": "partner id", "type": "string", "format": "uuid" }, "email": { "title": "email", "type": "string" }, "name": { "title": "name", "type": "string" }, "connection_id": { "title": "connection id", "type": "string" }, "created_at": { "title": "created_at", "type": "string", "format": "timestamp" }, "updated_at": { "title": "updated_at", "type": "string", "format": "timestamp" } } }, "blueprints_apply_policy": { "type": "string", "enum": [ "ALWAYS APPLY", "IGNORE", "PROVISION ONLY" ] }, "blueprints_device_mode_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "device_mode": { "type": "string", "enum": [ "KIOSK", "MULTI APP" ] } } }, "blueprints_launcher_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "launcher": { "type": "string", "enum": [ "ESPER", "DEFAULT" ] } }, "required": [ "apply_policy", "launcher" ] }, "blueprints_local_app_install_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_local_app_install": { "type": "boolean" } }, "required": [ "apply_policy", "allow_local_app_install" ] }, "blueprints_app_uninstall_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_app_uninstallation": { "type": "boolean" } }, "required": [ "apply_policy", "allow_app_uninstallation" ] }, "blueprints_app_permission_policy_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "permission_policy": { "type": "string", "enum": [ "ALLOW AUTOMATICALLY", "DENY", "ASK USER" ] } }, "required": [ "apply_policy", "permission_policy" ] }, "blueprints_wifi_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_wifi": { "type": "boolean" }, "wifi_state": { "type": "string", "enum": [ "ENABLE", "DISABLE" ] } }, "required": [ "apply_policy", "allow_wifi", "wifi_state" ] }, "blueprints_drift_policy": { "type": "string", "enum": [ "IGNORE", "LOG ONLY", "MINOR", "MAJOR", "CRITICAL" ], "default": "IGNORE", "description": "Allowed values: IGNORE, LOG ONLY, MINOR, MAJOR, CRITICAL" }, "blueprints_bluetooth_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_bluetooth": { "type": "boolean" }, "bluetooth_state": { "type": "string", "enum": [ "ENABLE", "DISABLE" ] }, "drift_policy": { "$ref": "#/components/schemas/blueprints_drift_policy" } }, "required": [ "apply_policy", "allow_bluetooth" ] }, "blueprints_sms_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_sms": { "type": "boolean" } }, "required": [ "apply_policy", "allow_sms" ] }, "blueprints_nfc_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_nfc": { "type": "boolean" } }, "required": [ "apply_policy", "allow_nfc" ] }, "blueprints_incoming_numbers_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_all_numbers": { "type": "boolean" }, "allowed_numbers": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "apply_policy", "allow_all_numbers" ] }, "blueprints_outgoing_numbers_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_all_numbers": { "type": "boolean" }, "allow_ussd_codes": { "type": "boolean", "default": false }, "allowed_numbers": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "apply_policy", "allow_all_numbers" ] }, "blueprints_ethernet_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "auth_mode": { "type": "string", "enum": [ "NONE", "EAP-TLS" ] }, "ca_cert_alias": { "type": "string" }, "client_cert_alias": { "type": "string" }, "eap_identity": { "type": "string" } }, "required": [ "apply_policy" ] }, "blueprints_adb_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_adb": { "type": "boolean" } }, "required": [ "apply_policy", "allow_adb" ] }, "blueprints_safe_boot_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_safe_boot": { "type": "boolean" } }, "required": [ "apply_policy", "allow_safe_boot" ] }, "blueprints_factory_reset_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_factory_reset": { "type": "boolean" } }, "required": [ "apply_policy", "allow_factory_reset" ] }, "blueprints_screen_timeout_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "screentimeout_value": { "type": "integer" } }, "required": [ "apply_policy", "screentimeout_value" ] }, "blueprints_lock_screen_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "password_quality": { "type": "string", "enum": [ "NONE", "ALPHABETIC", "NUMERIC", "ALPHANUMERIC", "COMPLEX", "BIOMETRIC_WEAK" ] }, "minimum_password_length": { "type": "integer", "nullable": true }, "allow_keyguard": { "type": "boolean" } }, "required": [ "apply_policy", "password_quality", "allow_keyguard" ] }, "blueprints_brightness_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "brightness_value": { "type": "string" } } }, "blueprints_screen_orientation_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "orientation_type": { "type": "string", "enum": [ "PORTRAIT", "LANDSCAPE", "INVERTED PORTRAIT", "INVERTED LANDSCAPE", "AUTO" ] } } }, "blueprints_screenshot_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_screenshot": { "type": "boolean" } } }, "blueprints_notification_bar_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_notification_bar": { "type": "boolean" } } }, "blueprints_wallpaper_settings": { "type": "object", "properties": { "homescreen": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "portrait": { "type": "object", "properties": { "wallpaper_id": { "type": "string" } } }, "landscape": { "type": "object", "properties": { "wallpaper_id": { "type": "string" } } } } }, "lockscreen": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "portrait": { "type": "object", "properties": { "wallpaper_id": { "type": "string" } } } } } } }, "blueprints_esper_settings_apps_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_dock": { "type": "boolean" }, "admin_mode_password": { "type": "string" }, "allow_esper_settings_app": { "type": "boolean" }, "settings": { "type": "object", "properties": { "flashlight": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "wifi": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "auto_rotation": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "reboot": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "clear_app_data": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "kiosk_app_selection": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "esper_branding": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "factory_reset": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "about": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "display": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "sound": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "keyboard": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "input_selection": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "accessibility": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "accessibility_reset_to_default": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "accessibility_high_contrast_text": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "accessibility_cc_deuteranomaly": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "accessibility_cc_protanomaly": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "accessibility_cc_tritanomaly": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "accessibility_mono_audio": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "accessibility_display_size": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "accessibility_font_scale": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "accessibility_talkback": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "accessibility_text_to_speech": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "mobile_data": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "bluetooth": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "language": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "time_and_date": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "storage": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "data_roaming": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "wifi_tethering": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] }, "airplane_mode": { "type": "string", "enum": [ "NONE", "USER", "ADMIN", "BOTH" ] } } } }, "required": [ "dock_accessibitly_settings", "admin_mode_password_settings", "settings" ] }, "blueprints_android_settings_app_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_android_settings_app": { "type": "boolean" } }, "required": [ "allow_android_settings_app" ] }, "blueprints_customized_device_level_json_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "customized_json": { "type": "object" } }, "required": [ "customized_json" ] }, "blueprints_google_services_settings": { "type": "object", "properties": { "afw_account_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_afw_account_addition": { "type": "boolean" } }, "required": [ "apply_policy", "allow_afw_account_addition" ] }, "personal_accounts_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "personal_accounts_limit_value": { "type": "integer" } }, "required": [ "apply_policy", "personal_accounts_limit_value" ] }, "play_store_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_playstore": { "type": "boolean" } }, "required": [ "apply_policy", "allow_playstore" ] }, "google_assitant_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_google_assistant": { "type": "boolean" } }, "required": [ "apply_policy", "allow_google_assistant" ] }, "factory_reset_protection_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "google_id": { "type": "string" }, "email": { "type": "string" } }, "required": [ "apply_policy", "google_id", "email" ] } }, "required": [ "afw_account_settings", "personal_accounts_settings", "play_store_settings", "google_assitant_settings", "factory_reset_protection_settings" ] }, "blueprints_external_device_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_external_device_mount": { "type": "boolean" } } }, "blueprints_usb_tethering_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_usb_tethering": { "type": "boolean" } } }, "blueprints_file_transfer_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_file_transfer": { "type": "boolean" } } }, "blueprints_camera_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_camera_access": { "type": "boolean" } } }, "blueprints_location_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_location": { "type": "boolean" } } }, "blueprints_sound_settings": { "type": "object", "properties": { "alarm_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "alarm_volume": { "type": "integer" } } }, "music_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "music_volume": { "type": "integer" } } }, "ringtone_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "ringtone_volume": { "type": "integer" } } }, "notification_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "notification_volume": { "type": "integer" } } }, "voice_call_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "voice_call_volume": { "type": "integer" } } } } }, "blueprints_system_updates_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "system_update_policy_type": { "type": "string", "enum": [ "UPDATE AUTOMATICALLY", "POSTPONE INSTALLATION", "WINDOWED INSTALLATION", "DISABLE UPDATE", "DEFAULT UPDATE" ] }, "maintenance_start": { "type": "string" }, "maintenance_end": { "type": "string" } } }, "blueprints_time_date_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_edit_time_date": { "type": "boolean" } } }, "blueprints_timezone_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "timezone": { "type": "string" } } }, "blueprints_language_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "device_locale": { "type": "string" } } }, "blueprints_strict_wifi_synchronization_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_strict_wifi_synchronization": { "type": "boolean" } } }, "blueprints_strict_app_synchronization_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_strict_app_synchronization": { "type": "boolean" } } }, "blueprints_app": { "type": "object", "properties": { "app_id": { "type": "string" }, "app_version_id": { "type": "string" }, "package_name": { "type": "string" }, "installation_rule": { "type": "string", "enum": [ "POST PROVISIONING", "DURING PROVISIONING" ] }, "state": { "type": "string", "enum": [ "SHOW", "HIDE", "DISABLE", "LAUNCHABLE_BUT_HIDDEN" ] }, "managed_config": { "type": "object" }, "type": { "type": "string", "enum": [ "PRELOADED", "ENTERPRISE", "PLAYSTORE" ] }, "auto_update_mode": { "type": "string", "enum": [ "autoUpdateDefault", "autoUpdateHighPriority", "autoUpdatePostponed" ] } }, "required": [ "app_id", "app_version_id", "package_name", "installation_rule", "state", "type", "auto_update_mode" ] }, "blueprints_apps": { "type": "array", "items": { "$ref": "#/components/schemas/blueprints_app" } }, "blueprints_file": { "type": "object", "properties": { "file_id": { "type": "integer", "description": "File identifier from Content Management" }, "destination_path": { "type": "string" } }, "required": [ "file_id", "destination_path", "tags" ] }, "blueprints_files": { "type": "array", "items": { "$ref": "#/components/schemas/blueprints_file" } }, "blueprints_wifi_network": { "type": "object", "properties": { "wifi_network_id": { "type": "string" }, "certificate_file_path": { "type": "string", "example": "/storage/emulated/0/Documents" }, "certificate_file_password": { "type": "string", "example": "abc" } }, "required": [ "wifi_network_id" ] }, "blueprints_wifi_networks": { "type": "array", "items": { "$ref": "#/components/schemas/blueprints_wifi_network" } }, "blueprints_saved_ap_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "use_only_saved_ap": { "type": "boolean" } }, "required": [ "apply_policy", "use_only_saved_ap" ] }, "blueprints_mac_address_randomization_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_mac_address_randomization": { "type": "boolean" } } }, "blueprints_esper_edgebox_settings": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_esper_edgebox": { "type": "boolean" } } }, "blueprints_app_layout_setting": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "brand_logo_position": { "type": "string", "enum": [ "BOTTOM_LEFT", "BOTTOM_RIGHT", "TOP_LEFT", "TOP_RIGHT" ] }, "device_name_position": { "type": "string", "enum": [ "BOTTOM_LEFT", "BOTTOM_RIGHT", "TOP_LEFT", "TOP_RIGHT" ] }, "app_icon_size": { "type": "string", "enum": [ "SMALL_ICON", "MEDIUM_ICON", "LARGE_ICON", "DEFAULT_ICON", "CUSTOM_ICON" ] }, "app_name_size": { "type": "string", "enum": [ "SMALL_TEXT", "MEDIUM_TEXT", "LARGE_TEXT", "DEFAULT_TEXT", "CUSTOM_TEXT" ] }, "device_name_and_id_display_policy": { "type": "string", "enum": [ "NONE", "DEFAULT", "DEVICE_ID_ONLY", "ALIAS_NAME_ONLY", "DEVICE_ID_AND_ALIAS_NAME" ] }, "device_name_size": { "type": "string", "enum": [ "SMALL_TEXT", "MEDIUM_TEXT", "LARGE_TEXT", "DEFAULT_TEXT", "CUSTOM_TEXT" ] }, "device_alias_size": { "type": "string", "enum": [ "SMALL_TEXT", "MEDIUM_TEXT", "LARGE_TEXT", "DEFAULT_TEXT", "CUSTOM_TEXT" ] }, "custom_app_icon_size": { "type": "integer", "minimum": 20, "maximum": 100 }, "custom_device_name_size": { "type": "integer", "minimum": 20, "maximum": 100 }, "custom_device_alias_size": { "type": "integer", "minimum": 20, "maximum": 100 }, "custom_app_name_size": { "type": "integer", "minimum": 20, "maximum": 100 } } }, "blueprints_app_icon": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "SINGLE_APP" ] }, "name": { "type": "string" } } }, "blueprints_app_order_setting": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "app_order_list": { "type": "array", "items": { "$ref": "#/components/schemas/blueprints_app_icon" } } } }, "blueprints_datawedge_settings": { "type": "object", "description": "DataWedge barcode scanning configuration for Zebra devices.", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "config_mode": { "type": "string", "enum": [ "NONE", "UPLOAD", "CONTENT_MANAGEMENT" ], "default": "NONE" }, "files": { "$ref": "#/components/schemas/blueprints_files" } } }, "blueprints_mx_config_settings": { "type": "object", "description": "MX Config settings — supports file upload, content management, and XML paste.", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "config_mode": { "type": "string", "enum": [ "NONE", "UPLOAD", "CONTENT_MANAGEMENT", "PASTE_XML" ], "default": "NONE" }, "files": { "$ref": "#/components/schemas/blueprints_files" }, "xml_content": { "type": "string", "nullable": true } } }, "blueprints_oem_config_options": { "type": "object", "description": "OEM Config options — multi-mode input. Exactly one of files / json_content / manual_configuration is populated depending on config_mode; the rest must be empty/null.\n", "properties": { "config_mode": { "type": "string", "enum": [ "NONE", "PASTE_JSON", "UPLOAD_JSON_FILE", "MANUAL_CONFIGURATION", "CONTENT_MANAGEMENT" ], "default": "NONE" }, "files": { "$ref": "#/components/schemas/blueprints_files" }, "json_content": { "type": "string", "nullable": true }, "manual_configuration": { "type": "object", "nullable": true, "additionalProperties": true } } }, "blueprints_oem_config_settings": { "type": "object", "description": "OEM Config settings with version picker and configuration options.", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_oem_config": { "type": "boolean", "default": false }, "oem_config_type": { "type": "string", "enum": [ "NONE", "LEGACY_ZEBRA_OEMCONFIG", "ZEBRA_OEMCONFIG_POWERED_BY_MX" ], "default": "NONE" }, "oem_config_options": { "$ref": "#/components/schemas/blueprints_oem_config_options" } } }, "blueprints_oem_settings": { "type": "object", "description": "Container for all OEM subsystem settings (DataWedge, MX Config, OEM Config).", "properties": { "datawedge_settings": { "$ref": "#/components/schemas/blueprints_datawedge_settings" }, "mx_config_settings": { "$ref": "#/components/schemas/blueprints_mx_config_settings" }, "oem_config_settings": { "$ref": "#/components/schemas/blueprints_oem_config_settings" } } }, "blueprints_advanced_configurations": { "type": "object", "description": "OEM-specific advanced configurations for AIDC devices. Currently supports Zebra (DataWedge, MX Config, OEM Config).\n", "properties": { "oem_manufacturer": { "type": "string", "nullable": true, "enum": [ "ZEBRA" ] }, "oem_settings": { "$ref": "#/components/schemas/blueprints_oem_settings" } } }, "blueprints_settings": { "type": "object", "properties": { "blueprint_drift_enabled": { "type": "boolean", "default": false, "description": "Whether granular drift detection is enabled for this blueprint. Defaults to false (disabled). When toggled on, drift-supported settings default to \"LOG ONLY\"; when toggled off, they are set to \"IGNORE\". Source of truth for granular-drift enablement." }, "device_mode_settings": { "$ref": "#/components/schemas/blueprints_device_mode_settings" }, "launcher_settings": { "$ref": "#/components/schemas/blueprints_launcher_settings" }, "local_app_install_settings": { "$ref": "#/components/schemas/blueprints_local_app_install_settings" }, "app_uninstall_settings": { "$ref": "#/components/schemas/blueprints_app_uninstall_settings" }, "app_permission_policy_settings": { "$ref": "#/components/schemas/blueprints_app_permission_policy_settings" }, "wifi_settings": { "$ref": "#/components/schemas/blueprints_wifi_settings" }, "bluetooth_settings": { "$ref": "#/components/schemas/blueprints_bluetooth_settings" }, "sms_settings": { "$ref": "#/components/schemas/blueprints_sms_settings" }, "nfc_settings": { "$ref": "#/components/schemas/blueprints_nfc_settings" }, "incoming_numbers_settings": { "$ref": "#/components/schemas/blueprints_incoming_numbers_settings" }, "outgoing_numbers_settings": { "$ref": "#/components/schemas/blueprints_outgoing_numbers_settings" }, "ethernet_settings": { "$ref": "#/components/schemas/blueprints_ethernet_settings" }, "adb_settings": { "$ref": "#/components/schemas/blueprints_adb_settings" }, "safe_boot_settings": { "$ref": "#/components/schemas/blueprints_safe_boot_settings" }, "factory_reset_settings": { "$ref": "#/components/schemas/blueprints_factory_reset_settings" }, "screen_timeout_settings": { "$ref": "#/components/schemas/blueprints_screen_timeout_settings" }, "lock_screen_settings": { "$ref": "#/components/schemas/blueprints_lock_screen_settings" }, "brightness_settings": { "$ref": "#/components/schemas/blueprints_brightness_settings" }, "screen_orientation_settings": { "$ref": "#/components/schemas/blueprints_screen_orientation_settings" }, "screenshot_settings": { "$ref": "#/components/schemas/blueprints_screenshot_settings" }, "notification_bar_settings": { "$ref": "#/components/schemas/blueprints_notification_bar_settings" }, "wallpaper_settings": { "$ref": "#/components/schemas/blueprints_wallpaper_settings" }, "esper_settings_apps_settings": { "$ref": "#/components/schemas/blueprints_esper_settings_apps_settings" }, "android_settings_app_settings": { "$ref": "#/components/schemas/blueprints_android_settings_app_settings" }, "customized_device_level_json_settings": { "$ref": "#/components/schemas/blueprints_customized_device_level_json_settings" }, "google_services_settings": { "$ref": "#/components/schemas/blueprints_google_services_settings" }, "external_device_settings": { "$ref": "#/components/schemas/blueprints_external_device_settings" }, "usb_tethering_settings": { "$ref": "#/components/schemas/blueprints_usb_tethering_settings" }, "file_transfer_settings": { "$ref": "#/components/schemas/blueprints_file_transfer_settings" }, "camera_settings": { "$ref": "#/components/schemas/blueprints_camera_settings" }, "location_settings": { "$ref": "#/components/schemas/blueprints_location_settings" }, "sound_settings": { "$ref": "#/components/schemas/blueprints_sound_settings" }, "system_updates_settings": { "$ref": "#/components/schemas/blueprints_system_updates_settings" }, "time_date_settings": { "$ref": "#/components/schemas/blueprints_time_date_settings" }, "timezone_settings": { "$ref": "#/components/schemas/blueprints_timezone_settings" }, "language_settings": { "$ref": "#/components/schemas/blueprints_language_settings" }, "strict_wifi_synchronization_settings": { "$ref": "#/components/schemas/blueprints_strict_wifi_synchronization_settings" }, "strict_app_synchronization_settings": { "$ref": "#/components/schemas/blueprints_strict_app_synchronization_settings" }, "apps": { "$ref": "#/components/schemas/blueprints_apps" }, "files": { "$ref": "#/components/schemas/blueprints_files" }, "wifi_networks": { "$ref": "#/components/schemas/blueprints_wifi_networks" }, "saved_ap_settings": { "$ref": "#/components/schemas/blueprints_saved_ap_settings" }, "mac_address_randomization_settings": { "$ref": "#/components/schemas/blueprints_mac_address_randomization_settings" }, "esper_edgebox_settings": { "$ref": "#/components/schemas/blueprints_esper_edgebox_settings" }, "app_layout_setting": { "$ref": "#/components/schemas/blueprints_app_layout_setting" }, "app_order_setting": { "$ref": "#/components/schemas/blueprints_app_order_setting" }, "advanced_configurations": { "$ref": "#/components/schemas/blueprints_advanced_configurations" } } }, "blueprints_kiosk_mode_settings": { "type": "object", "properties": { "app_id": { "type": "string" }, "app_type": { "type": "string", "enum": [ "VPP", "TENANT_IOS", "ESPER_IOS", "WEBCLIP", "PRELOADED" ] }, "disable_device_rotation": { "type": "boolean", "default": false }, "disable_screen_timeout": { "type": "boolean", "default": true } } }, "blueprints_local_app_install_settings_ios": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_local_app_install": { "type": "boolean", "default": true } }, "required": [ "apply_policy", "allow_local_app_install" ] }, "blueprints_app_uninstall_settings_ios": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_app_uninstallation": { "type": "boolean", "default": true } }, "required": [ "apply_policy", "allow_app_uninstallation" ] }, "blueprints_bluetooth_settings_ios": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "edit_bluetooth": { "type": "boolean", "default": true } }, "required": [ "apply_policy", "edit_bluetooth" ] }, "blueprints_nfc_settings_ios": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_nfc": { "type": "boolean", "default": true } }, "required": [ "apply_policy", "allow_nfc" ] }, "blueprints_factory_reset_settings_ios": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_factory_reset": { "type": "boolean", "default": true } }, "required": [ "apply_policy", "allow_factory_reset" ] }, "blueprints_screenshot_settings_ios": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_screenshot": { "type": "boolean", "default": true } } }, "blueprints_custom_device_level_profile_settings_ios": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "custom_profile": { "type": "string", "nullable": true } }, "required": [ "customized_profile" ] }, "blueprints_siri_settings_ios": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_siri": { "type": "boolean", "default": true } }, "required": [ "apply_policy", "allow_siri" ] }, "blueprints_tethering_settings_ios": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "edit_hotspot": { "type": "boolean", "default": true } } }, "blueprints_camera_settings_ios": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_camera_access": { "type": "boolean", "default": true } } }, "blueprints_hide_preloaded_apps_settings_ios": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "hide_preloaded_apps": { "type": "boolean", "default": true } } }, "blueprints_time_date_settings_ios": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "force_automatic_time_date": { "type": "boolean", "default": false } } }, "blueprints_wifi_network_ios": { "type": "object", "properties": { "wifi_network_id": { "type": "string" } }, "required": [ "wifi_network_id" ] }, "blueprints_wifi_networks_ios": { "type": "array", "items": { "$ref": "#/components/schemas/blueprints_wifi_network_ios" } }, "blueprints_ios_app": { "type": "object", "properties": { "app_id": { "type": "string" }, "app_version_id": { "type": "string" }, "state": { "type": "string", "enum": [ "SHOW" ] }, "app_type": { "type": "string", "enum": [ "VPP", "TENANT_IOS", "ESPER_IOS", "WEBCLIP", "PRELOADED" ] }, "base64_app_config": { "type": "string" }, "auto_update": { "type": "boolean", "default": false, "description": "Enable automatic updates for the app. Only allowed when app_type is VPP." } }, "required": [ "app_id", "app_version_id", "state", "app_type" ] }, "blueprints_ios_apps": { "type": "array", "items": { "$ref": "#/components/schemas/blueprints_ios_app" } }, "blueprints_provisioning_profile_ios": { "type": "object", "properties": { "profile_id": { "type": "string", "format": "uuid" }, "profile_version_id": { "type": "string", "format": "uuid" } }, "required": [ "profile_id", "profile_version_id" ] }, "blueprints_provisioning_profiles_ios": { "type": "array", "items": { "$ref": "#/components/schemas/blueprints_provisioning_profile_ios" } }, "blueprints_ios_wallpaper_settings": { "type": "object", "properties": { "homescreen": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "portrait": { "type": "object", "properties": { "wallpaper_id": { "type": "string" } } } } }, "lockscreen": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "portrait": { "type": "object", "properties": { "wallpaper_id": { "type": "string" } } } } } } }, "blueprints_web_content_setting_ios": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "url_blocklist": { "type": "array", "items": { "type": "string" } }, "url_allowlist": { "type": "array", "items": { "type": "string" } } } }, "blueprints_defer_os_updates": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "defer_os_updates_delay": { "type": "integer", "minimum": 0, "maximum": 90 } } }, "blueprints_ddm_os_update_settings_ios": { "type": "object", "description": "iOS declarative device management (DDM) OS update settings. Every leaf setting's apply_policy defaults to IGNORE (opt-in), so a blueprint that never configures this section won't dispatch an update command with default values to devices.", "properties": { "automatic_actions": { "type": "object", "properties": { "download": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "download": { "type": "string", "enum": [ "ALLOWED", "ALWAYS_ON", "ALWAYS_OFF" ], "default": "ALLOWED" } }, "required": [ "apply_policy", "download" ] }, "install_os_updates": { "type": "object", "description": "ALWAYS_ON has no effect when automatic_actions.download is ALWAYS_OFF (the device only applies this with automatic downloads enabled).", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "install_os_updates": { "type": "string", "enum": [ "ALLOWED", "ALWAYS_ON", "ALWAYS_OFF" ], "default": "ALLOWED" } }, "required": [ "apply_policy", "install_os_updates" ] }, "install_security_update": { "type": "object", "description": "ALWAYS_ON has no effect when automatic_actions.download is ALWAYS_OFF (the device only applies this with automatic downloads enabled).", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "install_security_update": { "type": "string", "enum": [ "ALLOWED", "ALWAYS_ON", "ALWAYS_OFF" ], "default": "ALLOWED" } }, "required": [ "apply_policy", "install_security_update" ] } }, "required": [ "download", "install_os_updates", "install_security_update" ] }, "deferrals": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "combined_period_in_days": { "type": "integer", "minimum": 1, "maximum": 90, "nullable": true, "description": "Number of days to combine software update notifications." } }, "required": [ "apply_policy" ] }, "notifications": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "notifications": { "type": "boolean", "default": true } }, "required": [ "apply_policy", "notifications" ] }, "rapid_security_response": { "type": "object", "properties": { "enable": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "enable": { "type": "boolean", "default": true } }, "required": [ "apply_policy", "enable" ] }, "enable_rollback": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "enable_rollback": { "type": "boolean", "default": true } }, "required": [ "apply_policy", "enable_rollback" ] } }, "required": [ "enable", "enable_rollback" ] }, "recommended_cadence": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "recommended_cadence": { "type": "string", "enum": [ "ALL", "OLDEST", "NEWEST" ], "default": "ALL" } }, "required": [ "apply_policy", "recommended_cadence" ] } }, "required": [ "automatic_actions", "deferrals", "notifications", "rapid_security_response", "recommended_cadence" ] }, "blueprints_mac_address_randomization_settings_ios": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "disable_mac_randomization": { "type": "boolean", "default": false } } }, "blueprints_allowed_wifi_networks_settings_ios": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "force_wifi_to_allowed_networks_only": { "type": "boolean", "default": false } } }, "blueprints_iosSettings": { "type": "object", "properties": { "kiosk_app": { "$ref": "#/components/schemas/blueprints_kiosk_mode_settings" }, "device_mode_settings": { "$ref": "#/components/schemas/blueprints_device_mode_settings" }, "local_app_install_settings": { "$ref": "#/components/schemas/blueprints_local_app_install_settings_ios" }, "app_uninstall_settings": { "$ref": "#/components/schemas/blueprints_app_uninstall_settings_ios" }, "bluetooth_settings": { "$ref": "#/components/schemas/blueprints_bluetooth_settings_ios" }, "nfc_settings": { "$ref": "#/components/schemas/blueprints_nfc_settings_ios" }, "factory_reset_settings": { "$ref": "#/components/schemas/blueprints_factory_reset_settings_ios" }, "screenshot_settings": { "$ref": "#/components/schemas/blueprints_screenshot_settings_ios" }, "custom_device_level_profile_settings": { "$ref": "#/components/schemas/blueprints_custom_device_level_profile_settings_ios" }, "siri_settings": { "$ref": "#/components/schemas/blueprints_siri_settings_ios" }, "tethering_settings": { "$ref": "#/components/schemas/blueprints_tethering_settings_ios" }, "camera_settings": { "$ref": "#/components/schemas/blueprints_camera_settings_ios" }, "hide_preloaded_apps_settings": { "$ref": "#/components/schemas/blueprints_hide_preloaded_apps_settings_ios" }, "time_date_settings": { "$ref": "#/components/schemas/blueprints_time_date_settings_ios" }, "wifi_networks": { "$ref": "#/components/schemas/blueprints_wifi_networks_ios" }, "apps": { "$ref": "#/components/schemas/blueprints_ios_apps" }, "provisioning_profiles": { "$ref": "#/components/schemas/blueprints_provisioning_profiles_ios" }, "wallpaper_settings": { "$ref": "#/components/schemas/blueprints_ios_wallpaper_settings" }, "web_content_settings": { "$ref": "#/components/schemas/blueprints_web_content_setting_ios" }, "defer_os_updates": { "$ref": "#/components/schemas/blueprints_defer_os_updates" }, "ddm_os_update_settings": { "$ref": "#/components/schemas/blueprints_ddm_os_update_settings_ios" }, "strict_wifi_synchronization_settings": { "$ref": "#/components/schemas/blueprints_strict_wifi_synchronization_settings" }, "mac_address_randomization_settings": { "$ref": "#/components/schemas/blueprints_mac_address_randomization_settings_ios" }, "allowed_wifi_networks_settings": { "$ref": "#/components/schemas/blueprints_allowed_wifi_networks_settings_ios" } } }, "blueprints_tvos_kiosk_mode_settings": { "type": "object", "description": "Kiosk app configuration for tvOS. WEBCLIP and PRELOADED types are not allowed.", "properties": { "app_id": { "type": "string", "format": "uuid" }, "app_type": { "type": "string", "enum": [ "VPP", "TENANT_IOS", "ESPER_IOS" ] } }, "required": [ "app_id", "app_type" ] }, "blueprints_wifi_access_points_tvos": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" } } }, "blueprints_tvos_app": { "type": "object", "description": "App configuration for tvOS devices. WEBCLIP apps are not supported on tvOS.", "properties": { "app_id": { "type": "string", "format": "uuid" }, "app_version_id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "SHOW" ] }, "app_type": { "type": "string", "enum": [ "VPP", "TENANT_IOS", "ESPER_IOS", "PRELOADED" ] }, "base64_app_config": { "type": "string" }, "auto_update": { "type": "boolean", "default": false, "description": "Enable automatic updates for the app. Only allowed when app_type is VPP." } }, "required": [ "app_id", "app_version_id", "state", "app_type" ] }, "blueprints_tvos_apps": { "type": "array", "items": { "$ref": "#/components/schemas/blueprints_tvos_app" } }, "blueprints_ddm_os_update_settings_tvos": { "type": "object", "description": "tvOS declarative device management (DDM) OS update settings. Reduced shape versus iOS — only deferrals and notifications are supported. Every leaf setting's apply_policy defaults to IGNORE (opt-in).", "properties": { "deferrals": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "combined_period_in_days": { "type": "integer", "minimum": 1, "maximum": 90, "nullable": true, "description": "Number of days to combine software update notifications." } }, "required": [ "apply_policy" ] }, "notifications": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "notifications": { "type": "boolean", "default": true } }, "required": [ "apply_policy", "notifications" ] } }, "required": [ "deferrals", "notifications" ] }, "blueprints_tvosSettings": { "type": "object", "description": "Configuration settings specific to tvOS (Apple TV) devices", "properties": { "device_mode_settings": { "$ref": "#/components/schemas/blueprints_device_mode_settings" }, "kiosk_app": { "$ref": "#/components/schemas/blueprints_tvos_kiosk_mode_settings" }, "custom_device_level_profile_settings": { "$ref": "#/components/schemas/blueprints_custom_device_level_profile_settings_ios" }, "hide_preloaded_apps_settings": { "$ref": "#/components/schemas/blueprints_hide_preloaded_apps_settings_ios" }, "time_date_settings": { "$ref": "#/components/schemas/blueprints_time_date_settings_ios" }, "wifi_access_points": { "$ref": "#/components/schemas/blueprints_wifi_access_points_tvos" }, "wifi_networks": { "$ref": "#/components/schemas/blueprints_wifi_networks_ios" }, "apps": { "$ref": "#/components/schemas/blueprints_tvos_apps" }, "provisioning_profiles": { "$ref": "#/components/schemas/blueprints_provisioning_profiles_ios" }, "defer_os_updates": { "$ref": "#/components/schemas/blueprints_defer_os_updates" }, "ddm_os_update_settings": { "$ref": "#/components/schemas/blueprints_ddm_os_update_settings_tvos" }, "strict_wifi_synchronization_settings": { "$ref": "#/components/schemas/blueprints_strict_wifi_synchronization_settings" } } }, "blueprints_shellScriptLinux": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "script": { "type": "string", "description": "The shell script to be executed." }, "interpreter": { "type": "string", "description": "The interpreter to use for the script (e.g., bash)." }, "alias": { "type": "string", "description": "A user-friendly name or alias for the script." }, "description": { "type": "string", "description": "A description of what the script does." }, "timeout_in_mins": { "type": "integer", "nullable": true, "minimum": 2, "maximum": 35791394, "description": "Maximum runtime in minutes before the script is terminated. If not set, the on-device agent's own default applies." } }, "required": [ "apply_policy", "script", "interpreter", "alias" ] }, "blueprints_customShellScriptsMultiple": { "type": "object", "properties": { "shell_scripts": { "type": "array", "items": { "$ref": "#/components/schemas/blueprints_shellScriptLinux" } } } }, "blueprints_customActionLinux": { "type": "object", "description": "Reference to a custom action to be applied on Linux devices within a blueprint.", "properties": { "id": { "type": "string", "format": "uuid", "description": "The UUID of the custom action to apply." }, "options_key": { "type": "string", "format": "uuid", "description": "The UUID of the specific option key within the Custom Action to use." }, "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" } }, "required": [ "id", "options_key", "apply_policy" ] }, "blueprints_customActionsMultipleLinux": { "type": "object", "description": "Collection of custom actions to be applied on Linux devices.", "properties": { "custom_actions": { "type": "array", "description": "List of custom actions to apply to Linux devices.", "items": { "$ref": "#/components/schemas/blueprints_customActionLinux" } } } }, "blueprints_linuxFile": { "type": "object", "properties": { "file_id": { "type": "integer" }, "destination_path": { "type": "string", "example": "/tmp" } }, "required": [ "file_id", "destination_path" ] }, "blueprints_linuxFiles": { "type": "array", "items": { "$ref": "#/components/schemas/blueprints_linuxFile" } }, "blueprints_linuxSettings": { "type": "object", "description": "Configuration settings specific to Linux devices in a blueprint", "properties": { "custom_shell_scripts_multiple": { "$ref": "#/components/schemas/blueprints_customShellScriptsMultiple" }, "custom_actions_multiple": { "$ref": "#/components/schemas/blueprints_customActionsMultipleLinux" }, "files": { "$ref": "#/components/schemas/blueprints_linuxFiles" } } }, "blueprints_active_hours_settings_windows": { "type": "object", "description": "Windows active hours configuration for controlling update installation timing", "properties": { "active_hours_start": { "type": "object", "description": "Start time for active hours", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "time": { "type": "integer", "minimum": 0, "maximum": 23, "default": 8, "description": "Start hour in 24-hour format (0-23)" } }, "required": [ "apply_policy", "time" ] }, "active_hours_end": { "type": "object", "description": "End time for active hours", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "time": { "type": "integer", "minimum": 0, "maximum": 23, "default": 17, "description": "End hour in 24-hour format (0-23)" } }, "required": [ "apply_policy", "time" ] } }, "required": [ "active_hours_start", "active_hours_end" ] }, "blueprints_windows_app": { "type": "object", "properties": { "app_id": { "type": "string" }, "app_version_id": { "type": "string" }, "state": { "type": "string", "enum": [ "SHOW" ] }, "app_type": { "type": "string", "enum": [ "TENANT_WINDOWS", "ESPER_WINDOWS", "TENANT_WINDOWS_EXE", "TENANT_WINDOWS_UWP" ] }, "base64_app_config": { "type": "string" } }, "required": [ "app_id", "app_version_id", "state", "app_type" ] }, "blueprints_windows_apps": { "type": "array", "items": { "$ref": "#/components/schemas/blueprints_windows_app" } }, "blueprints_auto_update_settings_windows": { "type": "object", "description": "Windows automatic updates configuration", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "auto_update_type": { "type": "string", "enum": [ "NOTIFY_DOWNLOAD", "AUTO_INSTALL_AND_NOTIFY_RESTART", "DEFAULT", "SCHEDULED_INSTALL_AND_RESTART", "AUTO_INSTALL_AND_RESTART_FORCED", "OFF" ], "default": "DEFAULT", "description": "Type of automatic update behavior, mapped to the Windows CSP Update/AllowAutoUpdate. NOTIFY_DOWNLOAD notifies before downloading; AUTO_INSTALL_AND_NOTIFY_RESTART auto-installs and notifies to schedule a restart; DEFAULT auto-installs and restarts (system default); SCHEDULED_INSTALL_AND_RESTART auto-installs and restarts at a scheduled time; AUTO_INSTALL_AND_RESTART_FORCED auto-installs and restarts without end-user control; OFF disables automatic updates." } }, "required": [ "apply_policy", "auto_update_type" ] }, "blueprints_background_script_settings": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the background script registered in the tenant." }, "apply_policy": { "type": "string", "enum": [ "ALWAYS APPLY", "IGNORE", "PROVISION ONLY" ], "default": "ALWAYS APPLY" } } }, "blueprints_background_scripts_windows": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/blueprints_background_script_settings" } }, "blueprints_custom_policy_setting": { "type": "object", "required": [ "apply_policy", "is_atomic", "b64_csp_payload", "alias" ], "properties": { "apply_policy": { "type": "string", "enum": [ "ALWAYS APPLY", "IGNORE", "PROVISION ONLY" ], "default": "ALWAYS APPLY" }, "is_atomic": { "type": "boolean", "default": false }, "b64_csp_payload": { "type": "string", "maxLength": 87382, "description": "Base64-encoded CSP (SyncML/OMA-DM) payload." }, "alias": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 300 } } }, "blueprints_custom_policies_windows": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/blueprints_custom_policy_setting" } }, "blueprints_powerShellScriptWindows": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "script": { "type": "string", "description": "The PowerShell script to be executed." }, "interpreter": { "type": "string", "maxLength": 255, "description": "The interpreter to use for the script (e.g., powershell)." }, "alias": { "type": "string", "maxLength": 100, "description": "A user-friendly name or alias for the script." }, "description": { "type": "string", "maxLength": 300, "description": "A description of what the script does." }, "timeout_in_mins": { "type": "integer", "nullable": true, "minimum": 2, "maximum": 35791394, "description": "Maximum runtime in minutes before the script is terminated. If not set, the on-device agent's own default applies." } }, "required": [ "apply_policy", "script", "interpreter", "alias" ] }, "blueprints_customShellScriptsMultipleWindows": { "type": "object", "properties": { "shell_scripts": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/blueprints_powerShellScriptWindows" } } } }, "blueprints_defer_os_updates_windows": { "type": "object", "description": "Windows OS updates deferral configuration with separate quality and feature update controls", "properties": { "quality_updates": { "type": "object", "description": "Quality updates deferral settings", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "defer_days": { "type": "integer", "minimum": 0, "maximum": 30, "default": 0, "description": "Number of days to defer quality updates" } }, "required": [ "apply_policy", "defer_days" ] }, "feature_updates": { "type": "object", "description": "Feature updates deferral settings", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "defer_days": { "type": "integer", "minimum": 0, "maximum": 365, "default": 0, "description": "Number of days to defer feature updates" } }, "required": [ "apply_policy", "defer_days" ] } }, "required": [ "quality_updates", "feature_updates" ] }, "blueprints_windowsFile": { "type": "object", "properties": { "file_id": { "type": "integer" }, "destination_path": { "type": "string", "example": "C:\\" } }, "required": [ "file_id", "destination_path" ] }, "blueprints_windowsFiles": { "type": "array", "items": { "$ref": "#/components/schemas/blueprints_windowsFile" } }, "blueprints_windows_kiosk_win32_single_app_config": { "type": "object", "description": "Win32 single-app kiosk configuration. Defaults applied if not provided.", "properties": { "name": { "type": "string", "description": "Name of the kiosk profile" }, "desktop_app_path": { "type": "string", "description": "Absolute path to the kiosk desktop app executable (required)" }, "auto_launch": { "type": "boolean", "default": true, "description": "Automatically launch the app" }, "auto_launch_arguments": { "type": "string", "default": "", "description": "Arguments passed to the app on launch" }, "hide_taskbar": { "type": "boolean", "default": true, "description": "Hide Windows taskbar" }, "hide_start_recommended_section": { "type": "boolean", "default": true, "description": "Hide Recommended section from Start menu" }, "hide_power_button": { "type": "boolean", "default": false, "description": "Hide power button in Start menu" } } }, "blueprints_windows_kiosk_uwp_single_app_config": { "type": "object", "description": "UWP single-app kiosk configuration. app_id must match an entry in windows.apps with app_type TENANT_WINDOWS_UWP.\n", "required": [ "app_id" ], "properties": { "app_id": { "type": "string", "format": "uuid", "description": "UUID of the UWP app. Must be present in windows.apps with app_type TENANT_WINDOWS_UWP." } } }, "blueprints_windows_kiosk_settings": { "type": "object", "description": "Windows kiosk configuration. kiosk_type determines the kiosk mechanism: CONFIGURATION uses Windows Assigned Access, SHELL_LAUNCHER uses Shell Launcher. Exactly one of win32_single_app_config or uwp_single_app_config must be set when kiosk_settings is present. kiosk_type defaults to CONFIGURATION if omitted (backward compatible with pre-existing blueprints).\n", "properties": { "kiosk_type": { "type": "string", "enum": [ "CONFIGURATION", "SHELL_LAUNCHER" ], "default": "CONFIGURATION", "description": "Kiosk mechanism to use. CONFIGURATION uses Windows Assigned Access; SHELL_LAUNCHER uses Shell Launcher. Defaults to CONFIGURATION if omitted.\n" }, "win32_single_app_config": { "$ref": "#/components/schemas/blueprints_windows_kiosk_win32_single_app_config" }, "uwp_single_app_config": { "$ref": "#/components/schemas/blueprints_windows_kiosk_uwp_single_app_config" } } }, "blueprints_pause_os_updates_windows": { "type": "object", "description": "Windows pause OS updates configuration", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "pause_os_updates": { "type": "boolean", "default": false, "description": "Whether to pause OS updates" } }, "required": [ "apply_policy", "pause_os_updates" ] }, "blueprints_scheduled_install_settings_windows": { "type": "object", "description": "Windows scheduled install configuration. Only valid when auto_update_type is SCHEDULED_INSTALL_AND_RESTART or AUTO_INSTALL_AND_RESTART_FORCED. Each sub-field is optional — omitting it leaves the corresponding Windows default in effect (3 AM, every day, every week).", "properties": { "scheduled_install_day": { "type": "object", "description": "Day of the week for scheduled install. Maps to Update/ScheduledInstallDay CSP.", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "day": { "type": "string", "enum": [ "EVERY_DAY", "SUNDAY", "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY" ], "nullable": true } }, "required": [ "apply_policy" ] }, "scheduled_install_week": { "type": "object", "description": "Week of the month for scheduled install. Maps to Update/ScheduledInstall*Week CSPs.", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "week": { "type": "string", "enum": [ "ALL", "FIRST", "SECOND", "THIRD", "FOURTH" ], "nullable": true } }, "required": [ "apply_policy" ] }, "scheduled_install_time": { "type": "object", "description": "Hour of day for scheduled install (0 = 12 AM, 23 = 11 PM). Maps to Update/ScheduledInstallTime CSP.", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "time": { "type": "integer", "minimum": 0, "maximum": 23, "nullable": true } }, "required": [ "apply_policy" ] } } }, "blueprints_unenrollment_settings_windows": { "type": "object", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "allow_unenrollment_from_device": { "type": "boolean" } }, "required": [ "apply_policy", "allow_unenrollment_from_device" ] }, "blueprints_windows_wallpaper_settings": { "type": "object", "description": "Configuration for Windows desktop wallpaper settings including homescreen and lockscreen backgrounds. Uses landscape orientation only.", "properties": { "homescreen": { "type": "object", "description": "Wallpaper settings for the Windows desktop homescreen", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "landscape": { "type": "object", "description": "Landscape wallpaper configuration", "properties": { "wallpaper_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Unique identifier for the wallpaper resource" } } } } }, "lockscreen": { "type": "object", "description": "Wallpaper settings for the Windows lock screen", "properties": { "apply_policy": { "$ref": "#/components/schemas/blueprints_apply_policy" }, "landscape": { "type": "object", "description": "Landscape wallpaper configuration", "properties": { "wallpaper_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Unique identifier for the wallpaper resource" } } } } } } }, "blueprints_wifi_network_windows": { "type": "object", "properties": { "wifi_network_id": { "type": "string" } }, "required": [ "wifi_network_id" ] }, "blueprints_wifi_networks_windows": { "type": "array", "items": { "$ref": "#/components/schemas/blueprints_wifi_network_windows" } }, "blueprints_windowsSettings": { "type": "object", "properties": { "active_hours_settings": { "$ref": "#/components/schemas/blueprints_active_hours_settings_windows" }, "apps": { "$ref": "#/components/schemas/blueprints_windows_apps" }, "auto_update_settings": { "$ref": "#/components/schemas/blueprints_auto_update_settings_windows" }, "background_scripts": { "$ref": "#/components/schemas/blueprints_background_scripts_windows" }, "bluetooth_settings": { "$ref": "#/components/schemas/blueprints_bluetooth_settings" }, "camera_settings": { "$ref": "#/components/schemas/blueprints_camera_settings" }, "custom_policies": { "$ref": "#/components/schemas/blueprints_custom_policies_windows" }, "custom_shell_scripts_multiple": { "$ref": "#/components/schemas/blueprints_customShellScriptsMultipleWindows" }, "device_mode_settings": { "$ref": "#/components/schemas/blueprints_device_mode_settings" }, "defer_os_updates": { "$ref": "#/components/schemas/blueprints_defer_os_updates_windows" }, "factory_reset_settings": { "$ref": "#/components/schemas/blueprints_factory_reset_settings" }, "files": { "$ref": "#/components/schemas/blueprints_windowsFiles" }, "kiosk_settings": { "$ref": "#/components/schemas/blueprints_windows_kiosk_settings" }, "pause_os_updates": { "$ref": "#/components/schemas/blueprints_pause_os_updates_windows" }, "scheduled_install_settings": { "$ref": "#/components/schemas/blueprints_scheduled_install_settings_windows" }, "timezone_settings": { "$ref": "#/components/schemas/blueprints_timezone_settings" }, "unenrollment_settings": { "$ref": "#/components/schemas/blueprints_unenrollment_settings_windows" }, "wallpaper_settings": { "$ref": "#/components/schemas/blueprints_windows_wallpaper_settings" }, "wifi_networks": { "$ref": "#/components/schemas/blueprints_wifi_networks_windows" } } }, "blueprints_settingsV2": { "type": "object", "properties": { "android": { "$ref": "#/components/schemas/blueprints_settings" }, "ios": { "$ref": "#/components/schemas/blueprints_iosSettings" }, "tvos": { "$ref": "#/components/schemas/blueprints_tvosSettings" }, "linux": { "$ref": "#/components/schemas/blueprints_linuxSettings" }, "windows": { "$ref": "#/components/schemas/blueprints_windowsSettings" } } }, "blueprints_BlueprintV2": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string", "description": "Name of the blueprint" }, "description": { "type": "string", "description": "Description of the blueprint" }, "comments": { "type": "string", "description": "Comments on the blueprint" }, "version_number": { "type": "integer", "readOnly": true }, "version_id": { "type": "string", "format": "uuid", "readOnly": true }, "minor_version_number": { "type": "integer", "readOnly": true }, "publish": { "type": "boolean", "readOnly": true }, "settings": { "$ref": "#/components/schemas/blueprints_settingsV2" }, "created_by": { "type": "string", "description": "ID of the user who created the blueprint", "readOnly": true }, "updated_by": { "type": "string", "description": "ID of the user who updated the blueprint", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "blueprints_BlueprintV2Put": { "allOf": [ { "$ref": "#/components/schemas/blueprints_BlueprintV2" }, { "type": "object", "properties": { "publish": { "type": "boolean", "description": "Field to indicate whether to publish the blueprint\n", "readOnly": false } } } ] }, "blueprints_customActionBase": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Custom Action name" }, "type": { "type": "string", "enum": [ "button", "toggle", "radio", "dropdown" ], "description": "The UI component type for this custom action" }, "state": { "type": "string", "enum": [ "draft", "active", "inactive" ], "description": "The current operational state of the custom action. Only active custom actions can be deployed to Linux devices." }, "position_in_blueprints": { "type": "string", "enum": [ "none", "blueprints_apps_and_configuration", "blueprints_connectivity", "blueprints_device_security", "blueprints_display_and_branding", "blueprints_esper_settings", "blueprints_scripts", "blueprints_files", "blueprints_platform_services", "blueprints_hardware_settings", "blueprints_sound", "blueprints_system_updates", "blueprints_time_and_date" ], "description": "The location in the blueprint where the custom action will be added" }, "position_in_device_settings": { "type": "string", "enum": [ "none", "device_quick_settings" ], "description": "The location in the device's Quick Actions where the custom action will be added" }, "properties": { "type": "object", "description": "Object for the description, info_message, and tooltip_message." } }, "required": [ "name", "type", "state", "position_in_blueprints", "position_in_device_settings", "properties" ] }, "blueprints_platformScriptResponse": { "type": "object", "properties": { "script_id": { "type": "string", "format": "uuid", "description": "Script identifier stored in external storage" } }, "required": [ "script_id" ] }, "blueprints_options_response": { "type": "object", "properties": { "label": { "type": "string", "description": "Label shown on the UI" }, "key": { "type": "string", "format": "uuid", "description": "Unique key identifier for the option" }, "scripts": { "type": "object", "description": "Platform-specific script references. Currently only Linux platform is supported. Platform key must be lowercase \"linux\".", "properties": { "linux": { "$ref": "#/components/schemas/blueprints_platformScriptResponse" } }, "required": [ "linux" ], "additionalProperties": false } }, "required": [ "label", "key", "scripts" ] }, "blueprints_CustomActionRead": { "allOf": [ { "$ref": "#/components/schemas/blueprints_customActionBase" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the custom action" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/blueprints_options_response" }, "description": "List of options for the custom action" }, "created_at": { "type": "string", "format": "date-time", "description": "When the custom action was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the custom action was last updated" }, "created_by": { "type": "integer", "description": "User ID who created the custom action" }, "updated_by": { "type": "integer", "description": "User ID who last updated the custom action" } }, "required": [ "id", "options", "created_at", "updated_at", "created_by", "updated_by" ] } ] }, "blueprints_platformScriptRequest": { "type": "object", "properties": { "script": { "type": "string", "description": "The script content to be executed on Linux devices" }, "interpreter": { "type": "string", "maxLength": 255, "description": "Interpreter used to run the script. Default is \"bash\" if not specified. Common values include \"bash\", \"sh\", \"python\", \"python3\"", "default": "bash" }, "timeout_in_mins": { "type": "integer", "minimum": 2, "maximum": 35791394, "description": "Optional maximum runtime in minutes before the script is terminated. Must be between 2 and 35791394 (math.MaxInt32 / 60). If omitted the on-device agent applies its own default." } }, "required": [ "script", "interpreter" ] }, "blueprints_optionsRequest": { "type": "object", "properties": { "label": { "type": "string", "description": "Label shown on the UI" }, "key": { "type": "string", "format": "uuid", "description": "Unique key identifier for the option" }, "scripts": { "type": "object", "description": "Platform-specific scripts. Currently only Linux platform is supported. Platform key must be lowercase \"linux\".", "properties": { "linux": { "$ref": "#/components/schemas/blueprints_platformScriptRequest" } }, "required": [ "linux" ], "additionalProperties": false } }, "required": [ "label", "key", "scripts" ] }, "blueprints_CustomActionCreate": { "allOf": [ { "$ref": "#/components/schemas/blueprints_customActionBase" }, { "type": "object", "properties": { "options": { "type": "array", "items": { "$ref": "#/components/schemas/blueprints_optionsRequest" }, "description": "List of options for the custom action" } }, "required": [ "options" ] } ] }, "blueprints_CustomActionUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Custom action name" }, "type": { "type": "string", "enum": [ "button", "toggle", "radio", "dropdown" ], "description": "The UI component type for this custom action" }, "state": { "type": "string", "enum": [ "draft", "active", "inactive" ], "description": "The current operational state of the custom action" }, "position_in_blueprints": { "type": "string", "enum": [ "none", "blueprints_apps_and_configuration", "blueprints_connectivity", "blueprints_device_security", "blueprints_display_and_branding", "blueprints_esper_settings", "blueprints_scripts", "blueprints_files", "blueprints_platform_services", "blueprints_hardware_settings", "blueprints_sound", "blueprints_system_updates", "blueprints_time_and_date" ], "description": "The location in the blueprint where the custom action will be added" }, "position_in_device_settings": { "type": "string", "enum": [ "none", "device_quick_settings" ], "description": "The location in the device's Quick Actions where the custom action will be added" }, "properties": { "type": "object", "description": "Object for the description, info_message, and tooltip_message. Replaces the existing properties." }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/blueprints_optionsRequest" }, "description": "A new list of options to replace the existing ones" } }, "description": "Update a custom action. All fields are optional." }, "blueprints_platformScript": { "type": "object", "properties": { "script": { "type": "string", "description": "The script content" }, "interpreter": { "type": "string", "description": "Interpreter used to run the script" }, "timeout_in_mins": { "type": "integer", "minimum": 2, "maximum": 35791394, "description": "Maximum runtime in minutes before the script is terminated. Absent when not configured; if not set the on-device agent applies its own default." } }, "required": [ "script", "interpreter" ] }, "blueprints_BackgroundScriptRead": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the background script" }, "name": { "type": "string", "description": "Name of the background script" }, "interpreter": { "type": "string", "description": "Interpreter used to run the script" }, "always_run": { "type": "boolean", "description": "Whether the script runs continuously" }, "frequency_in_mins": { "type": "integer", "nullable": true, "description": "Interval in minutes between script executions" }, "timeout_in_mins": { "type": "integer", "description": "Maximum runtime in minutes before the script is terminated." }, "description": { "type": "string", "description": "Description of the background script. Empty string if not set." }, "created_at": { "type": "string", "format": "date-time", "description": "When the background script was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the background script was last updated" }, "created_by": { "type": "integer", "description": "User ID who created the background script" }, "updated_by": { "type": "integer", "description": "User ID who last updated the background script" } }, "required": [ "id", "name", "interpreter", "always_run", "timeout_in_mins", "created_at", "updated_at", "created_by", "updated_by" ] }, "blueprints_BackgroundScriptCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Name of the background script" }, "script": { "type": "string", "description": "The script content to be executed on devices" }, "interpreter": { "type": "string", "maxLength": 50, "default": "powershell", "description": "Interpreter used to run the script. Currently only 'powershell' is supported." }, "always_run": { "type": "boolean", "description": "Whether the script runs continuously. When true, frequency_in_mins must be null." }, "frequency_in_mins": { "type": "integer", "nullable": true, "description": "Interval in minutes between script executions. Required when always_run is false, must be null when always_run is true." }, "timeout_in_mins": { "type": "integer", "minimum": 1, "default": 60, "description": "Maximum runtime in minutes before the script is terminated. Must be > 0. Defaults to 60 if omitted." }, "description": { "type": "string", "maxLength": 300, "nullable": true, "description": "Optional description for the background script. Max 300 characters." } }, "required": [ "name", "script", "always_run" ] }, "blueprints_BackgroundScriptDetailRead": { "allOf": [ { "$ref": "#/components/schemas/blueprints_BackgroundScriptRead" }, { "type": "object", "properties": { "script": { "type": "string", "description": "The script content fetched from S3" } }, "required": [ "script" ] } ] }, "pipelines_Pipeline": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "enterprise_id": { "type": "string", "readOnly": true }, "name": { "type": "string" }, "description": { "type": "string" }, "is_active": { "type": "boolean" }, "is_valid": { "type": "boolean" }, "is_visible": { "type": "boolean" }, "is_archived": { "type": "boolean" }, "is_default": { "type": "boolean" }, "timeout_seconds": { "type": "number", "format": "int32" }, "created_by": { "type": "number", "format": "int32" }, "updated_by": { "type": "number", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "name", "created_by", "updated_by" ] }, "pipelines_Pipeline_POST": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "is_default": { "type": "boolean", "default": false }, "is_active": { "type": "boolean", "default": true }, "timeout_seconds": { "type": "number", "format": "int32", "default": 86400 } }, "required": [ "name" ] }, "pipelines_Error_400_Bad_Data": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 400 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "pipelines_Error_401_Unauthorized": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 401 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "pipelines_Pipeline_PUT": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "is_active": { "type": "boolean" }, "is_default": { "type": "boolean" }, "timeout_seconds": { "type": "number", "format": "int32" } } }, "pipelines_Stage": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "enterprise_id": { "type": "string", "readOnly": true }, "pipeline_id": { "type": "string" }, "description": { "type": "string" }, "name": { "type": "string" }, "timeout_seconds": { "type": "number", "format": "int32" }, "created_by": { "type": "number", "format": "int32" }, "updated_by": { "type": "number", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pipelines_Stage_POST": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "timeout_seconds": { "type": "number", "format": "int32" } }, "required": [ "name" ] }, "pipelines_Stage_PUT": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "timeout_seconds": { "type": "number", "format": "int32" } } }, "pipelines_TargetList": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "pipeline_id": { "type": "string" }, "name": { "type": "string" }, "target_list_type": { "type": "string" }, "created_by": { "type": "number", "format": "int32" }, "updated_by": { "type": "number", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pipelines_StageTargetList_POST": { "type": "object", "properties": { "target_list_id": { "type": "string", "format": "uuid" } }, "required": [ "target_list_id" ] }, "pipelines_OperationList": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "pipeline_id": { "type": "string" }, "stage_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "created_by": { "type": "number", "format": "int32" }, "updated_by": { "type": "number", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pipelines_OperationList_POST": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "pipeline_id": { "type": "string", "format": "uuid" } }, "required": [ "name" ] }, "pipelines_TargetList_POST": { "type": "object", "properties": { "name": { "type": "string" }, "target_list_type": { "type": "string", "enum": [ "DEVICES", "GROUPS", "COLLECTIONS" ] } }, "required": [ "name", "target_list_type" ] }, "pipelines_Target": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "pipeline_id": { "type": "string", "format": "uuid" }, "device_id": { "type": "string", "format": "uuid" }, "device_name": { "type": "string" }, "device_alias": { "type": "string" }, "is_active": { "type": "boolean" }, "created_by": { "type": "number", "format": "int32" }, "updated_by": { "type": "number", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pipelines_Target_POST": { "type": "object", "properties": { "device_id": { "type": "string", "format": "uuid" }, "device_alias": { "type": "string" }, "device_name": { "type": "string" }, "is_active": { "type": "boolean" } }, "required": [ "device_id", "device_name" ] }, "pipelines_Target_PUT": { "type": "object", "properties": { "device_name": { "type": "string" }, "is_active": { "type": "boolean" } } }, "pipelines_Error_500_Internal_Server_Error": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 500 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "pipelines_TargetListDeviceGroup": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "device_group_id": { "type": "string" }, "target_list_id": { "type": "string" }, "created_by": { "type": "number", "format": "int32" }, "updated_by": { "type": "number", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pipelines_TargetListDeviceGroups_POST": { "type": "object", "properties": { "device_group_id": { "type": "string", "format": "uuid", "description": "UUID of the Device Group" } } }, "pipelines_Device": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID of the Device" }, "device_name": { "type": "string", "description": "Name of the device" }, "serial": { "type": "string", "description": "Device serial number" }, "template_name": { "type": "string", "description": "Device template name" }, "manufacturer": { "type": "string", "description": "Manufacturer of the Device" }, "android_version": { "type": "string", "description": "Version number of android" }, "api_level": { "type": "string", "description": "Device api level" }, "is_gms": { "type": "boolean", "description": "Is this a gms device" }, "is_active": { "type": "boolean" }, "model": { "type": "string", "description": "Device model number" }, "alias_name": { "type": "string", "description": "Device alias" }, "esper_client": { "type": "string" } } }, "pipelines_Operation": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "operation_list_id": { "type": "string" }, "pipeline_id": { "type": "string" }, "operation_type": { "type": "string" }, "args": { "type": "string" }, "created_by": { "type": "number", "format": "int32" }, "updated_by": { "type": "number", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pipelines_Operation_POST": { "type": "object", "properties": { "args": { "type": "object", "description": "Arguments for the operation" }, "operation_type": { "type": "string", "enum": [ "LOCK", "REBOOT", "SET_NEW_POLICY", "UPDATE_HEARTBEAT", "REQUEST_BUGREPORT", "REQUEST_DPCLOG", "ADD_TO_WHITELIST", "REMOVE_FROM_WHITELIST", "SET_APP_PERMISSION", "WIPE", "CAPTURE_SCREENSHOT", "SET_WIFI_STATE", "SET_BLUETOOTH_STATE", "SET_ROTATION_STATE", "SET_GPS_STATE", "SET_BRIGHTNESS_SCALE", "SET_STREAM_VOLUME", "SET_SCREEN_OFF_TIMEOUT", "SET_ADB_STATE", "INITIATE_OFFER", "INSTALL", "SIMPLE_INSTALL", "UNINSTALL", "REFRESH_APPLIST", "UPDATE_LATEST_DPC", "NOTIFY_OTA", "CLEAR_APP_DATA", "SET_GEO_FENCE", "SET_KIOSK_APP", "SET_DEVICE_LOCKDOWN_STATE", "SET_TIMEZONE", "SET_APP_STATE", "ADD_WIFI_AP", "REMOVE_WIFI_AP", "UPDATE_WIFI_AP", "UPDATE_DEVICE_CONFIG", "INITIATE_CONFERENCE_CALL", "ADD_OVERRIDE_APN", "SYNC_CONTENT", "SET_WALLPAPER" ] } } }, "pipelines_PipelineRun": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "enterprise_id": { "type": "string", "readOnly": true }, "run_number": { "type": "integer", "format": "int32", "readOnly": true }, "pipeline_id": { "type": "string" }, "pipeline_name": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "queued", "processing", "running", "waiting", "complete", "success", "failure", "cancelled", "invalid", "timeout" ] }, "status_meta": { "type": "object" }, "created_by": { "type": "number", "format": "int32" }, "updated_by": { "type": "number", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time" }, "ended_at": { "type": "string", "format": "date-time" } } }, "pipelines_PipelineRun_POST": { "type": "object" }, "pipelines_PipelineRun_PUT": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "queued", "processing", "running", "waiting", "complete", "success", "failure", "cancelled", "invalid", "timeout" ] } } }, "pipelines_StageRun": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "enterprise_id": { "type": "string", "readOnly": true }, "pipeline_id": { "type": "string" }, "pipeline_run_id": { "type": "string" }, "stage_id": { "type": "string" }, "stage_meta": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "created_by": { "type": "number", "format": "int32" } } }, "status": { "type": "string", "enum": [ "pending", "queued", "processing", "running", "complete", "success", "failure", "cancelled", "invalid", "timeout" ] }, "created_by": { "type": "number", "format": "int32" }, "updated_by": { "type": "number", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time" }, "ended_at": { "type": "string", "format": "date-time" } } }, "pipelines_StageRunOperation": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "operation_type": { "type": "string" }, "args": { "type": "string" }, "created_by": { "type": "number", "format": "int32" }, "updated_by": { "type": "number", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pipelines_TargetRun": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "target_id": { "type": "string", "format": "uuid" }, "device_id": { "type": "string", "format": "uuid" }, "device_alias": { "type": "string", "format": "uuid" }, "stage_run_id": { "type": "string", "format": "uuid" }, "stage_run_operation_id": { "type": "string", "format": "uuid" }, "command_id": { "type": "string" }, "command_status": { "type": "string" }, "command_meta": { "type": "object" }, "status": { "type": "string", "enum": [ "pending", "queued", "processing", "dispatched", "running", "complete", "success", "failure", "cancelled", "timeout", "invalid" ] }, "created_by": { "type": "number", "format": "int32" }, "updated_by": { "type": "number", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time" }, "ended_at": { "type": "string", "format": "date-time" } } }, "pipelines_TargetRun_POST": { "type": "object", "properties": { "target_id": { "type": "string", "format": "uuid" }, "device_name": { "type": "string" }, "device_alias": { "type": "string" } }, "required": [ "target_id" ] }, "pipelines_TargetRun_PUT": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "queued", "processing", "dispatched", "running", "complete", "success", "failure", "cancelled", "invalid" ] }, "device_name": { "type": "string" } } }, "pipelines_CommandResponse": { "type": "object", "properties": { "target_run_id": { "type": "string", "format": "uuid" }, "operation_id": { "type": "string", "format": "uuid" }, "enterprise_id": { "type": "string", "format": "uuid" }, "command": { "type": "string" }, "command_type": { "type": "string", "default": "DEVICE" }, "device_type": { "type": "string", "default": "all" }, "device_id": { "type": "string", "format": "uuid" }, "schedule": { "type": "string", "default": "IMMEDIATE" }, "args": { "type": "object" }, "request_id": { "type": "string", "format": "uuid" }, "request_status": { "type": "string" }, "request_status_reason": { "type": "string" } } }, "pipelines_AndroidCommandRequest": { "type": "object" }, "pipelines_CommandRequest_PUT": { "type": "object", "properties": { "request_status": { "type": "string", "enum": [ "cancelled" ] } } }, "pipelines_Error": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "pipelines_Health": { "type": "object", "properties": { "service": { "type": "string" }, "component": { "type": "string" }, "hostname": { "type": "string" } }, "required": [ "service", "component", "hostname" ] }, "device_DeviceStateEnumAndroid": { "type": "integer", "format": "int32", "description": "The following are the device states and their descriptions:\n```\n* 0 = Device State is Unspecified\n* 1 = Online\n* 20 = Disabled (device has been factory reset or removed from the Esper Dashboard)\n* 30 = Beginning Provisioning\n* 40 = Configuring Google Play (still provisioning)\n* 50 = Applying Policies and Installing Applications (still provisioning)\n* 60 = Offline\n* 70 = Device is undergoing a Factory Reset (reset started from Dashboard)\n* 80 = Device Onboarding in Progress\n* 90 = Device Onboarding Failed\n* 100 = Device Onboarded in Esper\n* 110 = Android For Work Account added\n* 120 = Apps installed\n* 130 = Branding Processed\n* 140 = Permission Policy Processed\n* 150 = Device Policy Processed\n* 160 = Device Settings Processed\n* 170 = Security Policy Processed\n* 180 = Phone Policy Processed\n* 190 = Custom Settings Processed\n* 200 = Device is Registered\n```\n", "enum": [ 0, 1, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130, 140, 150, 160, 170, 180, 190, 200 ] }, "device_HardwareInfo": { "type": "object", "properties": { "brand": { "type": "string", "description": "The brand of the device" }, "model": { "type": "string", "description": "The model of the device" }, "model_number": { "type": "string", "description": "The model number of the device" }, "serial": { "type": "string", "description": "The serial number of the device" }, "manufacturer": { "type": "string", "description": "The manufacturer number of the device" }, "hardware": { "type": "string", "description": "The hardware information of the device" }, "device_baseband_version": { "type": "string", "description": "The device baseband version of the device" } } }, "device_FoundationInfo": { "type": "object", "properties": { "major_version": { "type": "string", "description": "The foundation OS build major version of the device" }, "minor_version": { "type": "string", "description": "The foundation OS build minor version of the device" }, "build_number": { "type": "string", "description": "The foundation OS build number of the device" }, "project_name": { "type": "string", "description": "The foundation project name of the device" }, "build_flavor": { "type": "string", "description": "The foundation OS build flavor of the device" }, "variant": { "type": "string", "description": "The foundation variant of the device" }, "foundation_device_model_id": { "type": "string", "description": "The foundation device model id of the device" } } }, "device_AirwaveInfo": { "type": "object", "properties": { "build_number": { "type": "integer", "description": "The airwave OS build number of the device" }, "tenant_model_id": { "type": "string", "description": "The airwave tenant model id of the device" }, "build_id": { "type": "string", "description": "The airwave build id of the device" }, "esper_ota_manager_version_code": { "type": "integer", "description": "The Esper OTA Manager version code" }, "esper_ota_manager_version_name": { "type": "string", "description": "The Esper OTA Manager version name" } } }, "device_SoftwareInfo": { "type": "object", "properties": { "os_version": { "type": "string", "description": "The OS version number of the device" }, "os_build_number": { "type": "string", "description": "The OS build number of the device" }, "bootloader_version": { "type": "string", "description": "The bootloader version of the device" }, "security_path_level": { "type": "string", "description": "The security path level of the device" }, "device_kernel_version": { "type": "string", "description": "The kernel version of the device" }, "eea_version": { "type": "string", "description": "EEA (Esper Enterprise Android) version" }, "esper_agent_info": { "type": "object", "properties": { "version_code": { "type": "string", "description": "Esper agent version code" }, "version_name": { "type": "string", "description": "Esper agent version name" } } }, "foundation_info": { "$ref": "#/components/schemas/device_FoundationInfo" }, "airwave_info": { "$ref": "#/components/schemas/device_AirwaveInfo" } } }, "device_NetworkInfo": { "type": "object", "properties": { "imei1": { "type": "string", "description": "The IMEI number of the device" }, "imei2": { "type": "string", "description": "The IMEI number of the device" }, "wifi_mac_address": { "type": "string", "description": "The wifi mac address of the device" }, "ethernet_mac_address": { "type": "string", "description": "The ethernet mac address of the device" }, "iccid1": { "type": "string", "description": "The ICCID number of the device" }, "iccid2": { "type": "string", "description": "The ICCID number of the device" }, "phone_number_1": { "type": "string", "description": "The phone number of the device" }, "phone_number_2": { "type": "string", "description": "The phone number of the device" }, "network_type": { "type": "string", "description": "The network type of the device", "enum": [ "CELLULAR", "ETHERNET", "WI-FI", "OTHER" ] } } }, "device_MemoryInfo": { "type": "object", "properties": { "total_ram": { "type": "string", "description": "Total ram capacity for the device" }, "total_internal_storage": { "type": "string", "description": "The total internal storage capacity of the device" }, "units": { "type": "string", "description": "The units used for the storage capacity" }, "internal_storage_binary_prefix": { "type": "string", "description": "(Specific to Android devices)" } } }, "device_NetworkStats": { "type": "object", "properties": { "current_active_connection": { "type": "string", "description": "The current active connection type" }, "wifi_network_info": { "type": "object", "properties": { "wifi_ssid": { "type": "string", "description": "The SSID of the WiFi network" } } }, "cellular_network_info": { "type": "object", "properties": { "network_type": { "type": "string", "description": "The network type of the cellular network - null, 2G, 3G, 4G LTE" } } } } }, "device_LocationStats": { "type": "object", "properties": { "altitude": { "type": "string", "description": "The altitude value" }, "latitude": { "type": "string", "description": "The latitude value" }, "longitude": { "type": "string", "description": "The longitude value" } } }, "device_BlueprintInfo": { "type": "object", "properties": { "assigned_blueprint_id": { "type": "string", "description": "Assigned blueprint id of the device" }, "current_blueprint_id": { "type": "string", "description": "Current blueprint id of the blueprint assigned to the device" }, "current_blueprint_version_id": { "type": "string", "description": "Current Version id of the blueprint assigned to the device" }, "blueprint_upgrade_status": { "type": "string", "description": "The status of the blueprint upgrade on the device", "enum": [ "UPGRADABLE", "UPGRADE_INITIATED", "UPGRADE_FAILED", "UPGRADED", "NOT_UPGRADABLE", "NOT_APPLICABLE" ] } } }, "device_AndroidDevice": { "type": "object", "properties": { "timezone_string": { "type": "string", "nullable": true, "readOnly": true, "description": "Device-reported timezone. Null when unavailable.", "example": "America/Los_Angeles" }, "id": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string", "description": "Esper generated name for the device" }, "alias": { "type": "string", "description": "Alias/alternate name for the device" }, "os": { "type": "string", "description": "Operating system for the device", "enum": [ "Android" ] }, "state": { "$ref": "#/components/schemas/device_DeviceStateEnumAndroid" }, "platform": { "type": "string", "description": "Platform for the device", "enum": [ "ANDROID" ] }, "serial": { "type": "string", "description": "Serial number the device" }, "os_version": { "type": "string", "description": "OS version the device" }, "global_device_id": { "type": "string", "description": "Esper generated unique id for the device" }, "tenant_id": { "type": "string", "format": "uuid", "readOnly": true }, "group_id": { "type": "string", "format": "uuid", "readOnly": true }, "onboarded_on": { "type": "string", "format": "date-time" }, "provisioned_on": { "type": "string", "format": "date-time" }, "hardware_info": { "$ref": "#/components/schemas/device_HardwareInfo" }, "software_info": { "$ref": "#/components/schemas/device_SoftwareInfo" }, "network_info": { "$ref": "#/components/schemas/device_NetworkInfo" }, "memory_info": { "$ref": "#/components/schemas/device_MemoryInfo" }, "network_stats": { "$ref": "#/components/schemas/device_NetworkStats" }, "location_stats:": { "$ref": "#/components/schemas/device_LocationStats" }, "blueprint_info": { "$ref": "#/components/schemas/device_BlueprintInfo" }, "battery_stats": { "type": "object", "properties": { "battery_level": { "type": "number", "description": "Current battery level of the device" } } }, "mqtt_topic": { "type": "string", "description": "MQTT topic" }, "fcm_id": { "type": "string" }, "is_gms": { "type": "boolean" }, "policy": { "nullable": true, "description": "Policy associated with the device", "type": "object", "properties": { "policy_id": { "type": "integer" }, "policy_name": { "type": "string" } } }, "managed_by": { "type": "string", "description": "Whether the device is managed by blueprint or template", "enum": [ "BLUEPRINT", "TEMPLATE" ] }, "template_name": { "nullable": true, "type": "string", "description": "Name of the template the device is managed by" }, "is_seamless": { "type": "boolean" }, "is_esper_managed": { "type": "boolean", "nullable": true, "readOnly": true, "description": "Indicates if the device is Esper managed" }, "created_by": { "type": "string" }, "updated_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "device_DeviceStateEnumApple": { "type": "integer", "format": "int32", "description": "The following are the device states and their descriptions:\n```\n* 0 = Device State is Unspecified\n* 1 = Online/Active\n* 20 = Disabled (device has been factory reset or removed from the Esper Dashboard)\n* 70 = Device is undergoing a Factory Reset (reset started from Dashboard)\n* 80 = Device Onboarding in Progress\n* 90 = Device Onboarding Failed\n* 100 = Device Onboarded in Esper\n* 200 = Device is Registered\n```\n", "enum": [ 0, 1, 20, 70, 80, 90, 100, 200 ] }, "device_AppModeMeta": { "type": "object", "nullable": true, "minProperties": 1, "description": "App mode configuration for the device (kiosk / multi-app)", "properties": { "is_kiosk": { "type": "boolean", "nullable": true, "description": "Whether the device is in kiosk mode" }, "app_id": { "type": "string", "format": "uuid", "description": "Application UUID identifier for kiosk mode. For Android, this is the DeviceApp UUID (not available for older DPCs)." }, "app_type": { "type": "string", "description": "Application type for kiosk mode", "enum": [ "TENANT_IOS", "ESPER_IOS", "VPP", "WEBCLIP", "ESPER_ANDROID", "ESPER_WINDOWS", "TENANT_WINDOWS", "ESPER_LINUX", "TENANT_WINDOWS_EXE", "TENANT_ANDROID", "GOOGLE_ANDROID", "PRELOADED_ANDROID", "TENANT_WINDOWS_UWP" ] }, "disable_device_rotation": { "type": "boolean", "nullable": true, "description": "Disable device rotation sensing while in kiosk mode (iOS only). Only meaningful alongside one of is_kiosk / app_id / app_type — a payload containing only disable_device_rotation is rejected." }, "disable_screen_timeout": { "type": "boolean", "nullable": true, "description": "Disable screen timeout while in kiosk mode (Apple only). Only meaningful alongside one of is_kiosk / app_id / app_type — a payload containing only disable_screen_timeout is rejected." }, "kiosk_mode_type": { "type": "string", "description": "Kiosk configuration mode. Currently only supported on Windows devices. Requires is_kiosk to be true.", "enum": [ "SHELL_LAUNCHER", "CONFIGURATION" ] }, "application_path": { "type": "string", "description": "WIN32 executable path for the kiosk app. Only applicable when kiosk_mode_type is SHELL_LAUNCHER or CONFIGURATION with a WIN32 app." }, "application_args": { "type": "string", "description": "Command-line arguments for the WIN32 kiosk app." } }, "anyOf": [ { "required": [ "is_kiosk" ] }, { "required": [ "app_id" ] }, { "required": [ "app_type" ] } ], "allOf": [ { "anyOf": [ { "not": { "required": [ "application_path" ] } }, { "required": [ "kiosk_mode_type" ] } ] }, { "anyOf": [ { "not": { "required": [ "application_args" ] } }, { "required": [ "kiosk_mode_type" ] } ] } ] }, "device_AppleDevice": { "type": "object", "properties": { "timezone_string": { "type": "string", "nullable": true, "readOnly": true, "description": "Device-reported timezone. Null when unavailable.", "example": "America/Los_Angeles" }, "id": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string", "description": "Esper generated name for the device" }, "alias": { "type": "string", "description": "Alias/alternate name for the device" }, "os": { "type": "string", "description": "Operating system for the device", "enum": [ "iOS", "iPadOS", "tvOS" ] }, "state": { "$ref": "#/components/schemas/device_DeviceStateEnumApple" }, "platform": { "type": "string", "description": "Platform for the device", "enum": [ "APPLE" ] }, "serial": { "type": "string", "description": "Serial number the device" }, "os_version": { "type": "string", "description": "OS version the device" }, "global_device_id": { "type": "string", "description": "Esper generated unique id for the device" }, "tenant_id": { "type": "string", "format": "uuid", "readOnly": true }, "group_id": { "type": "string", "format": "uuid", "readOnly": true }, "hardware_info": { "$ref": "#/components/schemas/device_HardwareInfo" }, "software_info": { "$ref": "#/components/schemas/device_SoftwareInfo" }, "network_info": { "$ref": "#/components/schemas/device_NetworkInfo" }, "memory_info": { "$ref": "#/components/schemas/device_MemoryInfo" }, "blueprint_info": { "$ref": "#/components/schemas/device_BlueprintInfo" }, "udid": { "type": "string", "description": "UDID as provided by apple" }, "dep_profile": { "type": "string", "description": "DEP profile applied to device" }, "dep_profile_push_time": { "type": "string", "format": "date-time" }, "dep_profile_assign_time": { "type": "string", "format": "date-time" }, "dep_profile_status": { "type": "string", "description": "DEP profile applied to device", "enum": [ "empty", "assigned", "pushed", "removed" ] }, "enrolment_info": { "type": "object", "properties": { "enrolment_id": { "type": "string", "description": "The per-enrollment identifier for the device" }, "enrolment_user_id": { "type": "string", "description": "The per-enrollment identifier for the user" } } }, "last_seen": { "type": "string", "format": "date-time" }, "tokens": { "type": "object", "properties": { "push_magic": { "type": "string" }, "push_token": { "type": "string" }, "device_token": { "type": "string" } } }, "device_source": { "type": "string", "description": "Source of device onboarding", "enum": [ "ABM", "NON_ABM" ] }, "is_supervised": { "type": "boolean" }, "is_ddm_enabled": { "type": "boolean", "description": "Whether Declarative Device Management is enabled for this device" }, "managed_by": { "type": "string", "description": "Whether the device is managed by blueprint or template", "enum": [ "BLUEPRINT" ] }, "onboarded_on": { "type": "string", "format": "date-time" }, "provisioned_on": { "type": "string", "format": "date-time" }, "is_seamless": { "type": "boolean" }, "app_mode_meta": { "nullable": true, "$ref": "#/components/schemas/device_AppModeMeta" }, "created_by": { "type": "string" }, "updated_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "device_DeviceStateEnumLinux": { "type": "integer", "format": "int32", "description": "The following are the device states and their descriptions:\n```\n* 0 = Device State is Unspecified\n* 1 = Online/Active\n* 20 = Disabled (device has been factory reset or removed from the Esper Dashboard)\n* 70 = Device Wipe in Progress\n* 80 = Device Onboarding in Progress\n* 90 = Device Onboarding Failed\n* 100 = Device Onboarded in Esper\n* 200 = Device is Registered\n```\n", "enum": [ 0, 1, 20, 70, 80, 90, 100, 200 ] }, "device_LinuxBlueprintInfo": { "type": "object", "properties": { "assigned_blueprint_id": { "type": "string", "description": "Assigned blueprint id of the device" }, "current_blueprint_id": { "type": "string", "description": "Current blueprint id of the blueprint assigned to the device" }, "current_blueprint_version_id": { "type": "string", "description": "Current Version id of the blueprint assigned to the device" }, "blueprint_upgrade_status": { "type": "string", "description": "The status of the blueprint upgrade on the device", "enum": [ "NOT_APPLICABLE" ] } } }, "device_LinuxDevice": { "type": "object", "properties": { "timezone_string": { "type": "string", "nullable": true, "readOnly": true, "description": "Device-reported timezone. Null when unavailable.", "example": "America/Los_Angeles" }, "id": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string", "description": "Esper generated name for the device" }, "os": { "type": "string", "description": "Operating system for the device", "enum": [ "Ubuntu" ] }, "state": { "$ref": "#/components/schemas/device_DeviceStateEnumLinux" }, "platform": { "type": "string", "description": "Operating system for the device", "enum": [ "LINUX" ] }, "serial": { "type": "string", "description": "Serial number the device" }, "os_version": { "type": "string", "description": "OS version the device" }, "global_device_id": { "type": "string", "description": "Esper generated unique id for the device" }, "tenant_id": { "type": "string", "format": "uuid", "readOnly": true }, "group_id": { "type": "string", "format": "uuid", "readOnly": true }, "onboarded_on": { "type": "string", "format": "date-time" }, "provisioned_on": { "type": "string", "format": "date-time" }, "blueprint_info": { "$ref": "#/components/schemas/device_LinuxBlueprintInfo" }, "managed_by": { "type": "string", "description": "Whether the device is managed by blueprint or template", "enum": [ "BLUEPRINT" ] }, "is_seamless": { "type": "boolean" }, "created_by": { "type": "string" }, "updated_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "device_DeviceStateEnumWindows": { "type": "integer", "format": "int32", "description": "The following are the device states and their descriptions:\n```\n* 0 = Device State is Unspecified\n* 1 = Online/Active\n* 20 = Disabled (device has been factory reset or removed from the Esper Dashboard)\n* 70 = Device Wipe in Progress\n* 80 = Device Onboarding in Progress\n* 90 = Device Onboarding Failed\n* 100 = Device Onboarded in Esper\n* 200 = Device is Registered\n```\n", "enum": [ 0, 1, 20, 70, 80, 90, 100, 200 ] }, "device_WindowsHardwareInfo": { "type": "object", "properties": { "brand": { "type": "string", "description": "Device brand" }, "model": { "type": "string", "description": "Device model" }, "serial": { "type": "string", "description": "Device serial number" }, "manufacturer": { "type": "string", "description": "Device manufacturer" }, "hardware": { "type": "string", "description": "Hardware information" } } }, "device_WindowsSoftwareInfo": { "type": "object", "properties": { "supported_abi": { "type": "string", "description": "Supported ABI" }, "os_build_time": { "type": "string", "description": "OS build time" }, "os_build_number": { "type": "string", "description": "OS build number" }, "os_version": { "type": "string", "description": "OS version" }, "os": { "type": "string", "description": "OS name" }, "os_platform": { "type": "string", "description": "OS platform" }, "os_distribution": { "type": "string", "description": "OS distribution" }, "bootloader_version": { "type": "string", "description": "Bootloader version" }, "kernel_architecture": { "type": "string", "description": "Kernel architecture" }, "device_kernel_version": { "type": "string", "description": "Device kernel version" }, "last_boot_time": { "type": "string", "description": "Last boot time" }, "display_resolution": { "type": "string", "description": "Display resolution" }, "display_refresh_rate": { "type": "string", "description": "Display refresh rate" }, "host_name": { "type": "string", "description": "Device host name" }, "esper_agent_info": { "type": "object", "properties": { "version_code": { "type": "string", "description": "Esper agent version code" }, "version_name": { "type": "string", "description": "Esper agent version name" } } } } }, "device_WindowsNetworkInfo": { "type": "object", "properties": { "wifi_mac_address": { "type": "string", "description": "Wi-Fi MAC address" }, "ethernet_mac_address": { "type": "string", "description": "Ethernet MAC address" } } }, "device_WindowsMemoryInfo": { "type": "object", "properties": { "total_ram": { "type": "string", "description": "Total RAM in bytes" }, "total_internal_storage": { "type": "string", "description": "Total internal storage in bytes" }, "total_swap_memory": { "type": "string", "description": "Total swap memory in bytes" }, "units": { "type": "string", "description": "Units used for the storage capacity" } } }, "device_WindowsDevice": { "type": "object", "properties": { "timezone_string": { "type": "string", "nullable": true, "readOnly": true, "description": "Device-reported timezone. Null when unavailable.", "example": "America/Los_Angeles" }, "id": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string", "description": "Esper generated name for the device" }, "os": { "type": "string", "description": "Operating system of the device", "enum": [ "Windows" ] }, "state": { "$ref": "#/components/schemas/device_DeviceStateEnumWindows" }, "platform": { "type": "string", "description": "Operating system of the device", "enum": [ "WINDOWS" ] }, "serial": { "type": "string", "description": "Serial number of the device" }, "os_version": { "type": "string", "description": "OS version of the device" }, "global_device_id": { "type": "string", "description": "Windows generated unique id for the device" }, "tenant_id": { "type": "string", "format": "uuid", "readOnly": true }, "group_id": { "type": "string", "format": "uuid", "readOnly": true }, "onboarded_on": { "type": "string", "format": "date-time" }, "provisioned_on": { "type": "string", "format": "date-time" }, "blueprint_info": { "$ref": "#/components/schemas/device_BlueprintInfo" }, "hardware_info": { "$ref": "#/components/schemas/device_WindowsHardwareInfo" }, "software_info": { "$ref": "#/components/schemas/device_WindowsSoftwareInfo" }, "network_info": { "$ref": "#/components/schemas/device_WindowsNetworkInfo" }, "memory_info": { "$ref": "#/components/schemas/device_WindowsMemoryInfo" }, "managed_by": { "type": "string", "description": "Whether the device is managed by blueprint or template", "enum": [ "BLUEPRINT" ] }, "is_seamless": { "type": "boolean" }, "windows_config": { "type": "object", "properties": { "channel_uri": { "type": "string", "description": "Channel URI for the device" }, "channel_updated_at": { "type": "string", "format": "date-time", "description": "Last updated time of the channel URI" } } }, "app_mode_meta": { "nullable": true, "$ref": "#/components/schemas/device_AppModeMeta" }, "created_by": { "type": "string" }, "updated_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "device_Error_401_Unauthorized": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 401 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "device_Error_500_Internal_Server_Error": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 500 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "device_Error_400_Bad_Data": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 400 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "device_Error_404_Not_Found": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 404 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "device_DeviceSettings": { "type": "object", "properties": { "gps_state": { "type": "string", "description": "GPS state of the device", "enum": [ "LOCATION_MODE_HIGH_ACCURACY", "LOCATION_MODE_SENSORS_ONLY", "LOCATION_MODE_BATTERY_SAVING", "LOCATION_MODE_OFF", "LOCATION_MODE_ON" ] }, "wifi_state": { "type": "boolean", "description": "WiFi state of the device" }, "adb_enabled": { "type": "boolean", "description": "ADB state of the device" }, "adb_timeout": { "type": "integer", "description": "ADB timeout value for the device" }, "remote_adb_enabled": { "type": "boolean", "description": "Remote ADB state for the device" }, "remote_adb_ip": { "type": "string", "description": "Remote ADB IP for the device" }, "remote_adb_port": { "type": "integer", "description": "Remote ADB port for the device" }, "audio_settings": { "type": "object", "description": "Different Audio types and respective values" }, "rotation_state": { "type": "string", "description": "Display rotation of the device", "enum": [ "AUTO", "PORTRAIT_ONLY", "LANDSCAPE_ONLY", "INVERTED_PORTRAIT_ONLY", "INVERTED_LANDSCAPE_ONLY" ] }, "bluetooth_state": { "type": "boolean", "description": "Bluetooth state of device" }, "brightness_scale": { "type": "integer", "description": "Brightness value for the device it will be in range 0 to 100" }, "screen_off_timeout": { "type": "integer", "description": "Device screen off timeout" }, "use_only_saved_ap": { "type": "boolean", "description": "Whether device is allowed to connect to only saved Wifi APs" } } }, "device_NetworkStatsV2": { "type": "object", "properties": { "current_active_connection": { "type": "string", "description": "The current active connection type" }, "wifi_network_info": { "type": "object", "properties": { "wifi_ssid": { "type": "string", "description": "The SSID of the WiFi network" }, "wifi_signal_strength": { "type": "integer", "description": "The signal strength of the WiFi network on a scale of 0 to 5" } } }, "cellular_network_info": { "type": "object", "properties": { "network_type": { "type": "string", "description": "The network type of the cellular network - null, 2G, 3G, 4G LTE" } } }, "ip_address": { "type": "array", "items": { "type": "string" }, "description": "The IP address of the device" } } }, "device_MemoryStats": { "type": "object", "properties": { "available_ram": { "type": "integer", "description": "The available memory value" }, "available_internal_storage": { "type": "integer", "description": "The available internal storage value" }, "os_occupied_storage": { "type": "integer", "description": "The OS occupied storage value" } } }, "device_AndroidDeviceV2": { "type": "object", "properties": { "timezone_string": { "type": "string", "nullable": true, "readOnly": true, "description": "Device-reported timezone. Null when unavailable.", "example": "America/Los_Angeles" }, "id": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string", "description": "Esper generated name for the device" }, "alias": { "type": "string", "description": "Alias/alternate name for the device" }, "os": { "type": "string", "description": "Operating system for the device", "enum": [ "Android" ] }, "state": { "$ref": "#/components/schemas/device_DeviceStateEnumAndroid" }, "platform": { "type": "string", "description": "Platform for the device", "enum": [ "ANDROID" ] }, "serial": { "type": "string", "description": "Serial number the device" }, "os_version": { "type": "string", "description": "OS version the device" }, "global_device_id": { "type": "string", "description": "Esper generated unique id for the device" }, "tenant_id": { "type": "string", "format": "uuid", "readOnly": true }, "group_id": { "type": "string", "format": "uuid", "readOnly": true }, "provisioned_on": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Array of UUIDs representing tags associated with the device" }, "hardware_info": { "$ref": "#/components/schemas/device_HardwareInfo" }, "software_info": { "$ref": "#/components/schemas/device_SoftwareInfo" }, "network_info": { "$ref": "#/components/schemas/device_NetworkInfo" }, "memory_info": { "$ref": "#/components/schemas/device_MemoryInfo" }, "network_stats": { "$ref": "#/components/schemas/device_NetworkStatsV2" }, "location_stats": { "$ref": "#/components/schemas/device_LocationStats" }, "memory_stats": { "$ref": "#/components/schemas/device_MemoryStats" }, "blueprint_info": { "$ref": "#/components/schemas/device_BlueprintInfo" }, "battery_stats": { "type": "object", "properties": { "battery_level": { "type": "number", "description": "Current battery level of the device" } } }, "mqtt_topic": { "type": "string", "description": "MQTT topic" }, "fcm_id": { "type": "string" }, "is_gms": { "type": "boolean" }, "dpc_version": { "nullable": true, "type": "string", "description": "DPC (Device Policy Controller) version / Esper agent version name" }, "eea_version": { "nullable": true, "type": "string", "description": "EEA (Esper Enterprise Android) version" }, "policy": { "nullable": true, "description": "Policy associated with the device", "type": "object", "properties": { "policy_id": { "type": "integer" }, "policy_name": { "type": "string" } } }, "managed_by": { "type": "string", "description": "Whether the device is managed by blueprint or template", "enum": [ "BLUEPRINT", "TEMPLATE" ] }, "provisioned_with": { "type": "string", "description": "Whether the device was provisioned with blueprint or template", "enum": [ "BLUEPRINT", "TEMPLATE" ] }, "template_name": { "nullable": true, "type": "string", "description": "Name of the template the device is managed by" }, "is_seamless": { "type": "boolean" }, "is_esper_managed": { "type": "boolean", "nullable": true, "readOnly": true, "description": "Indicates if the device is Esper managed" }, "app_mode_meta": { "nullable": true, "$ref": "#/components/schemas/device_AppModeMeta" }, "created_by": { "type": "string" }, "updated_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "device_AppleDeviceV2": { "type": "object", "properties": { "timezone_string": { "type": "string", "nullable": true, "readOnly": true, "description": "Device-reported timezone. Null when unavailable.", "example": "America/Los_Angeles" }, "id": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string", "description": "Esper generated name for the device" }, "alias": { "type": "string", "description": "Alias/alternate name for the device" }, "os": { "type": "string", "description": "Operating system for the device", "enum": [ "iOS", "iPadOS", "tvOS" ] }, "state": { "$ref": "#/components/schemas/device_DeviceStateEnumApple" }, "platform": { "type": "string", "description": "Platform for the device", "enum": [ "APPLE" ] }, "serial": { "type": "string", "description": "Serial number the device" }, "os_version": { "type": "string", "description": "OS version the device" }, "global_device_id": { "type": "string", "description": "Esper generated unique id for the device" }, "tenant_id": { "type": "string", "format": "uuid", "readOnly": true }, "group_id": { "type": "string", "format": "uuid", "readOnly": true }, "tags": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Array of UUIDs representing tags associated with the device" }, "hardware_info": { "$ref": "#/components/schemas/device_HardwareInfo" }, "software_info": { "$ref": "#/components/schemas/device_SoftwareInfo" }, "network_info": { "$ref": "#/components/schemas/device_NetworkInfo" }, "memory_info": { "$ref": "#/components/schemas/device_MemoryInfo" }, "blueprint_info": { "$ref": "#/components/schemas/device_BlueprintInfo" }, "udid": { "type": "string", "description": "UDID as provided by apple" }, "dep_profile": { "type": "string", "description": "DEP profile applied to device" }, "dep_profile_push_time": { "type": "string", "format": "date-time" }, "dep_profile_assign_time": { "type": "string", "format": "date-time" }, "dep_profile_status": { "type": "string", "description": "DEP profile applied to device", "enum": [ "empty", "assigned", "pushed", "removed" ] }, "enrolment_info": { "type": "object", "properties": { "enrolment_id": { "type": "string", "description": "The per-enrollment identifier for the device" }, "enrolment_user_id": { "type": "string", "description": "The per-enrollment identifier for the user" } } }, "last_seen": { "type": "string", "format": "date-time" }, "tokens": { "type": "object", "properties": { "push_magic": { "type": "string" }, "push_token": { "type": "string" }, "device_token": { "type": "string" } } }, "is_supervised": { "type": "boolean" }, "device_source": { "type": "string", "description": "Source of device onboarding", "enum": [ "ABM", "NON_ABM" ] }, "managed_by": { "type": "string", "description": "Whether the device is managed by blueprint or template", "enum": [ "BLUEPRINT" ] }, "provisioned_with": { "type": "string", "description": "Whether the device was provisioned with blueprint or template", "enum": [ "BLUEPRINT" ] }, "provisioned_on": { "type": "string", "format": "date-time" }, "is_seamless": { "type": "boolean" }, "is_locked_down": { "type": "boolean" }, "is_ddm_enabled": { "type": "boolean", "description": "Whether Declarative Device Management is enabled for this device" }, "app_mode_meta": { "nullable": true, "$ref": "#/components/schemas/device_AppModeMeta" }, "created_by": { "type": "string" }, "updated_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "memory_stats": { "type": "object", "properties": { "total_memory": { "type": "integer", "format": "int64", "description": "Total memory in bytes" }, "total_internal_storage": { "type": "integer", "format": "int64", "description": "Total internal storage in bytes" }, "available_ram": { "type": "integer", "format": "int64", "description": "Available RAM in bytes" }, "available_internal_storage": { "type": "integer", "format": "int64", "description": "Available internal storage in bytes" } } }, "battery_stats": { "type": "object", "properties": { "battery_level": { "type": "number", "description": "Current battery level of the device" } } }, "updated_at": { "type": "string", "format": "date-time" } } }, "device_LinuxDeviceV2": { "type": "object", "properties": { "timezone_string": { "type": "string", "nullable": true, "readOnly": true, "description": "Device-reported timezone. Null when unavailable.", "example": "America/Los_Angeles" }, "id": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string", "description": "Esper generated name for the device" }, "alias": { "type": "string", "description": "Alias/alternate name for the device" }, "os": { "type": "string", "description": "Operating system for the device", "enum": [ "ubuntu", "Ubuntu", "Linux" ] }, "state": { "$ref": "#/components/schemas/device_DeviceStateEnumLinux" }, "platform": { "type": "string", "description": "Platform for the device", "enum": [ "LINUX" ] }, "serial": { "type": "string", "description": "Serial number the device" }, "os_version": { "type": "string", "description": "OS version the device" }, "global_device_id": { "type": "string", "description": "Esper generated unique id for the device" }, "tenant_id": { "type": "string", "format": "uuid", "readOnly": true }, "group_id": { "type": "string", "format": "uuid", "readOnly": true }, "provisioned_on": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Array of UUIDs representing tags associated with the device" }, "hardware_info": { "type": "object", "properties": { "brand": { "type": "string", "description": "Device brand" }, "model": { "type": "string", "description": "Device model" }, "serial": { "type": "string", "description": "Device serial number" }, "manufacturer": { "type": "string", "description": "Device manufacturer" }, "hardware": { "type": "string", "description": "Hardware information" } } }, "software_info": { "type": "object", "properties": { "supported_abi": { "type": "string", "description": "Supported ABI" }, "os_build_time": { "type": "integer", "format": "int64", "description": "OS build time timestamp" }, "os_build_number": { "type": "string", "description": "OS build number" }, "os_version": { "type": "string", "description": "OS version" }, "os": { "type": "string", "description": "OS name" }, "os_platform": { "type": "string", "description": "OS platform" }, "os_distribution": { "type": "string", "description": "OS distribution" }, "bootloader_version": { "type": "string", "description": "Bootloader version" }, "kernel_architecture": { "type": "string", "description": "Kernel architecture" }, "device_kernel_version": { "type": "string", "description": "Device kernel version" }, "last_boot_time": { "type": "string", "description": "Last boot time" }, "display_resolution": { "type": "string", "description": "Display resolution" }, "display_refresh_rate": { "type": "string", "description": "Display refresh rate" }, "esper_agent_info": { "type": "object", "properties": { "version_code": { "type": "string", "description": "Esper agent version code" }, "version_name": { "type": "string", "description": "Esper agent version name" } } } } }, "network_info": { "type": "object", "properties": { "wifi_mac_address": { "type": "string", "description": "Wi-Fi MAC address" }, "ethernet_mac_address": { "type": "string", "description": "Ethernet MAC address" } } }, "memory_info": { "type": "object", "properties": { "total_ram": { "type": "string", "description": "Total RAM in bytes" }, "total_internal_storage": { "type": "string", "description": "Total internal storage in bytes" }, "total_swap_memory": { "type": "string", "description": "Total swap memory in bytes" }, "units": { "type": "string", "description": "Units used for the storage capacity" } } }, "network_stats": { "type": "object", "properties": { "dns_servers": { "type": "array", "items": { "type": "string" }, "description": "DNS servers" }, "default_gateway": { "type": "string", "description": "Default gateway" }, "ethernet_ip_address": { "type": "string", "description": "Ethernet IP address" }, "current_active_connection": { "type": "string", "description": "The current active connection type" }, "wifi_network_info": { "type": "object", "properties": { "wifi_ssid": { "type": "string", "description": "The SSID of the WiFi network" }, "wifi_signal_strength": { "type": "integer", "description": "The signal strength of the WiFi network" }, "wifi_ip_address": { "type": "string", "description": "The IP address of the WiFi network" } } }, "ip_address": { "type": "array", "items": { "type": "string" }, "description": "The IP address of the device" } } }, "memory_stats": { "type": "object", "properties": { "total_memory": { "type": "integer", "format": "int64", "description": "Total memory in bytes" }, "total_internal_storage": { "type": "integer", "format": "int64", "description": "Total internal storage in bytes" }, "total_swap_memory": { "type": "integer", "format": "int64", "description": "Total swap memory in bytes" }, "available_ram": { "type": "integer", "format": "int64", "description": "The available memory value" }, "available_internal_storage": { "type": "integer", "format": "int64", "description": "The available internal storage value" }, "available_swap_memory": { "type": "integer", "format": "int64", "description": "The available swap memory value" }, "units": { "type": "string", "description": "The units used for the storage capacity" } } }, "cpu_stats": { "type": "object", "properties": { "cpu_counts": { "type": "integer", "description": "Number of CPU cores" }, "cpu_cores": { "type": "array", "items": { "type": "number", "format": "float" }, "description": "CPU core usage percentages" }, "cpu_temperature": { "type": "number", "format": "float", "description": "CPU temperature" }, "total_percent": { "type": "number", "format": "float", "description": "Total CPU usage percentage" } } }, "battery_stats": { "type": "object", "properties": { "battery_present": { "type": "boolean", "description": "Whether battery is present" }, "battery_state": { "type": "string", "description": "Battery state" }, "battery_energy": { "type": "number", "format": "float", "description": "Battery energy" }, "battery_energy_full": { "type": "number", "format": "float", "description": "Battery full energy" }, "battery_energy_full_design": { "type": "number", "format": "float", "description": "Battery design full energy" }, "battery_level": { "type": "number", "format": "int32", "description": "Battery level" }, "battery_technology": { "type": "string", "description": "Battery technology" }, "battery_voltage": { "type": "number", "format": "float", "description": "Battery voltage" }, "battery_health": { "type": "number", "format": "float", "description": "Battery health percentage" }, "battery_temperature": { "type": "number", "format": "float", "description": "Battery temperature" } } }, "location_stats": { "type": "object", "properties": { "latitude": { "type": "number", "format": "float", "description": "Device latitude" }, "longitude": { "type": "number", "format": "float", "description": "Device longitude" }, "altitude": { "type": "number", "format": "float", "description": "Device altitude" }, "accuracy": { "type": "number", "format": "float", "description": "Location accuracy" } } }, "blueprint_info": { "$ref": "#/components/schemas/device_LinuxBlueprintInfo" }, "managed_by": { "type": "string", "description": "Whether the device is managed by blueprint or template", "enum": [ "BLUEPRINT" ] }, "provisioned_with": { "type": "string", "description": "Whether the device was provisioned with blueprint or template", "enum": [ "BLUEPRINT" ] }, "is_seamless": { "type": "boolean" }, "last_seen": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "updated_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "device_WindowsBlueprintInfo": { "type": "object", "properties": { "assigned_blueprint_id": { "type": "string", "description": "Assigned blueprint id of the device" }, "current_blueprint_id": { "type": "string", "description": "Current blueprint id of the blueprint assigned to the device" }, "current_blueprint_version_id": { "type": "string", "description": "Current Version id of the blueprint assigned to the device" }, "blueprint_upgrade_status": { "type": "string", "description": "The status of the blueprint upgrade on the device", "enum": [ "NOT_APPLICABLE" ] } } }, "device_WindowsDeviceV2": { "type": "object", "properties": { "timezone_string": { "type": "string", "nullable": true, "readOnly": true, "description": "Device-reported timezone. Null when unavailable.", "example": "America/Los_Angeles" }, "id": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string", "description": "Esper generated name for the device" }, "alias": { "type": "string", "description": "Alias/alternate name for the device" }, "os": { "type": "string", "description": "Operating system for the device", "enum": [ "Windows" ] }, "state": { "$ref": "#/components/schemas/device_DeviceStateEnumWindows" }, "platform": { "type": "string", "description": "Platform for the device", "enum": [ "WINDOWS" ] }, "serial": { "type": "string", "description": "Serial number the device" }, "os_version": { "type": "string", "description": "OS version the device" }, "global_device_id": { "type": "string", "description": "Windows generated unique id for the device" }, "tenant_id": { "type": "string", "format": "uuid", "readOnly": true }, "group_id": { "type": "string", "format": "uuid", "readOnly": true }, "provisioned_on": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Array of UUIDs representing tags associated with the device" }, "hardware_info": { "$ref": "#/components/schemas/device_WindowsHardwareInfo" }, "software_info": { "$ref": "#/components/schemas/device_WindowsSoftwareInfo" }, "network_info": { "$ref": "#/components/schemas/device_WindowsNetworkInfo" }, "memory_info": { "$ref": "#/components/schemas/device_WindowsMemoryInfo" }, "network_stats": { "type": "object", "properties": { "dns_servers": { "type": "array", "items": { "type": "string" }, "description": "DNS servers" }, "default_gateway": { "type": "string", "description": "Default gateway" }, "ethernet_ip_address": { "type": "string", "description": "Ethernet IP address" }, "current_active_connection": { "type": "string", "description": "The current active connection type" }, "wifi_network_info": { "type": "object", "properties": { "wifi_ssid": { "type": "string", "description": "The SSID of the WiFi network" }, "wifi_signal_strength": { "type": "integer", "description": "The signal strength of the WiFi network" }, "wifi_ip_address": { "type": "string", "description": "The IP address of the WiFi network" } } }, "ip_address": { "type": "array", "items": { "type": "string" }, "description": "The IP address of the device" } } }, "memory_stats": { "type": "object", "properties": { "total_memory": { "type": "integer", "format": "int64", "description": "Total memory in bytes" }, "total_internal_storage": { "type": "integer", "format": "int64", "description": "Total internal storage in bytes" }, "available_ram": { "type": "integer", "format": "int64", "description": "The available memory value" }, "available_internal_storage": { "type": "integer", "format": "int64", "description": "The available internal storage value" }, "units": { "type": "string", "description": "The units used for the storage capacity" } } }, "cpu_stats": { "type": "object", "properties": { "cpu_counts": { "type": "integer", "description": "Number of CPU cores" }, "cpu_cores": { "type": "array", "items": { "type": "number", "format": "float" }, "description": "CPU core usage percentages" }, "cpu_temperature": { "type": "number", "format": "float", "description": "CPU temperature" } } }, "last_seen": { "type": "string", "format": "date-time", "description": "Last time the device was seen" }, "blueprint_info": { "$ref": "#/components/schemas/device_WindowsBlueprintInfo" }, "battery_stats": { "type": "object", "properties": { "battery_level": { "type": "number", "description": "Current battery level of the device" } } }, "background_scripts_stats": { "type": "object", "description": "Telemetry for Windows background scripts; object keys are background script UUIDs", "additionalProperties": { "type": "object", "properties": { "current_state": { "type": "string", "description": "Current execution state of the background script" }, "script_output": { "type": "string", "description": "Latest script output or logs" }, "reason": { "type": "string", "description": "Optional human-readable reason (e.g. failure or state change context)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last updated time of background script state on the device" } } } }, "provisioned_with": { "type": "string", "description": "Whether the device was provisioned with blueprint or template", "enum": [ "BLUEPRINT" ] }, "is_seamless": { "type": "boolean" }, "windows_config": { "type": "object", "properties": { "channel_uri": { "type": "string", "description": "Channel URI for the device" }, "channel_updated_at": { "type": "string", "format": "date-time", "description": "Last updated time of the channel URI" } } }, "app_mode_meta": { "nullable": true, "$ref": "#/components/schemas/device_AppModeMeta" }, "created_by": { "type": "string" }, "updated_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "device_OffsetPaginatedDeviceList": { "type": "object", "description": "Response format for offset-based pagination", "properties": { "count": { "type": "integer", "description": "Total number of devices matching the query" }, "previous": { "type": "string", "nullable": true, "description": "URL to the previous page of results" }, "next": { "type": "string", "nullable": true, "description": "URL to the next page of results" }, "results": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/device_AndroidDeviceV2" }, { "$ref": "#/components/schemas/device_AppleDeviceV2" }, { "$ref": "#/components/schemas/device_LinuxDeviceV2" }, { "$ref": "#/components/schemas/device_WindowsDeviceV2" } ] } } } }, "device_CursorPaginatedDeviceList": { "type": "object", "description": "Response format for cursor-based pagination", "properties": { "results": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/device_AndroidDeviceV2" }, { "$ref": "#/components/schemas/device_AppleDeviceV2" }, { "$ref": "#/components/schemas/device_LinuxDeviceV2" }, { "$ref": "#/components/schemas/device_WindowsDeviceV2" } ] } }, "next_cursor": { "type": "string", "nullable": true, "description": "Opaque cursor token for fetching the next page. Null if no more results.", "example": "eyJzdiI6W3siYyI6InVwZGF0ZWRfYXQiLCJ2IjoiMjAyNi0wMy0xMVQwNzozNjowMS45NDM3NDlaIiwibyI6IkRFU0MifV0sInV2IjoiMTM5NzQwMjYtYTQzNS00ZDk5LWEyOWItM2E0Y2Y0MTZmODFhIn0=" }, "prev_cursor": { "type": "string", "nullable": true, "description": "Opaque cursor token for navigating to the previous page. Pass this value as the `cursor` query parameter to paginate backward. Null when already on the first page." }, "has_more": { "type": "boolean", "description": "Indicates if there are more results after the current page" }, "has_prev": { "type": "boolean", "description": "Indicates if there are results before the current page" } } }, "device_DeviceTagsRequest": { "type": "object", "description": "Either 'add' or 'remove' must be non-empty. A tag ID must not appear in both 'add'\nand 'remove' in the same request; this cross-array constraint cannot be expressed\nin OpenAPI 3.0 and is enforced server-side.\n", "properties": { "add": { "type": "array", "maxItems": 5, "uniqueItems": true, "items": { "type": "string", "format": "uuid", "description": "Tag Ids you want to associate with device" } }, "remove": { "type": "array", "maxItems": 5, "uniqueItems": true, "items": { "type": "string", "format": "uuid", "description": "Tag Ids you want to remove from device" } } }, "anyOf": [ { "required": [ "add" ], "properties": { "add": { "minItems": 1 } } }, { "required": [ "remove" ], "properties": { "remove": { "minItems": 1 } } } ] }, "device_DeviceTagsResponse": { "type": "object", "properties": { "device_id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "tag_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "device_EsperDeviceHeartbeat": { "type": "object", "properties": { "device_id": { "type": "string", "description": "UUID of the device", "format": "uuid" }, "timestamp": { "type": "string", "description": "Last seen time stamp of the device", "format": "date-time" }, "status": { "type": "integer", "description": "Legacy field representing whether the device was last seen in the last 30 minutes (returns 1) or not (returns 0). ", "enum": [ 0, 1 ] } } }, "device_DeviceLastSeen": { "type": "object", "properties": { "count": { "type": "integer" }, "prev": { "type": "string" }, "next": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/device_EsperDeviceHeartbeat" } } } }, "device_DeviceAppsResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "device_id": { "type": "string", "format": "uuid" }, "app_id": { "type": "string", "format": "uuid" }, "app_type": { "type": "string", "enum": [ "TENANT_IOS", "ESPER_IOS", "ESPER_WINDOWS", "TENANT_WINDOWS", "TENANT_WINDOWS_EXE", "TENANT_WINDOWS_UWP" ] }, "app_version_id": { "type": "string", "format": "uuid" }, "base64_app_config": { "type": "string" }, "auto_update": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "tenant_id": { "type": "string", "format": "uuid" } } }, "device_AutoInstallConstraint": { "type": "object", "properties": { "charging_state_constraint": { "type": "string", "description": "Constraint on the device's charging state for installation." }, "device_idle_state_constraint": { "type": "string", "description": "Constraint on the device's idle state for installation." }, "network_type_constraint": { "type": "string", "description": "Network type required for installation." } } }, "device_AutoInstallPolicy": { "type": "object", "properties": { "auto_install_constraint": { "type": "array", "items": { "$ref": "#/components/schemas/device_AutoInstallConstraint" }, "description": "Constraints for auto-installing the product." }, "auto_install_mode": { "type": "string", "description": "Mode for auto-installation." }, "auto_install_priority": { "type": "integer", "description": "Priority of the auto-installation." } } }, "device_VariableSet": { "type": "object", "properties": { "placeholder": { "type": "string", "description": "Placeholder key for configuration variable.", "example": "$emailaddress$" }, "user_value": { "type": "string", "description": "User-provided value for the placeholder.", "example": "user@example.com" } } }, "device_ManagedConfiguration": { "type": "object", "properties": { "configuration_variables": { "type": "object", "description": "Variables used for managed configurations.", "properties": { "mcm_id": { "type": "string", "description": "MCM ID required for configuration management.", "example": "00982462290877382272" }, "variable_set": { "type": "array", "description": "Set of configuration variables and their values.", "items": { "$ref": "#/components/schemas/device_VariableSet" } } } }, "kind": { "type": "string", "description": "Type of managed configuration.", "example": "androidenterprise#managedConfiguration" } } }, "device_ProductPolicy": { "type": "object", "properties": { "auto_update_mode": { "type": "string", "description": "Mode of auto-updating the product." }, "product_id": { "type": "string", "description": "Unique identifier for the product." }, "auto_install_policy": { "$ref": "#/components/schemas/device_AutoInstallPolicy" }, "managed_configuration": { "$ref": "#/components/schemas/device_ManagedConfiguration" } } }, "device_Policy": { "type": "object", "properties": { "auto_update_policy": { "type": "string", "description": "Defines the auto-update policy for the device." }, "device_report_policy": { "type": "string", "description": "Policy for device report generation." }, "product_availability_policy": { "type": "string", "description": "Defines the product availability policy." }, "product_policy": { "type": "array", "items": { "$ref": "#/components/schemas/device_ProductPolicy" } } } }, "device_GoogleEMMDevice": { "type": "object", "properties": { "android_id": { "type": "string", "description": "Unique identifier for the Android device." }, "management_type": { "type": "string", "description": "The management type of the device (e.g., managedDevice)." }, "policy": { "$ref": "#/components/schemas/device_Policy" } } }, "device_GoogleApplication": { "type": "object", "properties": { "product_id": { "type": "string", "description": "The unique product ID in the format of app:.", "example": "app:com.android.chrome" }, "mcm_id": { "type": "string", "description": "The MCM ID if required for configuration management.", "example": "mcm_12345" }, "app_action": { "type": "string", "description": "Action to be performed on the app, either 'install' or 'uninstall'.", "enum": [ "install", "uninstall" ], "example": "install" } } }, "device_GoogleEMMDevicePolicyRequest": { "type": "object", "properties": { "applications": { "type": "array", "items": { "$ref": "#/components/schemas/device_GoogleApplication" } } } }, "device_GoogleDevice": { "type": "object", "properties": { "androidId": { "type": "string", "description": "The Google Play Services Android ID for the device encoded as a lowercase hex string. For example, '123456789abcdef0'." }, "managementType": { "type": "string", "description": "The type of management applied to the device, such as 'enterprise' or 'work'." } } }, "device_DevicesListResponse": { "type": "object", "properties": { "device": { "type": "array", "items": { "$ref": "#/components/schemas/device_GoogleDevice" } } } }, "device_GoogleAccount": { "type": "object", "properties": { "tenant_id": { "type": "string", "format": "uuid", "description": "The ID of the tenant associated with the Google account." }, "google_user_id": { "type": "string", "description": "The unique identifier for the Google user." }, "device_id": { "type": "string", "format": "uuid", "description": "The ID of the device associated with the Google account." }, "google_device_id": { "type": "string", "description": "The unique identifier for the Google device." }, "account_identifier": { "type": "string", "description": "An identifier for the account." }, "account_type": { "type": "integer", "description": "The type of the Google account." }, "google_authentication_token": { "type": "string", "description": "The authentication token for the Google account." }, "created_at": { "type": "string", "format": "date-time", "description": "The timestamp when the Google account was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "The timestamp when the Google account was last updated." } }, "required": [ "tenant_id", "google_user_id", "device_id", "account_type" ] }, "device_GoogleAccountUpdateRequestBody": { "type": "object", "properties": { "google_device_id": { "type": "string", "description": "Unique identifier for the Google device." }, "google_user_id": { "type": "string", "description": "Unique identifier for the Google user." } }, "required": [ "google_device_id", "google_user_id" ] }, "device_GoogleAccountUpdateResponseBody": { "type": "object", "properties": { "device_id": { "type": "string", "description": "Unique identifier for the device." }, "tenant_id": { "type": "string", "description": "Unique identifier for the tenant." } }, "required": [ "device_id", "tenant_id" ] }, "device_Error_409_Conflict": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 409 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "device_OperationScheduleArgsTimeTypeEnum": { "type": "string", "description": "The Time-Type argument, in Schedule args, is to indicate which timezone the Command Framework should utilize when scheduling the command.\nFollowing Schedule Args for Time-Type are supported:\n\n```\n* CONSOLE: Use the local timezone of the user creating the schedule.\n* DEVICE: Use the local timezone of the device, to which the command is issued, wherever it may be.\n```\n", "enum": [ "console", "device" ] }, "device_ScheduleArgs": { "type": "object", "properties": { "start_datetime": { "type": "string", "format": "date-time", "description": "Start date and time in ISO 8601 format, including timezone (e.g., 2024-08-08T14:30:00Z or 2024-08-08T14:30:00+05:30)." }, "end_datetime": { "type": "string", "format": "date-time", "description": "End date and time in ISO 8601 format, including timezone (e.g., 2024-08-08T15:30:00Z or 2024-08-08T15:30:00+05:30)." }, "time_type": { "$ref": "#/components/schemas/device_OperationScheduleArgsTimeTypeEnum" }, "window_start_time": { "type": "string", "format": "date-time", "description": "It is automatically populated by the time field from the request's start_datetime and cannot be injected via the API request body." }, "window_end_time": { "type": "string", "format": "date-time", "description": "It is automatically populated by the time field from the request's end_datetime and cannot be injected via the API request body." }, "days": { "type": "array", "items": { "type": "integer" } } } }, "device_OperationActivity": { "type": "array", "items": { "type": "object", "properties": { "operation_state": { "type": "string", "enum": [ "CREATED", "QUERY INITIATED", "QUERY RESOLVED", "DISPATCHING", "DISPATCHED", "PROCESSING", "PROCESSED", "SUCCESS", "FAILURE", "CANCELLED" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "device_OperationStats": { "type": "object", "properties": { "device_operation_statuses_count": { "type": "object", "properties": { "resolved_device_count": { "type": "integer" }, "dispatched_device_count": { "type": "integer" }, "dispatch_failed_count": { "type": "integer" }, "failed_device_count": { "type": "integer" }, "success_device_count": { "type": "integer" }, "cancelled_device_count": { "type": "integer" } } } } }, "device_OperationWithStats": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "operation": { "type": "string", "description": "", "enum": [ "CONVERGE" ] }, "alias": { "type": "string", "maxLength": 256 }, "state": { "type": "string", "description": "", "enum": [ "CREATED", "RESOLVING", "RESOLVED", "DISPATCHING", "COMPLETED", "FAILED" ] }, "schedule_type": { "type": "string", "description": "Following Schedule types are supported\n```\n* IMMEDIATE: Schedule the command to execute Immediately\n* WINDOW: Schedule the command to execute within the given window\n", "enum": [ "IMMEDIATE", "WINDOW" ] }, "schedule_args": { "$ref": "#/components/schemas/device_ScheduleArgs" }, "operation_device_query": { "type": "object" }, "arguments": { "type": "object", "properties": { "converge_with_provision": { "type": "boolean" }, "geofence_ids": { "type": "array", "description": "List of geofence UUIDs to apply (APPLY_GEO_FENCE).", "items": { "type": "string", "format": "uuid" } } } }, "reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" }, "updated_by": { "type": "string", "format": "uuid" }, "operation_activity": { "$ref": "#/components/schemas/device_OperationActivity" }, "operation_stats": { "$ref": "#/components/schemas/device_OperationStats" } } }, "device_Operations_POST": { "type": "object", "properties": { "operation_type": { "type": "string", "description": "", "enum": [ "CONVERGE", "INSTALL", "UNINSTALL", "INSTALL_APP", "UNINSTALL_APP", "REBOOT", "LOCK", "SHUT_DOWN", "WIPE", "ADD_EMM_ACCOUNT", "ADD_OVERRIDE_APN", "ADD_WIFI_AP", "REMOVE_WIFI_AP", "UPDATE_WIFI_AP", "SET_ETHERNET_SETTINGS", "SET_STATIC_IP", "USE_ONLY_SAVED_WIFI_AP", "ADD_TO_WHITELIST", "REMOVE_FROM_WHITELIST", "ALLOW_BLUETOOTH", "ALLOW_CAMERA", "ALLOW_FACTORY_RESET", "ALLOW_UNENROLLMENT_FROM_DEVICE", "DEFER_OS_UPDATES", "PAUSE_OS_UPDATES", "SET_OS_UPDATE_POLICY", "APPLE_APP_UNINSTALL", "APPLY_APP_CONFIG", "CLEAR_APP_CACHE", "CLEAR_APP_DATA", "DIRECT_IOS_APP_INSTALL", "INSTALL_CERTIFICATE", "INSTALL_OTA", "NOTIFY_OTA", "REFRESH_APPLIST", "SET_APP_NOTIFICATIONS", "SET_APP_PERMISSION", "SET_APP_STATE", "SET_KIOSK_APP", "SET_MULTI_APP_MODE", "SET_NEW_POLICY", "SIMPLE_INSTALL", "SYNC_CONTENT", "UNINSTALL_CERTIFICATE", "VPP_APP_INSTALL", "INSTALL_PROFILE", "INSTALL_PROVISIONING_PROFILE", "INSTALL_WEBCLIP", "REMOVE_PROVISIONING_PROFILE", "UNINSTALL_WEBCLIP", "LIST_PROVISIONING_PROFILES", "BEEP_DEVICE", "CAPTURE_SCREENSHOT", "INITIATE_CONFERENCE_CALL", "INITIATE_OFFER", "NOTIFY_DEVICE", "NUDGE_DEVICE", "REQUEST_BUGREPORT", "REQUEST_DPCLOG", "DEPLOY_SYSTEM_OTA", "UPDATE_BLUEPRINT", "UPDATE_DEVICE_CONFIG", "UPDATE_OEM_CONFIG", "CLEAR_PASSCODE", "RESET_LOCKSCREEN_PASSWORD", "SET_ADB_STATE", "SET_DEVICE_LOCKDOWN_STATE", "DISABLE_LOST_MODE", "ENABLE_LOST_MODE", "LOST_MODE_DEVICE_LOCATION", "PLAY_LOST_MODE_SOUND", "SET_BLUETOOTH_STATE", "SET_BRIGHTNESS_SCALE", "SET_DEVICE_LANGUAGE", "SET_GEO_FENCE", "SET_GPS_STATE", "SET_LOCATION_SERVICE", "SET_ROTATION_STATE", "SET_SCREEN_OFF_TIMEOUT", "SET_STREAM_VOLUME", "SET_TIMEZONE", "SET_WALLPAPER", "SET_WIDGET", "SET_WIFI_STATE", "RUN_CSP_PAYLOAD", "SET_PFN", "COLLECT_LOGS", "REMOTE_CONNECTION", "REMOVE_AGENT", "REMOVE_DEVICE", "RUN_CUSTOM_ACTION", "RUN_SHELL_SCRIPT", "DECLARATIVE_MANAGEMENT", "APPLY_GEO_FENCE" ] }, "alias": { "type": "string", "maxLength": 256, "description": "Human-readable name for the operation" }, "schedule_type": { "type": "string", "description": "Following Schedule types are supported\n```\n* IMMEDIATE: Schedule the command to execute Immediately\n* WINDOW: Schedule the command to execute within the given window\n", "enum": [ "IMMEDIATE", "WINDOW" ] }, "schedule_args": { "$ref": "#/components/schemas/device_ScheduleArgs" }, "operation_device_query": { "type": "object", "description": "A flexible JSON object to define device properties and filters.", "properties": {} }, "arguments": { "type": "object", "description": "Operation-specific arguments that mirror the command_args payload for the corresponding command type. Use the same field names and structure as POST /commands/v0/commands/ for that operation_type. For example, pass converge_with_provision for CONVERGE, or package_name and app_version for INSTALL/UNINSTALL operations.\n", "properties": { "converge_with_provision": { "type": "boolean" }, "geofence_ids": { "type": "array", "description": "List of geofence UUIDs to apply (APPLY_GEO_FENCE).", "items": { "type": "string", "format": "uuid" } } } } } }, "device_DeviceOperationActivity": { "type": "object", "properties": { "device_operation_state": { "type": "string", "description": "The state of the device operation (e.g., queued, processing).", "example": "CREATED" }, "created_at": { "type": "string", "format": "date-time", "description": "The start time of the device operation state." } } }, "device_DeviceOperationWithStats": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "operation_id": { "type": "string", "format": "uuid" }, "device_id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "CREATED", "INITIATED", "SUCCEDED", "FAILED" ] }, "reason": { "type": "string", "example": "" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "device_operation_activity": { "type": "array", "items": { "$ref": "#/components/schemas/device_DeviceOperationActivity" } } } }, "device_RemoteViewerSessionsListForTenantResponse": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "device_id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "INITIATED", "ACKNOWLEDGED", "ACTIVE", "TERMINATED", "FAILED" ] }, "reason": { "type": "string" }, "video_quality": { "type": "string", "enum": [ "STANDARD", "DATA_SAVER" ] }, "duration": { "type": "string", "format": "duration", "description": "Depicts the time duration (in ISO 8601 duration format) of only a valid elapsed session, i.e., sessions that have moved from ACTIVE state (where session start-time can be captured) to TERMINATED or FAILED state (where the session end-time can be captured).", "example": "PT10M30S" }, "created_by": { "type": "string" }, "updated_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "device_name": { "type": "string", "description": "Name of the device." }, "device_alias": { "type": "string", "description": "Alias of the device (if any)." }, "device_state": { "$ref": "#/components/schemas/device_DeviceStateEnumAndroid" } } }, "apps_management_VPPLicense": { "type": "object", "properties": { "app_id": { "type": "string" }, "assigned_count": { "type": "integer" }, "available_count": { "type": "integer" }, "pricing_param": { "type": "string" }, "supported_platforms": { "type": "array", "items": { "type": "string" } }, "total_count": { "type": "integer" } } }, "apps_management_Error_401_Unauthorized": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 401 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "apps_management_Error_500_Internal_Server_Error": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 500 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "apps_management_ItunesAppInfoV2": { "type": "object", "properties": { "app_id": { "type": "string", "format": "uuid", "description": "App ID in UUID format" }, "apple_app_id": { "type": "string", "description": "App ID from Apple" }, "app_version_id": { "type": "string", "format": "uuid", "description": "current version of the app in UUID format" }, "apple_app_version": { "type": "string", "description": "current version of the app" }, "app_name": { "type": "string", "description": "name of the app" }, "icon_url": { "type": "string", "description": "url of the app's icon" }, "developer": { "type": "string", "description": "developer of the app" }, "itunes_url": { "type": "string", "description": "URL for the app on the iTunes store" }, "genres": { "type": "array", "items": { "type": "string", "description": "genre of the app" } }, "device_families": { "type": "array", "items": { "type": "string", "description": "devices the app is compatible with" } }, "bundle_id": { "type": "string", "description": "bundle ID of the app" }, "price": { "type": "number", "description": "price of the app" }, "app_size": { "type": "integer", "description": "size of the app" }, "minimum_os_version": { "type": "string", "description": "minimum OS version required for the app" }, "description": { "type": "string", "description": "description of the app" }, "last_updated_date": { "type": "string", "description": "date the app was last updated" }, "pricing_param": { "type": "string", "description": "pricing parameter" } } }, "apps_management_Error_400_Bad_Data": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 400 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "apps_management_SetPreferredRegionRequest": { "type": "object", "required": [ "preferred_region" ], "properties": { "preferred_region": { "type": "string", "pattern": "^[a-zA-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code for the preferred App Store region (e.g., 'US', 'JP')", "example": "US" } } }, "apps_management_Error_404_Not_Found": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 404 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "apps_management_TenantAppResponse": { "type": "object", "properties": { "id": { "type": "string" }, "platform": { "type": "string", "enum": [ "APPLE", "WINDOWS" ] }, "tenant_id": { "type": "string" }, "package_name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "updated_by": { "type": "string" } } }, "apps_management_AppUploadRequestBody": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "APPLE", "WINDOWS" ] }, "file": { "type": "string", "format": "binary", "description": "The main app binary (e.g. `.ipa`, `.msi`, `.exe`, `.msix`, `.msixbundle`)." } } }, "apps_management_TenantAppUploadResponse": { "type": "object", "properties": { "id": { "type": "string" }, "version_id": { "type": "string" }, "app_name": { "type": "string" }, "platform": { "type": "string", "enum": [ "APPLE", "WINDOWS" ] }, "tenant_id": { "type": "string" }, "package_name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "updated_by": { "type": "string" } } }, "apps_management_Error_403_Forbidden": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 403 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "apps_management_WindowsExeRegistryValidationArgs": { "type": "object", "required": [ "registry_path", "registry_key", "registry_value" ], "properties": { "registry_path": { "type": "string", "description": "Registry path. e.g. HKCU:\\Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\MyApp" }, "registry_key": { "type": "string", "description": "Registry value name within the path." }, "registry_value": { "type": "string", "description": "Expected value." } } }, "apps_management_WindowsExeFileValidationArgs": { "type": "object", "required": [ "file_path" ], "properties": { "file_path": { "type": "string", "description": "File path to check." } } }, "apps_management_TenantAppVersionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "app_type": { "type": "string", "enum": [ "TENANT_IOS", "TENANT_WINDOWS", "TENANT_WINDOWS_EXE", "TENANT_WINDOWS_UWP" ] }, "tenant_id": { "type": "string" }, "app_name": { "type": "string" }, "app_icon_url": { "type": "string" }, "release_notes": { "type": "string" }, "description": { "type": "string" }, "file_size_in_kb": { "type": "integer" }, "device_family": { "type": "array", "items": { "type": "string" } }, "version_name": { "type": "string" }, "build_number": { "type": "string", "description": "Build number of the app. Omitted when legacy_format is false." }, "version_code": { "type": "string", "description": "Version code of the app (same as build_number). Only present when legacy_format is false." }, "min_sdk_version": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "updated_by": { "type": "string" }, "is_active": { "type": "boolean", "nullable": true, "description": "Present only when app_type is TENANT_WINDOWS_EXE. True only when install_script, uninstall_script, and success_criteria are all set. Gates downstream install commands — a version with is_active=false cannot be deployed." }, "success_criteria_type": { "type": "string", "enum": [ "REGISTRY_VALIDATION", "FILE_VALIDATION" ], "nullable": true, "description": "Present only when app_type is TENANT_WINDOWS_EXE. Discriminator for the validation check performed after install/uninstall." }, "success_criteria": { "nullable": true, "description": "Present only when app_type is TENANT_WINDOWS_EXE. Contains the validation args. Shape depends on success_criteria_type.", "oneOf": [ { "$ref": "#/components/schemas/apps_management_WindowsExeRegistryValidationArgs" }, { "$ref": "#/components/schemas/apps_management_WindowsExeFileValidationArgs" } ] } } }, "apps_management_MsixAumid": { "type": "object", "description": "A single Application User Model ID (AUMID) entry exposed by an MSIX package.", "properties": { "application_id": { "type": "string", "description": "The `` from the package manifest." }, "aumid": { "type": "string", "description": "The fully-qualified AUMID, formatted as PackageFamilyName!ApplicationId." }, "is_default": { "type": "boolean", "description": "True for the first launchable entry, treated as the package default." } } }, "apps_management_AppVersionArtifactMetadata": { "type": "object", "description": "Type-specific attributes of an artifact. All fields are optional; only\nthose relevant to the artifact's type are populated.\n", "properties": { "package_family_name": { "type": "string", "nullable": true, "description": "The dependency package's own package family name (UWP_DEPENDENCY)." }, "package_dependency_name": { "type": "string", "nullable": true, "description": "The `` declared by the main package manifest (UWP_DEPENDENCY)." }, "min_version": { "type": "string", "nullable": true, "description": "The minimum required version declared by the main package manifest (UWP_DEPENDENCY)." }, "version_name": { "type": "string", "nullable": true, "description": "The actual version of the uploaded dependency package (UWP_DEPENDENCY)." }, "architecture": { "type": "string", "nullable": true, "description": "The dependency package architecture, e.g. x64, x86, arm64 (UWP_DEPENDENCY)." }, "cert_thumbprint": { "type": "string", "nullable": true, "description": "SHA1 thumbprint of the signing certificate (UWP_CERTIFICATE)." } } }, "apps_management_AppVersionArtifact": { "type": "object", "description": "A generic per-version artifact (e.g. a UWP framework dependency or signing certificate).", "properties": { "id": { "type": "string", "description": "The artifact row id (UUID)." }, "artifact_type": { "type": "string", "description": "The artifact discriminator (e.g. \"UWP_DEPENDENCY\", \"UWP_CERTIFICATE\")." }, "file_name": { "type": "string", "nullable": true, "description": "The original uploaded filename of the artifact." }, "app_sha256_hash": { "type": "string", "nullable": true, "description": "SHA256 hash of the uploaded artifact file." }, "download_url": { "type": "string", "nullable": true, "description": "Presigned S3 URL for downloading the artifact." }, "metadata": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/apps_management_AppVersionArtifactMetadata" } ] } } }, "apps_management_TenantAppVersionDetailResponse": { "allOf": [ { "$ref": "#/components/schemas/apps_management_TenantAppVersionResponse" }, { "type": "object", "properties": { "app_download_url": { "type": "string", "description": "Presigned URL for downloading the app binary. Present for TENANT_IOS (IPA), TENANT_WINDOWS (MSI), and TENANT_WINDOWS_UWP (MSIX/MSIXBundle) app types." }, "app_sha256_hash": { "type": "string", "description": "SHA256 hash of the app binary. Present for TENANT_IOS, TENANT_WINDOWS, and TENANT_WINDOWS_UWP app types." }, "product_code": { "type": "string", "description": "MSI product code. Present only when app_type is TENANT_WINDOWS." }, "install_script": { "type": "string", "nullable": true, "description": "PowerShell install script content. Present only when app_type is TENANT_WINDOWS_EXE. Null if not yet configured." }, "uninstall_script": { "type": "string", "nullable": true, "description": "PowerShell uninstall script content. Present only when app_type is TENANT_WINDOWS_EXE. Null if not yet configured." }, "package_format": { "type": "string", "enum": [ "MSIX", "MSIXBUNDLE" ], "description": "Present only when app_type is TENANT_WINDOWS_UWP. Indicates whether the package is a single .msix or a .msixbundle." }, "package_family_name": { "type": "string", "nullable": true, "description": "Present only when app_type is TENANT_WINDOWS_UWP. The package family name (PFN) derived from the manifest identity and publisher." }, "identity_name": { "type": "string", "nullable": true, "description": "Present only when app_type is TENANT_WINDOWS_UWP. The `` from the package manifest." }, "publisher": { "type": "string", "nullable": true, "description": "Present only when app_type is TENANT_WINDOWS_UWP. The `` from the package manifest." }, "architecture": { "type": "string", "nullable": true, "description": "Present only when app_type is TENANT_WINDOWS_UWP. Package architecture (e.g. x64, x86, arm64, neutral)." }, "entry_point_type": { "type": "string", "nullable": true, "description": "Present only when app_type is TENANT_WINDOWS_UWP. The application entry point type from the manifest." }, "aumids": { "type": "array", "description": "Present only when app_type is TENANT_WINDOWS_UWP. The Application User Model IDs (AUMIDs) exposed by the package, extracted from the manifest at ingest.", "items": { "$ref": "#/components/schemas/apps_management_MsixAumid" } }, "artifacts": { "type": "array", "description": "Present only when app_type is TENANT_WINDOWS_UWP. Per-version artifacts (framework dependencies, signing certificates, etc.), each with a presigned download URL.", "items": { "$ref": "#/components/schemas/apps_management_AppVersionArtifact" } } } } ] }, "apps_management_WindowsExeSuccessCriteria": { "type": "object", "required": [ "type", "validation_args" ], "properties": { "type": { "type": "string", "enum": [ "REGISTRY_VALIDATION", "FILE_VALIDATION" ], "description": "Discriminator for the validation check performed after install/uninstall.\nREGISTRY_VALIDATION checks a registry key/value; FILE_VALIDATION checks file existence.\n" }, "validation_args": { "oneOf": [ { "$ref": "#/components/schemas/apps_management_WindowsExeRegistryValidationArgs" }, { "$ref": "#/components/schemas/apps_management_WindowsExeFileValidationArgs" } ] } } }, "apps_management_WindowsExeConfigRequest": { "type": "object", "description": "EXE configuration. All fields are optional; omitted fields leave\nexisting values unchanged.\n", "properties": { "install_script": { "type": "string", "description": "PowerShell install script body. Maximum 64 KB." }, "uninstall_script": { "type": "string", "description": "PowerShell uninstall script body. Maximum 64 KB." }, "success_criteria": { "$ref": "#/components/schemas/apps_management_WindowsExeSuccessCriteria" } } }, "apps_management_ArtifactMutationResponse": { "type": "object", "description": "Identifies the artifact affected by an add/delete (identity-style, like\nthe app upload response) so the caller can refresh its view without a\nfull re-fetch.\n", "properties": { "id": { "type": "string", "format": "uuid", "description": "The affected artifact's id." }, "version_id": { "type": "string", "format": "uuid", "description": "The app version the artifact belongs to." }, "tenant_id": { "type": "string", "format": "uuid" }, "artifact_type": { "type": "string", "enum": [ "UWP_DEPENDENCY", "UWP_CERTIFICATE" ], "description": "The artifact discriminator." }, "file_name": { "type": "string", "nullable": true, "description": "The artifact's original filename." }, "metadata": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/apps_management_AppVersionArtifactMetadata" } ] } } }, "apps_management_AppleAppStoreApp": { "type": "object", "properties": { "icon": { "type": "string", "format": "uri", "description": "URL for the app icon", "example": "https://icon-url.com" }, "name": { "type": "string", "description": "Name of the app", "example": "Safari" }, "bundle_id": { "type": "string", "description": "Bundle identifier for the app", "example": "com.apple.mobilesafari" }, "file_size_in_bytes": { "type": "string", "description": "File size of the app in bytes", "example": "100" }, "app_store_url": { "type": "string", "format": "uri", "description": "URL to the app store listing", "example": "https://apps.apple.com/us/app/" }, "minimum_os": { "type": "string", "description": "Minimum OS version required", "example": "10.0" }, "release_date": { "type": "string", "format": "date-time", "description": "Release date of the app", "example": "2021-10-25T07:00:00.000Z" }, "seller_name": { "type": "string", "description": "Name of the seller", "example": "Apple Inc." } } }, "apps_management_AppInfo": { "type": "object", "properties": { "app_id": { "type": "string", "description": "Unique identifier for the app." }, "app_version_id": { "type": "string", "description": "Unique identifier for the app version." }, "app_type": { "type": "string", "description": "Type of the app." }, "tenant_id": { "type": "string", "description": "Identifier for the tenant." }, "name": { "type": "string", "description": "Name of the app to show on console." }, "label": { "type": "string", "description": "Label for the app to show on device." }, "icon_url": { "type": "string", "format": "uri", "description": "URL to the app icon." }, "package_name": { "type": "string", "description": "Unique identifier for the app bundle." }, "is_removable": { "type": "boolean", "description": "Indicates if the app can be removed." }, "is_full_screen": { "type": "boolean", "description": "Indicates if the app runs in full-screen mode." }, "url": { "type": "string", "format": "uri", "description": "URL to access the app." }, "file_size_in_kb": { "type": "integer", "description": "Size of the app in kilobytes." }, "release_notes": { "type": "string", "description": "Release notes for the app version." }, "description": { "type": "string", "description": "Description of the app." }, "build_number": { "type": "string", "description": "Build number of the app. Omitted when legacy_format is false." }, "version_code": { "type": "string", "description": "Version code of the app (same as build_number). Only present when legacy_format is false." }, "version_name": { "type": "string", "description": "Version name of the app." }, "min_sdk_version": { "type": "string", "description": "Minimum SDK version required to run the app." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the app was created." }, "created_by": { "type": "string", "description": "User who created the app entry." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the app was last updated." }, "updated_by": { "type": "string", "description": "User who last updated the app entry." } } }, "apps_management_Webclip": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the web clip", "example": "09811f63-e2ca-4625-97c1-081145195d67" }, "tenant_id": { "type": "string", "format": "uuid", "description": "Tenant identifier", "example": "7d5fd1bf-bdf9-490b-9e32-203756a61235" }, "label": { "type": "string", "description": "Label of the web clip", "example": "Google" }, "url": { "type": "string", "format": "uri", "description": "URL associated with the web clip", "example": "https://www.google.com/" }, "icon_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL for the icon of the web clip", "example": null }, "target_bundle_name": { "type": "string", "description": "Name of the target bundle", "example": "Esper" }, "target_bundle_id": { "type": "string", "description": "ID of the target bundle", "example": "com.esper.io" }, "is_full_screen": { "type": "boolean", "description": "Indicates if the web clip is full screen", "example": false }, "is_removable": { "type": "boolean", "description": "Indicates if the web clip is removable", "example": true }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the web clip was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the web clip was last updated" }, "created_by": { "type": "string", "description": "The user who created the web clip" }, "updated_by": { "type": "string", "description": "The user who last updated the web clip" } } }, "apps_management_WebclipCreateRequest": { "type": "object", "properties": { "icon": { "type": "string", "format": "binary", "description": "Icon of the webclip" }, "label": { "type": "string", "description": "Label of the web clip which is displayed on device", "example": "Example Label" }, "esper_name": { "type": "string", "description": "Name of the webclip in Esper", "example": "Example Name" }, "url": { "type": "string", "description": "URL for the webclip", "example": "https://example.com" }, "target_bundle_id": { "type": "string", "description": "Target bundle ID for the webclip", "example": "com.example.bundle" }, "target_bundle_name": { "type": "string", "description": "Target bundle name for the webclip", "example": "Example Bundle" }, "is_full_screen": { "type": "boolean", "description": "Indicates if the webclip is full screen", "example": true }, "is_removable": { "type": "boolean", "description": "Indicates if the webclip is removable", "example": false } }, "required": [ "label", "esper_name", "url", "target_bundle_id", "target_bundle_name", "is_full_screen", "is_removable" ] }, "apps_management_Error_409_Conflict": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 409 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "apps_management_ProvisioningProfileUploadResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the provisioning profile" }, "version_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this specific version of the profile" }, "name": { "type": "string", "description": "Display name of the provisioning profile" }, "team_identifier": { "type": "string", "description": "Apple Developer Team identifier" }, "app_identifier": { "type": "string", "description": "Bundle identifier of the associated app" }, "profile_type": { "type": "string", "description": "Type of profile (development, distribution, etc.)", "enum": [ "development", "ad-hoc", "app-store", "enterprise" ] }, "expiration_date": { "type": "string", "format": "date-time", "description": "When the provisioning profile expires" }, "tenant_id": { "type": "string", "format": "uuid", "description": "Tenant that owns this provisioning profile" }, "created_at": { "type": "string", "format": "date-time", "description": "When the provisioning profile was first created" }, "updated_at": { "type": "string", "format": "date-time", "description": "When this version was last updated" }, "created_by": { "type": "string", "description": "User who created the provisioning profile" }, "updated_by": { "type": "string", "description": "User who created this version" } } }, "apps_management_ProvisioningProfileWithDownloadResponse": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/apps_management_ProvisioningProfileUploadResponse" }, { "type": "object", "properties": { "download_url": { "type": "string", "format": "uri", "description": "Signed URL for downloading the provisioning profile file", "example": "https://s3.amazonaws.com/bucket/provisioning-profiles/profile.mobileprovision?signature=abc123" } } } ] }, "apps_management_ProvisioningProfileUploadRequest": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Provisioning profile file (.mobileprovision)" } }, "required": [ "file" ] }, "apps_management_ProvisioningProfileVersionWithDownloadResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Primary key and unique identifier for this version" }, "profile_id": { "type": "string", "format": "uuid", "description": "Foreign key reference to the parent ProvisioningProfile" }, "uuid": { "type": "string", "description": "Apple's UUID for this specific provisioning profile version" }, "name": { "type": "string", "description": "Display name of the provisioning profile version" }, "sha256_hash": { "type": "string", "description": "SHA256 hash of the provisioning profile file for duplicate detection" }, "creation_date": { "type": "string", "format": "date-time", "description": "When Apple created this provisioning profile (from .mobileprovision file)" }, "expiration_date": { "type": "string", "format": "date-time", "description": "When this provisioning profile expires (from Apple)" }, "time_to_live": { "type": "integer", "description": "Days until expiration from creation date" }, "provisions_all_devices": { "type": "boolean", "description": "Whether this profile provisions all devices (enterprise profiles)" }, "is_xcode_managed": { "type": "boolean", "description": "Whether this profile is managed by Xcode automatically" }, "platforms": { "type": "string", "description": "JSON array of supported platforms (iOS, macOS, etc.)" }, "entitlements": { "type": "string", "description": "JSON object of app entitlements and capabilities" }, "developer_certificates": { "type": "string", "description": "JSON array of developer certificates included in this profile" }, "tenant_id": { "type": "string", "format": "uuid", "description": "Tenant that owns this provisioning profile version" }, "created_by": { "type": "string", "description": "User identifier who uploaded this version" }, "updated_by": { "type": "string", "description": "User identifier who last modified this version record" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this version record was created in the database" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this version record was last modified" }, "download_url": { "type": "string", "format": "uri", "description": "Signed URL for downloading the provisioning profile file", "example": "https://s3.amazonaws.com/bucket/provisioning-profiles/version.mobileprovision?signature=abc123" } } }, "apps_management_TenantPreferredRegions": { "type": "object", "properties": { "tenant_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the tenant" }, "countries": { "type": "array", "items": { "type": "string" }, "description": "List of preferred country codes", "example": [ "AU", "IN", "US" ] }, "created_by": { "type": "string", "description": "The user who created the preferred regions" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the preferred regions were first created" }, "updated_by": { "type": "string", "description": "The user who last updated the preferred regions" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the preferred regions were last updated" } } }, "apps_management_SetPreferredRegionsRequest": { "type": "object", "required": [ "countries" ], "properties": { "countries": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "description": "List of ISO 3166-1 alpha-2 country codes (2-character uppercase). An empty array clears the tenant's preferred region preference.", "example": [ "AU", "IN", "US" ] } } }, "apps_management_EsperAppVersionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "app_type": { "type": "string", "enum": [ "TENANT_IOS", "ESPER_IOS", "ESPER_ANDROID", "ESPER_LINUX", "ESPER_WINDOWS" ] }, "app_name": { "type": "string" }, "app_icon_url": { "type": "string" }, "app_download_url": { "type": "string" }, "app_sha256_hash": { "type": "string" }, "signature_hash": { "type": "string", "description": "SHA-256 fingerprint of the app's public key in uppercase hexadecimal with colon separators (only for Android apps)" }, "architecture": { "type": "string" }, "release_notes": { "type": "string" }, "description": { "type": "string" }, "file_size_in_kb": { "type": "integer" }, "device_family": { "type": "array", "items": { "type": "string" } }, "version_name": { "type": "string" }, "build_number": { "type": "string" }, "min_sdk_version": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "updated_by": { "type": "string" } } }, "apps_management_TenantEsperAppsItem": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "app_version_id": { "type": "string" }, "app_id": { "type": "string" }, "package_name": { "type": "string", "description": "Package name of the app (only shown for Android apps)" }, "app_sha256_hash": { "type": "string" }, "signature_hash": { "type": "string", "description": "Signature hash of the app (only shown for Android apps)" }, "architecture": { "type": "string" }, "app_download_url": { "type": "string" }, "version_code": { "type": "string", "description": "Version code of the app (only shown for Android apps)" }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "apps_management_OEMConfigSchema": { "type": "object", "description": "OEM config schema metadata and optional JSON schema content parsed from an OEM APK", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for this schema record" }, "oem_type": { "type": "string", "enum": [ "ZEBRA", "HONEYWELL", "DATALOGIC", "SAMSUNG", "SUNMI" ], "description": "OEM manufacturer type" }, "package_name": { "type": "string", "description": "OEM config package name", "example": "com.zebra.oemconfig.common" }, "version_name": { "type": "string", "description": "Human-readable version string from the APK manifest", "example": "11.3.3.00" }, "version_code": { "type": "string", "description": "Integer version code from the APK manifest", "example": "10" }, "schema_format": { "type": "string", "description": "Format of the parsed schema (e.g. MANAGED_CONFIGURATIONS)" }, "parser_version": { "type": "string", "description": "Version of the internal parser that produced this schema" }, "is_latest": { "type": "boolean", "description": "Whether this is the latest active schema for this oem_type + package_name" }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ], "description": "Status of this schema record" }, "schema_metadata": { "type": "object", "description": "Additional metadata produced by the parser (parser-specific)" }, "schema_json": { "type": "object", "description": "Full parsed schema JSON. Omitted when include_schema=false." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this schema was first persisted" } } }, "commands_DeviceCommandEnum": { "type": "string", "description": "Following commands are supported\n```\n* ADD_TO_WHITELIST: Whitelist an installed sytem app. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper\n* ADD_WIFI_AP : Add wifi access points for device. Requires `wifi_access_points` in command arguments where `wifi_access_points` is the data with access points\n* APPLY_APP_CONFIG : Apply app configuration for an installed app.\n* CLEAR_APP_DATA : Clear data for an installed app. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper\n* CLEAR_APP_CACHE : Clear the cache of an installed app without removing its data. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper. Supported on Android 6.0+ devices with the supervisor installed.\n* CONVERGE: Converge command for Blueprint\n* INSTALL: Install an app on a device. Requires `app_version` in command arguments where `app_version` is the version id of app uploaded on Esper\n* INSTALL_CERTIFICATE: Install a certificate chain in the system keystore of an android device. Requires `cert_file_type`, `cert_data_base64`, `cert_alias_name` and `cert_storage_type` in command arguments where `cert_file_type` must be set to \"pkcs12\", `cert_data_base64` contains the base64 encoded content of the pkcs12 file, `cert_alias_name` is the alias name with which the certificate chain is supposed to be installed and `cert_storage_type` must be set to \"system\". If the pkcs12 file is password protected, the password should be specified in the optional parameter `cert_password`.\n* LOCK: Lock device screen, Supports Android, iOS and Windows devices.\n* REBOOT: Reboot a device. Supports Android, iOS, and Windows devices.\n* REMOVE_FROM_WHITELIST : Remove an installed system app from whitelist. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper\n* REMOVE_WIFI_AP : Remove Wifi access points for device. Requires `wifi_access_points` in command arguments where `wifi_access_points` is the data with access points\n* UPDATE_WIFI_AP : Update Wi-Fi access point configuration on device. Requires `wifi_ssid` and `wifi_security_type` in command arguments. Device must be connected to the target SSID. Supports EAP (enterprise) and personal (WPA2/WPA/WEP) networks. On failure, attempts to restore the previous configuration. Android only.\n* SET_APP_PERMISSION : Set permission for an installed app. Requires `package_name`, `grant_state`, `permission` in command arguments where `package_name` is the app package uploaded on Esper, `grant_state` should be \"PERMISSION_GRANT_STATE_DEFAULT\", \"PERMISSION_GRANT_STATE_DENIED\", \"PERMISSION_GRANT_STATE_GRANTED\" and `permission` is a valid permission\n* SET_APP_STATE : Set the state of an app - SHOW/HIDE/DISABLE/LAUNCHABLE_BUT_HIDDEN. Requries `app_state` and `package_name` in command arguments where `app_state` is the state of app and `package_name` is the app package uploaded on Esper For LAUNCHABLE_BUT_HIDDEN: Hide an app on the home screen but allow it to be launched from other apps. Requires Esper agent 8.5+ and `package_name`. \n* SET_BLUETOOTH_STATE : Set bluetooth state (ON/OFF) for device. Requires `bluetooth_state` in command arguments where `bluetooth_state` is a boolean.\n* SET_BRIGHTNESS_SCALE : Set brightness for device. Requires `brightness_value` in command arguments where `brightness_value` is an integer (1-100).\n* SET_DEVICE_LOCKDOWN_STATE : Set lockdown state for a device. Requires `state` and `message` in command arguments where `state` is LOCKED/UNLOCKED and `message` is the message to be added with command\n* SET_GPS_STATE :Set the GPS state for a device. Requires `gps_state` in command arguments where `gps_state` should be either 0, 1, 2, 3 or 4 (LOCATION_MODE_HIGH_ACCURACY = 0, LOCATION_MODE_SENSORS_ONLY = 1, LOCATION_MODE_BATTERY_SAVING = 2, LOCATION_MODE_OFF = 3, LOCATION_MODE_ON = 4)\n* SET_KIOSK_APP : Command to set the Kiosk app for a device. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper. For iOS devices, optionally accepts `disable_device_rotation` (boolean, default false) which disables device rotation sensing while in kiosk mode, and `disable_screen_timeout` (boolean, default true) which disables the screen auto-lock/timeout while in kiosk mode.\n\n* SET_MULTI_APP_MODE : Command to set the device back to multi app mode.\n* SET_NEW_POLICY : Apply policy on device. Requires `policy_url` in command arguments where `policy_url` is the URL to the policy\n* SET_ROTATION_STATE : Set screen orientation. Requires `rotate_state` in command arguments where `rotate_state` should be either 0, 1 or 2 (0 = AUTO, 1 = PORTRAIT_ONLY, 2 = LANDSCAPE_ONLY)\n* SET_SCREEN_OFF_TIMEOUT: Set screen off timeout for a device. Requires `screen_off_timeout` in command arguments where `screen_off_timeout` should be either -1 or between 5000 and 1800000\n* SET_STREAM_VOLUME : Set strema volume for a device. Requires `stream` and `volume_level` in command arguments where `stream` should be either 0(Ring), 1(Notification), 2(Alarm) or 3(Music) and `volume_level` should be a value from 0 to 100\n* SET_TIMEZONE : Set the timezone for a device. Requires `timezone_string` in command arguments where `timezone_string` is a valid string representing the timezone\n* SET_WIFI_STATE : Set the wifi state (ON/OFF) for a device. Requires `wifi_state` in command arguments where `wifi_state` is a boolean.\n* UNINSTALL: Uninstall an app from device. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper\n* UNINSTALL_CERTIFICATE: Uninstall a certificate from an android device's system keystore using the installed certificate's alias name. Requires `cert_alias_name` and `cert_storage_type` in command arguments where `cert_alias_name` is the alias name of the certificate to be uninstalled and `cert_storage_type` must be set to \"system\"\n* UPDATE_DEVICE_CONFIG: Push additional configurations to the Device\n* UPDATE_HEARTBEAT: Ping a device\n* UPDATE_LATEST_DPC : Prompt device to update the DPC app to the latest versions.\n* WIPE : Wipes the device.\n* RESET_LOCKSCREEN_PASSWORD: Change the lockscreen password of the device. Requires `new_lockscreen_password` in command arguments where `new_lockscreen_password` is a valid string.\n* UPDATE_BLUEPRINT: Pushes or reapplies the most current Blueprint version to the device or group.\n* NOTIFY_DEVICE: Allows you to broadcast message to the device.\n* SET_DEVICE_LANGUAGE: Set language for a device. Requires locale value in xx[_Zzzz]_yy where xx is language code, Zzzz is script (optional) and yy is country code.\n* SET_ETHERNET_SETTINGS: Set ethernet settings on supported Device\n* SET_STATIC_IP: Set static ip on the deivce. Requires interface, dhcp_dnabled, static_ip, primary_dns, subnet_mask, gateway, secondary_dns (optional)\n* BEEP_DEVICE: Allows you to make the device beep for a specified duration\n* SET_APP_NOTIFICATIONS: Enable/disable app notifications. Requries `app_notifications_state` and `package_name` in command arguments where `app_notifications_state` is a string that has the value `ENABLED` or `DISABLED` and `package_name` is the app package uploaded on Esper.\n* USE_ONLY_SAVED_WIFI_AP: Allow/disallow device to connect to unregistered WiFi APs. Requires boolean `use_only_saved_ap`..\n* DEVICE_INFORMATION: Prompt device to update the device information\n* VPP_APP_INSTALL: Install a vpp app on an iOS device. Requires `app_id` and `bundle_identifier` in command arguments that corresponds to the associate vpp app\n* APPLE_APP_UNINSTALL: Uninstall an app on an iOS device. Requires `app_id` and `bundle_identifier` in command arguments that corresponds to the associated app\n* CLEAR_PASSCODE: Clear the passcode in a device\n* LIST_INSTALLED_PROFILES: Returns a list of all installed profiles on an iOS device.\n* INSTALL_PROFILE: Install a profile on an iOS device.\n* REMOVE_PROFILE: Remove a profile from an iOS device.\n* RUN_SHELL_SCRIPT: Run a shell script on a Linux or Windows device. Requires `script` and `interpreter` in command arguments.\n* RUN_CUSTOM_ACTION: Run a custom action (script) on a Linux device. Requires custom action parameters in command arguments.\n* COLLECT_LOGS: Collect and upload Esper agent logs from a Linux device.\n* SCHEDULE_OS_UPDATE: Schedule an OS update on an Apple device. Requires `product_version` (string) and `install_action` (string, one of \"Default\", \"DownloadOnly\", \"InstallASAP\") in command_args.\n* OS_UPDATE_STATUS: Query the status of pending or in-progress OS updates on an Apple device.\n* SCAN_OS_UPDATES: Query available OS updates on an Apple device.\n* ENFORCE_OS_UPDATE_SETTINGS: Configure software update settings on an Apple device via DDM (Declarative Device Management). Maps to Apple's `com.apple.configuration.softwareupdate.settings` declaration. Supports `automatic_actions` (object with `download`, `install_os_updates`, `install_security_update` — each \"allowed\", \"always_on\", or \"always_off\"), `deferrals` (optional object with `combined_period_in_days`, 1-90 days), `notifications` (boolean), `rapid_security_response` (object with `enable`, `enable_rollback` — both boolean), and `recommended_cadence` (\"all\", \"oldest\", or \"newest\"). Requires iOS/iPadOS 18.0+ or tvOS 18.4+.\n* ENFORCE_SOFTWARE_UPDATE: Enforce software update on an Apple device. Requires `target_os_version` and `target_local_date_time` in command arguments where `target_os_version` is the OS version to update to and `target_local_date_time` is local date time value that specifies when to force install the software update. Use the format yyyy-mm-ddThh:mm:ss, which is derived from RFC3339 but doesn’t include a time zone offset. If the user doesn’t trigger the software update before this time, the device force installs it. Applicable for iOS/iPadOS 17+ and tvOS 18.4+ after enabling Declarative Device Management (DDM) on the device.\n* SET_OS_UPDATE_POLICY: Allow, disable or schedule automatic updates on a Windows device. Requires `auto_update_type` in command arguments. `auto_update_type` supports \"NOTIFY_DOWNLOAD\", \"AUTO_INSTALL_AND_NOTIFY_RESTART\", \"DEFAULT\", \"SCHEDULED_INSTALL_AND_RESTART\", \"AUTO_INSTALL_AND_RESTART_FORCED\" or \"OFF\".\n```\n", "enum": [ "ADD_TO_WHITELIST", "ADD_WIFI_AP", "APPLY_APP_CONFIG", "CLEAR_APP_CACHE", "CLEAR_APP_DATA", "CONVERGE", "INSTALL", "INSTALL_CERTIFICATE", "LIST_INSTALLED_PROFILES", "LOCK", "REBOOT", "REMOVE_FROM_WHITELIST", "REMOVE_PROFILE", "REMOVE_WIFI_AP", "SET_APP_PERMISSION", "SET_APP_STATE", "SET_BLUETOOTH_STATE", "SET_BRIGHTNESS_SCALE", "SET_DEVICE_LOCKDOWN_STATE", "SET_GPS_STATE", "SET_KIOSK_APP", "SET_MULTI_APP_MODE", "SET_NEW_POLICY", "SET_ROTATION_STATE", "SET_SCREEN_OFF_TIMEOUT", "SET_STREAM_VOLUME", "SET_TIMEZONE", "SET_WIFI_STATE", "UNINSTALL", "UNINSTALL_CERTIFICATE", "UPDATE_DEVICE_CONFIG", "UPDATE_HEARTBEAT", "UPDATE_LATEST_DPC", "UPDATE_WIFI_AP", "WIPE", "RESET_LOCKSCREEN_PASSWORD", "UPDATE_BLUEPRINT", "NOTIFY_DEVICE", "SET_DEVICE_LANGUAGE", "SET_ETHERNET_SETTINGS", "SET_STATIC_IP", "BEEP_DEVICE", "SET_APP_NOTIFICATIONS", "USE_ONLY_SAVED_WIFI_AP", "DEVICE_INFORMATION", "VPP_APP_INSTALL", "APPLE_APP_UNINSTALL", "CLEAR_PASSCODE", "INSTALL_PROFILE", "RUN_SHELL_SCRIPT", "RUN_CUSTOM_ACTION", "COLLECT_LOGS", "SCAN_OS_UPDATES", "SCHEDULE_OS_UPDATE", "OS_UPDATE_STATUS", "ENFORCE_OS_UPDATE_SETTINGS", "ENFORCE_SOFTWARE_UPDATE", "SET_OS_UPDATE_POLICY" ] }, "commands_CommandArgs": { "title": "Command args", "type": "object", "properties": { "device_alias_name": { "type": "string", "description": "Alternate human-readable name for your Device" }, "custom_settings_config": { "type": "object", "properties": {}, "description": "Managed configurations for your device (passed as JSON object)" }, "app_version": { "type": "string", "description": "The version id of app uploaded on Esper" }, "package_name": { "type": "string", "description": "The app package name uploaded on Esper" }, "policy_url": { "type": "string", "description": "The URL to the policy" }, "wifi_access_points": { "type": "object", "properties": {}, "description": "Wifi access points for the device (passed as JSON object)" }, "wifi_ssid": { "type": "string", "description": "The Wi-Fi network SSID to update (must be currently connected)" }, "wifi_security_type": { "type": "string", "enum": [ "NONE", "WEP", "WPA", "WPA2", "SAE", "EAP" ], "description": "Security type of the Wi-Fi network" }, "wifi_password": { "type": "string", "description": "Network password (required for WEP/WPA/WPA2)" }, "wifi_eap_method": { "type": "string", "enum": [ "PEAP", "TLS", "TTLS", "PWD", "SIM", "AKA", "AKA_PRIME" ], "description": "EAP method (required when wifi_security_type is EAP)" }, "wifi_phase2_auth": { "type": "string", "description": "Phase 2 authentication (required for PEAP/TTLS)" }, "certificate_file_path": { "type": "string", "description": "Path to .pfx or .p12 certificate on device (EAP/TLS)" }, "certificate_file_password": { "type": "string", "description": "Certificate file password if encrypted" }, "identity": { "type": "string", "description": "EAP identity or username" }, "anonymous_identity": { "type": "string", "description": "Outer identity for tunneled EAP methods" }, "domain": { "type": "string", "description": "Authentication server domain (EAP)" }, "hidden": { "type": "boolean", "description": "Whether the network is hidden (default false)" }, "state": { "type": "string", "description": "LOCKED/UNLOCKED" }, "message": { "type": "string", "description": "Message to be added with command to notify device." }, "title": { "type": "string", "description": "Message title to be added with command to notify device." }, "url": { "type": "string", "description": "(Optional) Link to notify device." }, "app_state": { "type": "string", "description": "The state of app - SHOW/HIDE/DISABLE/LAUNCHABLE_BUT_HIDDEN" }, "bluetooth_state": { "type": "boolean", "description": "The state of bluetooth - ON/OFF" }, "brightness_value": { "type": "integer", "description": "The brightness value of a device(1-100)" }, "gps_state": { "type": "integer", "description": "The GPS state of a device. Should be either 0, 1, 2, 3 or 4 (LOCATION_MODE_HIGH_ACCURACY = 0, LOCATION_MODE_SENSORS_ONLY = 1, LOCATION_MODE_BATTERY_SAVING = 2, LOCATION_MODE_OFF = 3, LOCATION_MODE_ON = 4)" }, "rotate_state": { "type": "integer", "description": "The screen orientation of a device. Should be either 0, 1 or 2 (0 = AUTO, 1 = PORTRAIT_ONLY, 2 = LANDSCAPE_ONLY)" }, "screen_off_timeout": { "type": "integer", "description": "The value for screen timeout of a device. Should be either -1 or between 5000 and 1800000" }, "stream": { "type": "integer", "description": "The value of the volume stream. Should be either 0(Ring), 1(Notification), 2(Alarm) or 3(Music)" }, "volume_level": { "type": "integer", "description": "The level of volume. Should be a value from 0 to 100" }, "timezone_string": { "type": "integer", "description": "The timezone of a device. Should be a valid timezone string" }, "wifi_state": { "type": "boolean", "description": "The state of WIFI - ON/OFF" }, "wifi_revert_timeout": { "type": "integer", "description": "The WIFI revert timeout. Should be greater than or equal to 1" }, "locale": { "type": "string", "description": "Language and country code in xx[_Zzzz]_yy where xx is language code, Zzzz is script (optional) and yy is country code." }, "ethernet_auth_mode": { "type": "string", "description": "Chosen mode of authentication", "enum": [ "NONE", "EAP_TLS" ] }, "ethernet_ca_cert_alias": { "type": "string", "description": "CA certificate alias. It is mandatory with Auth Mode EAP_TLS" }, "ethernet_client_cert_alias": { "type": "string", "description": "Client certificate alias. It is mandatory with Auth Mode EAP_TLS" }, "ethernet_eap_identity": { "type": "string", "description": "EAP identity" }, "interface": { "type": "string", "description": "The network interface of the device - wlan/eth" }, "dhcp_enabled": { "type": "string", "description": "The dhcp state on the device - true/false" }, "static_ip": { "type": "string", "description": "The static ip to set on the device. Should be a valid ipv4" }, "primary_dns": { "type": "string", "description": "The primary dns to set on the device. Should be a valid ipv4" }, "subnet_mask": { "type": "string", "description": "The subnet mask set on the device. Should between 1-32 both inclusive" }, "secondary_dns": { "type": "string", "description": "The secondary dns to set on the device. Should be a valid ipv4" }, "gateway": { "type": "string", "description": "The gateway to set on the device. Should be a valid ipv4" }, "duration": { "type": "string", "description": "The beep duration specified in seconds. Value must be between 10 and 300, both inclusive." }, "video_quality": { "type": "string", "default": "HIGH", "description": "The video quality of the respective Remote Viewer session. Options are \"LOW\", \"MEDIUM\" and \"HIGH\"." }, "enable_debug_mode": { "type": "boolean", "default": false, "description": "The flag to determine whether device must go into Debug Mode, in order to retrieve bug report when the device is already in Kiosk Mode." }, "app_id": { "type": "string", "description": "The unique identifier for VPP application in Apple’s ecosystem" }, "bundle_identifier": { "type": "string", "description": "The unique identifier for an application in Apple’s ecosystem" }, "managed_only": { "type": "boolean", "description": "If true, list outs only the profiles that was installed via MDM." }, "profile_identifier": { "type": "string", "description": "The identifier of the profile to remove." }, "profile": { "type": "string", "description": "Base 64 encoded profile plist to be installed on the device." }, "is_converge": { "type": "boolean", "description": "This value indicates that the command belongs to a converge action." }, "disable_device_rotation": { "type": "boolean", "default": false, "description": "Disable device rotation sensing while in kiosk mode (iOS only). Used by SET_KIOSK_APP." }, "disable_screen_timeout": { "type": "boolean", "default": true, "description": "Disable screen auto-lock/timeout while in kiosk mode (iOS only). Used by SET_KIOSK_APP. Defaults to true when omitted." }, "script": { "type": "string", "description": "A complete shell script to execute on Linux or Windows devices." }, "interpreter": { "type": "string", "description": "Type of interpreter to use for executing the script. e.g. For Linux use bash, zsh, or sh. For Windows use powershell. This field is mandatory." }, "execute_as": { "type": "string", "description": "User to execute the script as root or Esper (default user) - Optional, default is Esper if not specified. Supports Linux devices." }, "arguments": { "type": "array", "description": "Optional named dynamic arguments supplied at command dispatch time for RUN_CUSTOM_ACTION on Linux devices. When present, command-and-control prepends `set -u` plus one `name='value'` bash assignment per entry (in order, single-quote escaped) to the script before it is dispatched. Existing callers that do not set this field are unaffected.", "maxItems": 20, "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "Variable name exposed to the script. Must match `^[A-Za-z_][A-Za-z0-9_]*$`.", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "value": { "type": "string", "description": "Literal value assigned to the variable. Bash-escaped by the server.", "maxLength": 10240 } } } }, "cert_file_type": { "type": "string", "description": "Certificate file type. Currently file type of \"pkcs12\" is supported" }, "cert_data_base64": { "type": "string", "description": "Base64 encoded content of the certificate file" }, "cert_alias_name": { "type": "string", "description": "Alias name of the certificate to be used during installation or uninstallation" }, "cert_storage_type": { "type": "string", "description": "Refers to the keystore type to be used for certificate installation or uninstallation. Currently storage type of \"system\" is supported" }, "cert_password": { "type": "string", "description": "Provides the password if the pkcs12 file is password protected - Optional" }, "is_factory_reset": { "type": "boolean", "description": "If true, performs factory reset and unenrolls the device. If false, only unenrolls the device without wiping data. Required for WIPE command on Windows devices." }, "product_version": { "type": "string", "description": "The target OS version to schedule for update on an Apple device (e.g., \"17.4\", \"18.0.1\"). Required for SCHEDULE_OS_UPDATE command." }, "install_action": { "type": "string", "description": "The install action for the OS update on an Apple device. Required for SCHEDULE_OS_UPDATE command. \"Default\" - Download or install the update depending on the current state. \"DownloadOnly\" - Download the update without installing it. \"InstallASAP\" - Install an already downloaded update immediately.", "enum": [ "Default", "DownloadOnly", "InstallASAP" ] }, "automatic_actions": { "type": "object", "description": "Controls automatic download and install behavior for OS and security updates. For ENFORCE_OS_UPDATE_SETTINGS command on Apple devices.", "properties": { "download": { "type": "string", "description": "Automatic download behavior.", "enum": [ "allowed", "always_on", "always_off" ] }, "install_os_updates": { "type": "string", "description": "Automatic OS update install behavior.", "enum": [ "allowed", "always_on", "always_off" ] }, "install_security_update": { "type": "string", "description": "Automatic security update install behavior.", "enum": [ "allowed", "always_on", "always_off" ] } } }, "deferrals": { "type": "object", "description": "Deferral period for OS updates. For ENFORCE_OS_UPDATE_SETTINGS command on Apple devices.", "properties": { "combined_period_in_days": { "type": "integer", "description": "Combined deferral period in days (1-90).", "minimum": 1, "maximum": 90 } } }, "notifications": { "type": "boolean", "description": "Whether to show OS update notifications to the user. For ENFORCE_OS_UPDATE_SETTINGS command on Apple devices." }, "rapid_security_response": { "type": "object", "description": "Rapid Security Response settings. For ENFORCE_OS_UPDATE_SETTINGS command on Apple devices.", "properties": { "enable": { "type": "boolean", "description": "Enable Rapid Security Responses (default true)." }, "enable_rollback": { "type": "boolean", "description": "Enable rollback of Rapid Security Responses (default true)." } } }, "recommended_cadence": { "type": "string", "description": "Which OS updates to recommend to users. For ENFORCE_OS_UPDATE_SETTINGS command on Apple devices.", "enum": [ "all", "oldest", "newest" ] }, "target_os_version": { "type": "string", "description": "The target OS version to enforce update to on an Apple device (e.g., \"17.4\", \"18.0.1\"). Required for ENFORCE_SOFTWARE_UPDATE command." }, "target_local_date_time": { "type": "string", "description": "The local date and time to enforce the software update on an Apple device. Required for ENFORCE_SOFTWARE_UPDATE command. Use the format yyyy-mm-ddThh:mm:ss, which is derived from RFC3339 but doesn’t include a time zone offset." }, "auto_update_type": { "type": "string", "description": "The type of auto update behavior to apply on a Windows device, mapped to the CSP Update/AllowAutoUpdate. Required for SET_OS_UPDATE_POLICY command. NOTIFY_DOWNLOAD notifies before downloading; AUTO_INSTALL_AND_NOTIFY_RESTART auto-installs and notifies to schedule a restart; DEFAULT auto-installs and restarts (system default); SCHEDULED_INSTALL_AND_RESTART auto-installs and restarts at a scheduled time; AUTO_INSTALL_AND_RESTART_FORCED auto-installs and restarts without end-user control; OFF disables automatic updates.", "enum": [ "NOTIFY_DOWNLOAD", "AUTO_INSTALL_AND_NOTIFY_RESTART", "DEFAULT", "SCHEDULED_INSTALL_AND_RESTART", "AUTO_INSTALL_AND_RESTART_FORCED", "OFF" ] } } }, "commands_CommandScheduleEnum": { "type": "string", "description": "Following Schedule types are supported\n```\n* IMMEDIATE: Schedule the command to execute Immediately\n* WINDOW: Schedule the command to execute within the given window\n* RECURRING: Schedule the command to execute during the scheduled time until it succeeds or expires. After executing successfully, it will not fire again.\n```\n", "enum": [ "IMMEDIATE", "WINDOW", "RECURRING" ] }, "commands_CommandScheduleArgsTimeTypeEnum": { "type": "string", "description": "The Time-Type argument, in Schedule args, is to indicate which timezone the Command Framework should utilize when scheduling the command.\nFollowing Schedule Args for Time-Type are supported:\n```\n* CONSOLE: Use the local timezone of the user creating the schedule.\n* DEVICE: Use the local timezone of the device, to which the command is issued, wherever it may be.\n```\n", "enum": [ "console", "device" ] }, "commands_CommandScheduleArgs": { "title": "Command Schedule Arguments", "type": "object", "properties": { "name": { "type": "string" }, "start_datetime": { "type": "string", "format": "date-time" }, "end_datetime": { "type": "string", "format": "date-time" }, "time_type": { "$ref": "#/components/schemas/commands_CommandScheduleArgsTimeTypeEnum" }, "window_start_time": { "type": "string" }, "window_end_time": { "type": "string" }, "days": { "type": "array", "items": { "type": "string" } } } }, "commands_CommandRequest": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique command request identifier", "format": "uuid", "readOnly": true }, "command_type": { "type": "string", "description": "Identifies the type of command\n\n```\n* DEVICE: command request is meant for devices\n* GROUP: command request is meant for groups\n* DYNAMIC: command request is meant for dynamic set of devices\n i.e subset of devices from different groups or otherwise.\n```\n", "enum": [ "DEVICE", "GROUP", "DYNAMIC" ] }, "devices": { "maxItems": 1000, "minItems": 0, "type": "array", "description": "list of devices to run commands", "items": { "type": "string", "format": "uuid" } }, "groups": { "maxItems": 500, "minItems": 0, "type": "array", "description": "list of groups to run commands", "items": { "type": "string", "format": "uuid" } }, "device_type": { "type": "string", "description": "Filtering by device_type is not supported currently and applies to 'all' devices. If 'active' or 'inactive' is specified, it will be ignored.", "default": "active", "enum": [ "active", "inactive", "all" ] }, "command": { "$ref": "#/components/schemas/commands_DeviceCommandEnum" }, "command_args": { "$ref": "#/components/schemas/commands_CommandArgs" }, "schedule": { "$ref": "#/components/schemas/commands_CommandScheduleEnum" }, "schedule_args": { "$ref": "#/components/schemas/commands_CommandScheduleArgs" }, "reason": { "type": "string", "description": "details briefing the reason for current command request processing stage" }, "created_by": { "type": "string", "description": "user id of the user", "readOnly": true }, "created_at": { "type": "string", "description": "Timestamp of command request", "format": "date-time", "readOnly": true } } }, "commands_Error_401_Unauthorized": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 401 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "commands_Error_500_Internal_Server_Error": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 500 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "commands_CommandRequest_POST": { "type": "object", "properties": { "command_type": { "type": "string", "description": "Identifies the type of command\n\n```\n* DEVICE: command request is meant for devices\n* GROUP: command request is meant for groups\n* DYNAMIC: command request is meant for dynamic set of devices\n i.e subset of devices from different groups or otherwise.\n```\n", "enum": [ "DEVICE", "GROUP", "DYNAMIC" ] }, "alias": { "type": "string", "description": "Another name for the command, provided by the user or Console." }, "devices": { "maxItems": 1000, "minItems": 0, "type": "array", "description": "List of devices to run commands. Required if command_type is 'DEVICE' or 'DYNAMIC'", "items": { "type": "string", "format": "uuid" } }, "groups": { "maxItems": 500, "minItems": 0, "type": "array", "description": "List of groups to run commands. Required if command_type is 'GROUP' or 'DYNAMIC'", "items": { "type": "string", "format": "uuid" } }, "device_type": { "type": "string", "description": "Filtering by device_type is currently not supported. Please specify 'all'.", "enum": [ "all" ] }, "command": { "$ref": "#/components/schemas/commands_DeviceCommandEnum" }, "command_args": { "$ref": "#/components/schemas/commands_CommandArgs" }, "schedule": { "$ref": "#/components/schemas/commands_CommandScheduleEnum" }, "schedule_args": { "$ref": "#/components/schemas/commands_CommandScheduleArgs" } } }, "commands_Error_400_Bad_Data": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 400 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "commands_Error_404_Not_Found": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 404 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "commands_CommandRequestStats": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "status": { "type": "array", "description": "List of each command status associated to its count.", "items": { "type": "object", "properties": { "state": { "type": "string", "description": "State of the command", "enum": [ "Command Queued", "Command Initiated", "Command Acknowledged", "Command In Progress", "Command TimeOut", "Command Success", "Command Failure", "Command Scheduled", "Command Cancelled" ] }, "total": { "type": "number", "description": "Count of the devices that are in the corresponding command state" } } } } } }, "commands_CommandStatus": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique command identifier", "format": "uuid", "readOnly": true }, "request": { "title": "Request Id", "type": "string", "description": "Request Id associated with this command", "format": "uuid", "readOnly": true }, "device": { "title": "Device", "type": "string", "description": "Device associated with this command", "format": "uuid", "readOnly": true }, "state": { "type": "string", "description": "Current state of the command", "enum": [ "Command Queued", "Command Initiated", "Command Acknowledged", "Command In Progress", "Command TimeOut", "Command Success", "Command Failure", "Command Scheduled", "Command Cancelled" ] }, "reason": { "type": "string", "description": "details briefing the reason for current command state" }, "created_at": { "type": "string", "description": "Timestamp of command creation", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "description": "Last updated timestamp of command", "format": "date-time", "readOnly": true }, "command_meta": { "type": "object", "nullable": true, "description": "Optional metadata associated with the command execution result. Present only for commands that return structured data from the device.\n", "properties": { "result": { "description": "Command-specific result data. Structure varies by command type. For OS_UPDATE_STATUS, result is an object with fields: product_key, is_downloaded, download_percent_complete, status, product_version. For SCAN_OS_UPDATES, result is an array of objects with fields: product_key, product_version, build, human_readable_name, is_critical, download_size.\n", "nullable": true } } } } }, "commands_CommandStatus_PUT": { "type": "object", "properties": { "state": { "type": "string", "description": "Command state to update", "enum": [ "Command Acknowledged", "Command In Progress", "Command TimeOut", "Command Success", "Command Failure", "Command Scheduled", "Command Cancelled" ] }, "reason": { "type": "string", "description": "State change reason to update" } } }, "commands_CommandInbox": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique command identifier", "format": "uuid", "readOnly": true }, "command": { "type": "string", "description": "The command to be executed" }, "command_args": { "type": "object", "description": "Arguments for the command", "properties": { "script": { "type": "string", "description": "The script to be executed" } } }, "device_meta": { "type": "object", "description": "Metadata about the device", "properties": { "platform": { "type": "string", "description": "The platform of the device" } } }, "state": { "type": "string", "description": "Current state of the command", "enum": [ "Command Queued" ] }, "created_on": { "type": "string", "description": "Timestamp of command creation", "format": "date-time", "readOnly": true }, "updated_on": { "type": "string", "description": "Last updated timestamp of command", "format": "date-time", "readOnly": true } } }, "drift_BlueprintsInfo": { "type": "object", "properties": { "blueprint_id": { "type": "string", "description": "Unique blueprint ID", "format": "uuid" }, "blueprint_version_id": { "type": "string", "description": "Version ID of blueprint", "format": "uuid" } } }, "drift_ScheduleEnum": { "type": "string", "description": "Following Schedule types are supported\n``` * IMMEDIATE: Schedule the command to execute Immediately\n* WINDOW: Schedule the command to execute within the given window ```\n", "enum": [ "IMMEDIATE", "WINDOW" ] }, "drift_Converge": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique converge identifier", "format": "uuid", "readOnly": true }, "device_id": { "type": "string", "description": "ID of the device", "format": "uuid" }, "converge_with_provision_option": { "type": "boolean" }, "blueprint_info": { "type": "object", "$ref": "#/components/schemas/drift_BlueprintsInfo" }, "schedule_type": { "$ref": "#/components/schemas/drift_ScheduleEnum" }, "schedule_args": { "type": "object" }, "status": { "type": "string", "description": "Current aggregated status of the converge action", "enum": [ "QUEUED", "PROCESSING", "IN_PROGRESS", "SUCCESS", "FAILURE" ] }, "reason": { "type": "string", "description": "details briefing the reason for current converge status" }, "created_by": { "type": "string", "description": "user id of the user", "readOnly": true }, "created_at": { "type": "string", "description": "Creation timestamp of converge", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "description": "Updation timestamp of converge", "format": "date-time", "readOnly": true } } }, "drift_Error_401_Unauthorized": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 401 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "drift_Error_500_Internal_Server_Error": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 500 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "drift_Converge_POST": { "type": "object", "properties": { "device_id": { "type": "string", "description": "ID of the device", "format": "uuid" }, "converge_with_provision_option": { "type": "boolean" }, "schedule_type": { "$ref": "#/components/schemas/drift_ScheduleEnum" }, "schedule_args": { "type": "object" } }, "required": [ "device_id", "converge_with_provision_option" ] }, "drift_Error_400_Bad_Data": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 400 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "drift_Error_404_Not_Found": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 404 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "drift_ConvergeCommand": { "type": "object", "properties": { "command_request_id": { "type": "string", "description": "ID of the command request", "format": "uuid" }, "command_state": { "type": "string", "description": "Current state of the command", "enum": [ "Command Queued", "Command Initiated", "Command Acknowledged", "Command In Progress", "Command TimeOut", "Command Success", "Command Failure", "Command Scheduled", "Command Cancelled" ] }, "reason": { "type": "string", "description": "Details briefing the reason for current command state." }, "created_at": { "type": "string", "description": "Creation timestamp of converge command", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "description": "Updation timestamp of converge command", "format": "date-time", "readOnly": true } } }, "drift_BlueprintDriftSummaryResponse": { "type": "object", "properties": { "drifted_total": { "type": "integer", "description": "Devices with drifted settings (highest severity shown in breakdown fields)" }, "compliant_total": { "type": "integer", "description": "Devices with no drifted settings" }, "critical_total": { "type": "integer", "description": "Drifted devices whose highest severity is critical" }, "major_total": { "type": "integer", "description": "Drifted devices whose highest severity is major" }, "minor_total": { "type": "integer", "description": "Drifted devices whose highest severity is minor" }, "log_only_total": { "type": "integer", "description": "Drifted devices whose highest severity is log_only" } }, "required": [ "drifted_total", "compliant_total", "critical_total", "major_total", "minor_total", "log_only_total" ] }, "drift_BlueprintDriftStatusItem": { "type": "object", "properties": { "device_id": { "type": "string", "format": "uuid", "description": "Device identifier" }, "state": { "type": "string", "description": "Blueprint Drift status (drifted, compliant, unknown)", "enum": [ "drifted", "compliant", "unknown" ] }, "critical_drift_count": { "type": "integer", "description": "Number of drifted settings with severity = 40 (CRITICAL)" } }, "required": [ "device_id", "state", "critical_drift_count" ] }, "drift_BlueprintDriftStatusResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/drift_BlueprintDriftStatusItem" } } }, "required": [ "results" ] }, "drift_BlueprintDriftDeviceSetting": { "type": "object", "properties": { "setting": { "type": "string", "description": "Setting identifier" }, "display_name": { "type": "string", "description": "Display name for the setting" }, "section": { "type": "string", "description": "Blueprint section this setting belongs to (e.g., \"Connectivity\", \"Apps & Configuration\")" }, "device_state": { "type": "string", "nullable": true, "description": "Current device value (if reported)" }, "desired_state": { "type": "string", "nullable": true, "description": "Desired state defined by blueprint" }, "state": { "type": "string", "description": "Blueprint Drift status for the setting", "enum": [ "drifted", "compliant" ] }, "severity": { "type": "string", "description": "Blueprint Drift severity", "enum": [ "ignore", "critical" ] }, "drift_calculated_at": { "type": "string", "format": "date-time", "description": "Timestamp when drift was calculated" }, "desired_state_reported_at": { "type": "string", "format": "date-time", "description": "Timestamp when desired state was reported" }, "device_state_reported_at": { "type": "string", "format": "date-time", "description": "Timestamp when device state was reported" } }, "required": [ "setting", "state", "severity", "drift_calculated_at", "desired_state_reported_at", "device_state_reported_at" ] }, "drift_BlueprintDriftDeviceSettingsResponse": { "type": "object", "properties": { "device_id": { "type": "string", "format": "uuid", "description": "Device identifier" }, "settings": { "type": "array", "items": { "$ref": "#/components/schemas/drift_BlueprintDriftDeviceSetting" } } }, "required": [ "device_id", "settings" ] }, "device_onboarding_SeamlessRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "assigned_blueprint_id": { "type": "string", "format": "uuid" }, "group_id": { "type": "string", "format": "uuid", "nullable": true }, "alias": { "type": "string", "nullable": true }, "tags": { "type": "array", "nullable": true, "maxItems": 5, "items": { "type": "string" } }, "unique_ids": { "type": "string" }, "unique_id_type": { "type": "integer" }, "tenant_id": { "type": "string" } } }, "device_onboarding_Error_400_Bad_Data": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 400 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "device_onboarding_Error_401_Unauthorized": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 401 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "device_onboarding_Error_500_Internal_Server_Error": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 500 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "device_onboarding_SeamlessInfo": { "type": "object", "properties": { "unique_ids": { "type": "string", "example": "3e41fd18-d53d-4673-a10a-23089cbb6b73" }, "unique_id_type": { "type": "integer", "example": 2 } } }, "device_onboarding_SeamlessRequestBody": { "type": "object", "properties": { "assigned_blueprint_id": { "type": "string", "format": "uuid", "example": "3e41fd18-d53d-4673-a10a-23089cbb6b73" }, "group_id": { "type": "string", "format": "uuid", "example": "3e41fd18-d53d-4673-a10a-23089cbb6b73" }, "alias": { "type": "string", "nullable": true, "example": "front-desk-ipad" }, "tags": { "type": "array", "nullable": true, "maxItems": 5, "items": { "type": "string" }, "example": [ "warehouse-a", "kiosk" ] }, "seamless_info": { "$ref": "#/components/schemas/device_onboarding_SeamlessInfo" } } }, "device_onboarding_DEPSyncDeviceStatus": { "type": "object", "properties": { "serial": { "type": "string" }, "reason": { "type": "string" } } }, "device_onboarding_DEPSyncRequestForGetResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique DEP sync request identifier", "format": "uuid", "readOnly": true }, "status": { "type": "string", "description": "Status of the DEP sync request", "enum": [ "QUEUED", "INPROGRESS", "COMPLETE", "FAILURE", "SUCCESS" ] }, "failure_reason": { "type": "string", "description": "Reason for DEP Sync failure. If this field is included in the response, a list of devices with which failed to process DEP sync will also be returned in the API response." }, "devices": { "type": "object", "properties": { "failure": { "type": "array", "items": { "$ref": "#/components/schemas/device_onboarding_DEPSyncDeviceStatus" } } } }, "created_by": { "type": "string", "description": "user id of the user" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "device_onboarding_DEPSyncRequest": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique DEP sync request identifier", "format": "uuid", "readOnly": true }, "status": { "type": "string", "description": "Status of the DEP sync request", "enum": [ "QUEUED", "INPROGRESS", "COMPLETE", "FAILURE", "SUCCESS" ] }, "created_by": { "type": "string", "description": "user id of the user" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "device_onboarding_Error_404_Not_Found": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 404 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "tenant_APNSCertInfo": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "apple_id": { "type": "string" }, "meta": { "type": "object", "properties": { "topic": { "type": "string" }, "cert_created_at": { "type": "string", "format": "date-time" }, "cert_expiry_on": { "type": "string", "format": "date-time" } } }, "state": { "type": "string", "description": "state of APNs certificate upload", "enum": [ "CSR_GENERATED", "COMPLETED" ] }, "created_by": { "type": "number", "format": "int32" }, "updated_by": { "type": "number", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "tenant_Error_401_Unauthorized": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 401 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "tenant_Error_500_Internal_Server_Error": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 500 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "tenant_Error_400_Bad_Data": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 400 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "tenant_Error_404_Not_Found": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 404 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "tenant_APNSCert_PUT": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "apple_id": { "type": "string" } }, "required": [ "file", "apple_id" ] }, "tenant_VPPToken": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "maxLength": 64 }, "key": { "type": "string", "maxLength": 256 }, "meta": { "type": "object" }, "created_by": { "type": "string", "maxLength": 64 }, "updated_by": { "type": "string", "maxLength": 64 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "tenant_id", "created_by", "updated_by" ] }, "tenant_DEP_Token_GET": { "type": "object", "properties": { "id": { "type": "string", "format": "UUID", "description": "id of DEP token" }, "token_name": { "type": "string", "description": "name of DEP Token" }, "meta": { "type": "object", "description": "meta information about the DEP token", "properties": { "token_expiry_on": { "type": "string" } } }, "state": { "type": "string", "description": "state of DEP token upload", "enum": [ "CSR_GENERATED", "COMPLETED" ] }, "created_by": { "type": "string", "description": "user id of the user" }, "updated_by": { "type": "string", "description": "user id of the user" }, "created_at": { "type": "string", "description": "Timestamp of DEP token creation", "readOnly": true }, "updated_at": { "type": "string", "description": "Timestamp of DEP token creation", "readOnly": true } } }, "tenant_DEP_Token_POST": { "type": "object" }, "tenant_DEPProfile": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "profile_uuid": { "type": "string" }, "show_setup_items": { "type": "array", "items": { "type": "string" }, "description": "List of setup items to show during device enrollment" }, "auto_advance_setup": { "type": "boolean", "description": "Whether to automatically advance through setup screens, only applicable to TvOS devices" }, "created_by": { "type": "string" }, "updated_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "tenant_DEPProfileCreateRequest": { "type": "object", "properties": { "show_setup_items": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "AccessibilityAppearance", "ActionButton", "Android", "Appearance", "AppleID", "AppStore", "Biometric", "CameraButton", "DeviceToDeviceMigration", "Diagnostics", "DisplayTone", "EnableLockdownMode", "HomeButtonSensitivity", "iMessageAndFaceTime", "Intelligence", "Keyboard", "LiquidGlass", "Location", "MessagingActivationUsingPhoneNumber", "Multitasking", "OnBoarding", "OSShowcase", "Passcode", "Payment", "Privacy", "Restore", "RestoreCompleted", "Safety", "SafetyAndHandling", "ScreenTime", "ScreenSaver", "SIMSetup", "Siri", "SoftwareUpdate", "SpokenLanguage", "TapToSetup", "TermsOfAddress", "TOS", "TVHomeScreenSync", "TVProviderSignIn", "TVRoom", "UpdateCompleted", "WatchMigration", "Welcome", "Zoom" ] }, "description": "List of setup items to show during device enrollment. If not provided or empty, all items will be skipped (default behavior)." }, "auto_advance_setup": { "type": "boolean", "default": true, "description": "Whether to automatically advance through setup screens. Defaults to true if not specified. Only applicable to TvOS devices." } } }, "tenant_BeginGoogleEMMEnrollmentRequest": { "type": "object", "properties": { "callback_url": { "type": "string" } }, "required": [ "callback_url" ] }, "tenant_BeginGoogleEMMEnrollmentResponse": { "type": "object", "properties": { "signup_url": { "type": "string" }, "completion_token": { "type": "string" } } }, "tenant_Error_409_Conflict": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 409 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "tenant_GoogleEnterpriseDetails": { "type": "object", "properties": { "id": { "type": "integer" }, "google_enterprise_id": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "integer" }, "callback_url": { "type": "string" }, "signup_url": { "type": "string" }, "completion_token": { "type": "string" }, "enterprise_token": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "tenant_id": { "type": "string" } } }, "tenant_CreateWebTokenRequest": { "type": "object", "properties": { "google_enterprise_id": { "type": "string", "description": "The ID of the Google enterprise. It is required and cannot be empty.", "example": "test", "minLength": 1 }, "parent_url": { "type": "string", "description": "The parent URL. It must be a valid URL with the https scheme.", "format": "uri", "example": "https://valid.url", "pattern": "^https://" } }, "required": [ "google_enterprise_id", "parent_url" ] }, "tenant_CreateWebTokenResponse": { "type": "object", "properties": { "token": { "type": "string", "description": "The generated token.", "example": "test_1245" } } }, "tenant_GoogleServiceAccountDetails": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "google_enterprise_id": { "type": "string" }, "name": { "type": "string" }, "key_id": { "type": "string" }, "type": { "type": "integer" }, "is_set": { "type": "boolean" }, "is_active": { "type": "boolean" }, "data": { "type": "string" }, "public_data": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "foundation_Build_V1": { "type": "object", "properties": { "build_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deprecated_on": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "updated_by": { "type": "string" }, "ab_update": { "type": "boolean" }, "android_major_version": { "type": "integer" }, "android_minimum_sdk_level": { "type": "integer" }, "android_minor_version": { "type": "string" }, "android_sdk_level": { "type": "integer" }, "build_arch": { "type": "string" }, "build_flavor": { "type": "string" }, "build_hash": { "type": "string" }, "build_ota_hash": { "type": "string" }, "build_job_url": { "type": "string" }, "build_job_id": { "type": "integer" }, "build_fingerprint_hash": { "type": "string" }, "build_type": { "type": "string" }, "build_url": { "type": "string", "format": "url" }, "build_update_meta_data": { "type": "string", "format": "json" }, "build_update_url": { "type": "string", "format": "url" }, "file_size_kb": { "type": "integer" }, "foundation_build_number": { "type": "integer" }, "foundation_major_number": { "type": "integer" }, "foundation_minor_number": { "type": "integer" }, "foundation_name": { "type": "string" }, "model_display_name": { "type": "string" }, "build_job_params": { "type": "string", "format": "json" }, "prebuilt_app_info": { "type": "string", "format": "json" }, "release_notes": { "type": "string", "format": "json" }, "release_rating": { "type": "string" }, "source_build_id": { "type": "string" }, "build_state": { "type": "string", "enum": [ "released", "to_be_deprecated", "unavailable" ] }, "device_model_id": { "type": "string" }, "approved": { "type": "boolean" } } }, "foundation_Error_401_Unauthorized": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 401 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "foundation_Error_500_Internal_Server_Error": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 500 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "foundation_Error_404_Not_Found": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 404 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "foundation_Foundry_Build_PUT_Request_V1": { "type": "object", "properties": { "approve": { "type": "boolean" }, "user_remarks": { "type": "string" } } }, "foundation_Error_400_Bad_Data": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 400 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "foundation_Device_Model_V1": { "type": "object", "properties": { "model_display_name": { "type": "string", "example": "Motorola Edge 20 - T2E20" }, "manufacturer": { "type": "string", "example": "Motorola" }, "model": { "type": "string", "example": "Edge 20" }, "profile_name": { "type": "string", "example": "Tacobell" }, "profile_variant": { "type": "string", "example": "T2E20" }, "update_compatible_android_api_level_begin": { "type": "integer", "example": 11 }, "device_model_id": { "type": "string", "format": "uuid", "example": "eb566c45-f841-41e5-a0af-435e90a96cae" }, "auto_update": { "type": "boolean", "example": false }, "latest": { "type": "boolean", "example": false }, "locked_build_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2023-12-07T17:14:46.419449+05:30" }, "updated_at": { "type": "string", "format": "date-time", "example": "2023-12-07T17:14:46.419449+05:30" }, "created_by": { "type": "string", "example": "FoundryAdmin" }, "updated_by": { "type": "string", "example": "FoundryAdmin" } } }, "foundation_Device_Model_PUT_Request_V1": { "type": "object", "properties": { "auto_update": { "type": "boolean", "description": "Enables/disables automatic updates for the device model. The other properties (latest and locked_build_id) are processed only if autoupdate is set to true." }, "latest": { "type": "boolean", "description": "Configures Foundry service to automatically lock to the latest approved build (whenever available) if set to true." }, "locked_build_id": { "type": "string", "description": "Specifies the UUID of the build which needs to be locked for automatic updates." } } }, "foundation_Error_403_Forbidden": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "default": 403 }, "message": { "type": "string" }, "content": { "type": "object" } }, "required": [ "code", "message" ] }, "foundation_Foundry_Event_V1": { "type": "object", "properties": { "stack": { "type": "string" }, "tenant": { "type": "string" }, "enterprise_id": { "type": "string" }, "actor": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "event_message": { "type": "string" }, "event_type": { "type": "string" }, "resource": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } } }, "meta": { "type": "object", "properties": { "user_remarks": { "type": "string" }, "change_type": { "type": "string" }, "device_model": { "type": "string" } } }, "created_timestamp": { "type": "integer" } } }, "reports_GetReportTypesResponse": { "type": "object", "properties": { "content": { "type": "object", "properties": { "report_types": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "display_name": { "type": "string" }, "description": { "type": "string" }, "last_generated_at": { "type": "string" }, "available_from": { "type": "string" } } } } } } } }, "reports_ReportsErrorResponse": { "type": "object", "properties": { "status": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } }, "reports_DeviceAppsFilter": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "example": "2024-08-28", "nullable": true, "description": "Date of report. If provided, this value will override start_time and end_time values. Example: \"2024-08-28\". Must be a date later than July 1st, 2024." }, "package_name": { "type": "array", "nullable": true, "items": { "type": "string" }, "example": [ "com.android.chrome" ] }, "app_state": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "SHOW", "HIDE", "DISABLE", "LAUNCHABLE_BUT_HIDDEN" ] }, "example": [ "SHOW" ] }, "device_os": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "Android", "iOS" ] }, "example": [ "Android" ] }, "platform": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "Android", "Apple", "Linux", "Windows" ] }, "example": [ "Android" ] } } }, "reports_DeviceFilter": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "example": "2025-03-17", "nullable": true, "description": "Date of report. If provided, this value will override start_time and end_time values. Example: \"2025-03-17\". Must be a date later than May 17th, 2025." }, "platform": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "Android", "Apple", "Linux", "Windows" ] }, "example": [ "Android" ] } } }, "reports_Report": { "type": "object", "properties": { "report_type": { "type": "string", "enum": [ "device_apps", "device" ], "example": "device_apps" }, "start_time": { "description": "Start time of the report in UTC format. Example: \"2024-08-28T00:00:00Z\". Must be a date and time later than July 1st, 2024.", "type": "string", "format": "date-time", "example": "2024-08-28T00:00:00Z" }, "end_time": { "description": "End time of the report in UTC format. Example: \"2024-08-29T00:00:00Z\". Must be a date and time later than July 1st, 2024 and equal to the start_time.", "type": "string", "format": "date-time", "example": "2024-08-28T00:00:00Z" }, "is_download": { "type": "boolean" }, "filters": { "type": "object", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/reports_DeviceAppsFilter" }, { "$ref": "#/components/schemas/reports_DeviceFilter" } ] } }, "required": [ "report_type" ] }, "reports_CreateReportResponse": { "type": "object", "properties": { "content": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "SUCCEEDED", "FAILED", "CANCELED", "CLOSED" ] } } } } }, "reports_GetReportResponsePreview": { "type": "object", "properties": { "content": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "SUCCEEDED", "FAILED", "CANCELED", "CLOSED" ] }, "schema": { "type": "object", "properties": { "column_count": { "type": "integer" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "position": { "type": "integer" }, "type_name": { "type": "string" }, "type_text": { "type": "string" } } } } } }, "data_array": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } } } } } }, "reports_GetReportResponseDownload": { "type": "object", "properties": { "content": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "SUCCEEDED", "FAILED", "CANCELED", "CLOSED" ] }, "schema": { "type": "object", "properties": { "column_count": { "type": "integer" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "position": { "type": "integer" }, "type_name": { "type": "string" }, "type_text": { "type": "string" } } } } } }, "external_link": { "type": "string" } } } } }, "geofence_PolygonGeometry": { "type": "object", "description": "Polygon geometry with coordinates as array of coordinate objects", "required": [ "type", "coordinates" ], "properties": { "type": { "type": "string", "enum": [ "polygon" ], "example": "polygon" }, "coordinates": { "type": "array", "description": "Array of coordinate objects, each containing latitude and longitude", "items": { "type": "object", "description": "Coordinate object with latitude and longitude", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude coordinate", "example": 41.8902 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude coordinate", "example": 12.4924 } } }, "minItems": 3, "maxItems": 100, "example": [ { "latitude": 41.8902, "longitude": 12.4924 }, { "latitude": 41.8903, "longitude": 12.4925 }, { "latitude": 41.8904, "longitude": 12.4926 } ] } } }, "geofence_CircleGeometry": { "type": "object", "description": "Circle geometry with center coordinates and radius", "required": [ "type", "coordinates", "radius" ], "properties": { "type": { "type": "string", "enum": [ "circle" ], "example": "circle" }, "coordinates": { "type": "array", "description": "Array with single coordinate object containing latitude and longitude", "minItems": 1, "maxItems": 1, "items": { "type": "object", "description": "Coordinate object with latitude and longitude", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude coordinate", "example": 41.8902 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude coordinate", "example": 12.4924 } } }, "example": [ { "latitude": 41.8902, "longitude": 12.4924 } ] }, "radius": { "type": "number", "minimum": 0.1, "description": "Radius in meters", "example": 100 } } }, "geofence_GeofenceResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-1111-1111-111111111111", "description": "Unique identifier for the geofence" }, "name": { "type": "string", "example": "Warehouse Perimeter", "description": "Name of the geofence" }, "description": { "type": "string", "example": "A polygon-shaped geofence", "description": "Description of the geofence" }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "lockdown", "beep" ] }, "minItems": 0, "maxItems": 2, "example": [ "lockdown", "beep" ], "description": "Actions configured for this geofence. Empty array means no actions." }, "geometry": { "oneOf": [ { "$ref": "#/components/schemas/geofence_PolygonGeometry" }, { "$ref": "#/components/schemas/geofence_CircleGeometry" } ], "discriminator": { "propertyName": "type" } }, "created_at": { "type": "string", "format": "date-time", "example": "2024-06-24T14:00:00Z", "description": "When the geofence was created" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-06-24T15:00:00Z", "description": "When the geofence was last updated" } }, "required": [ "id", "name", "actions", "geometry", "created_at", "updated_at" ] }, "geofence_DeviceSummaryResponse": { "type": "object", "description": "Summary statistics of devices in relation to a geofence", "properties": { "total_devices": { "type": "integer", "minimum": 0, "description": "Total number of devices associated with the geofence", "example": 100 }, "inside_count": { "type": "integer", "minimum": 0, "description": "Number of devices currently inside the geofence", "example": 60 }, "outside_count": { "type": "integer", "minimum": 0, "description": "Number of devices currently outside the geofence", "example": 35 }, "unknown_count": { "type": "integer", "minimum": 0, "description": "Number of devices with unknown state (neither inside nor outside)", "example": 5 } }, "required": [ "total_devices", "inside_count", "outside_count", "unknown_count" ] }, "geofence_BlueprintUsageItem": { "type": "object", "description": "Statistics about blueprint usage within a geofence", "properties": { "blueprint_id": { "type": "string", "format": "uuid", "description": "UUID of the blueprint", "example": "550e8400-e29b-41d4-a716-446655440000" }, "blueprint_version_number": { "type": "integer", "description": "Blueprint version number", "example": 1 }, "device_count": { "type": "integer", "minimum": 0, "description": "Number of devices using this blueprint revision", "example": 25 } }, "required": [ "blueprint_id", "blueprint_version_number", "device_count" ] }, "geofence_GeofenceListResponse": { "type": "object", "description": "Geofence response for list operations. Extends GeofenceResponse with optional summary fields when includeSummary=true.", "allOf": [ { "$ref": "#/components/schemas/geofence_GeofenceResponse" }, { "type": "object", "properties": { "device_summary": { "$ref": "#/components/schemas/geofence_DeviceSummaryResponse", "description": "Device statistics for this geofence. Only included when include_summary=true." }, "blueprints": { "type": "array", "items": { "$ref": "#/components/schemas/geofence_BlueprintUsageItem" }, "description": "Blueprint usage statistics for this geofence (top 5). Only included when include_summary=true." } } } ] }, "geofence_ErrorResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message", "example": "Invalid input" }, "content": { "type": "object", "description": "Additional error details", "example": {} } }, "required": [ "message", "content" ] }, "geofence_GeofenceRequest": { "type": "object", "description": "Request payload for creating a geofence. Specify either a Polygon or Circular geofence.", "required": [ "name", "geometry" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Geofence 1", "description": "Name of the geofence" }, "description": { "type": "string", "maxLength": 1000, "example": "A geofence that is either polygonal or circular.", "description": "Optional description of the geofence" }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "lockdown", "beep" ] }, "minItems": 0, "maxItems": 2, "example": [ "lockdown", "beep" ], "description": "Actions to trigger when geofence conditions are met. Empty array means no actions." }, "geometry": { "oneOf": [ { "$ref": "#/components/schemas/geofence_PolygonGeometry" }, { "$ref": "#/components/schemas/geofence_CircleGeometry" } ], "discriminator": { "propertyName": "type" } } } }, "geofence_DeviceListingItem": { "type": "object", "description": "Information about a device and its state within a geofence", "properties": { "device_id": { "type": "string", "format": "uuid", "description": "UUID of the device", "example": "660e8400-e29b-41d4-a716-446655440000" }, "blueprint_id": { "type": "string", "format": "uuid", "description": "UUID of the blueprint used by this device", "example": "550e8400-e29b-41d4-a716-446655440000" }, "blueprint_version_number": { "type": "integer", "description": "Blueprint version number used by this device", "example": 1 }, "inside": { "type": "boolean", "nullable": true, "description": "Whether the device is currently inside the geofence. Null means unknown state.", "example": true }, "state_changed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the device's geofence state was last changed. Null means unknown time.", "example": "2025-07-24T09:00:00Z" }, "latitude": { "type": "number", "format": "double", "nullable": true, "description": "Last known latitude for the device, rounded to 4 decimal places.", "example": 37.7749 }, "longitude": { "type": "number", "format": "double", "nullable": true, "description": "Last known longitude for the device, rounded to 4 decimal places.", "example": -122.4194 }, "location_updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the device location was last updated.", "example": "2025-07-24T09:05:00Z" } }, "required": [ "device_id", "blueprint_id", "blueprint_version_number" ] } }, "parameters": { "esper_cloud_api_EnterpriseID": { "name": "enterprise_id", "description": "Enterprise ID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "esper_cloud_api_GroupThumbnailID": { "name": "thumbnail_id", "description": "Group thumbnail ID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "esper_cloud_api_InviteID": { "name": "invite_id", "description": "Invite ID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "esper_cloud_api_UserID": { "name": "user_id", "description": "User ID", "in": "path", "required": true, "schema": { "type": "integer" } }, "esper_cloud_api_AuthNUserID": { "name": "user_id", "description": "AuthN User Id. The authn_user_id from the Get Users response.", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "esper_cloud_api_GroupID": { "name": "group_id", "description": "Device Group ID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "esper_cloud_api_BlueprintID": { "name": "blueprint_id", "description": "Blueprint ID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "esper_cloud_api_BlueprintRevisionID": { "name": "revision_id", "description": "Blueprint Revision ID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "esper_cloud_api_DirectoryRecordID": { "name": "directory_record_id", "description": "Directory record ID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "esper_cloud_api_IsDefault": { "name": "is_default", "description": "Is Default", "in": "query", "required": false, "schema": { "type": "boolean" } }, "esper_cloud_api_ConnectionID": { "name": "connection_id", "description": "Connection ID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "esper_cloud_api_RoleID": { "name": "role_id", "description": "Role ID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "esper_cloud_api_PersonalAccessTokenID": { "name": "personal_access_token_id", "description": "Personal Access Token Id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "esper_cloud_api_LegacyUserID": { "name": "legacy_user_id", "description": "Legacy User ID", "in": "query", "required": false, "schema": { "type": "integer" } }, "reports_ReportID": { "name": "report_id", "description": "Report ID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "geofence_OffsetParam": { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip before starting to collect the result set" }, "geofence_LimitParam": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Maximum number of items to return" }, "geofence_IdsParam": { "name": "ids", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}(,[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})*$" }, "description": "Comma-separated list of geofence UUIDs to filter by. When provided, only geofences with matching IDs will be returned.", "example": "11111111-1111-1111-1111-111111111111,22222222-2222-2222-2222-222222222222" }, "geofence_IncludeSummaryParam": { "name": "include_summary", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Whether to include device summary and blueprint usage statistics with each geofence. When true, adds device_summary and blueprints fields to each result.", "example": true }, "geofence_IncludeCountParam": { "name": "include_count", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Whether to include the total count of geofences in the response. When true, adds a count field to the response.", "example": true }, "geofence_SearchParam": { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search string to filter geofences by name (case-insensitive partial match).", "example": "warehouse" }, "geofence_NameParam": { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact geofence name to filter by (case-sensitive exact match).", "example": "Test Geofence 1" }, "geofence_IsDeletedParam": { "name": "is_deleted", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "When true, returns only soft-deleted geofences. When omitted or false, returns only live geofences.", "example": true }, "geofence_GeofenceIdParam": { "name": "geofence_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the geofence", "example": "f5316a75-f186-4769-970e-28d6a1a0e110" }, "geofence_XEsperTenantIdHeader": { "name": "X-Esper-Tenant-Id", "in": "header", "required": true, "x-internal": true, "schema": { "type": "string", "format": "uuid" }, "description": "Esper tenant ID associated with the request" }, "geofence_XCallerIdHeader": { "name": "X-Caller-Id", "in": "header", "required": true, "x-internal": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Unique identifier for the caller" }, "geofence_InsideParam": { "name": "inside", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Filter devices by whether they are inside (true) or outside (false) the geofence", "example": true }, "geofence_BlueprintIdParam": { "name": "blueprint_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter devices by blueprint ID", "example": "550e8400-e29b-41d4-a716-446655440000" }, "geofence_BlueprintVersionNumberParam": { "name": "blueprint_version_number", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filter devices by blueprint version number", "example": 1 } }, "examples": { "device_example_devices": { "summary": "An example where the query specifies a list of devices.", "value": { "operation_type": "CONVERGE", "schedule_type": "IMMEDIATE", "operation_device_query": { "device_ids": "460a4c28-b974-4c20-99b5-29aa6f10054f,560a4c28-b974-4c20-99b5-29aa6f10054e" }, "arguments": { "converge_with_provision": true } }, "description": "An example where the query specifies a list of devices with specific values." }, "device_example_filters": { "summary": "An example with devices filters.", "value": { "operation_type": "CONVERGE", "schedule_type": "IMMEDIATE", "operation_device_query": { "device_request": { "group_multi": "460a4c28-b974-4c20-99b5-29aa6f10054f,760a4c28-b974-4c20-99b5-29aa6f10054e", "state": "1" } }, "arguments": { "converge_with_provision": true } }, "description": "An example with dynamic filters, where 'filter1' and 'filter2' are used to apply specific criteria (Same as existing device api filters).\n- active_connection (string)\n- android_version (string)\n- assigned_blueprint_id (string)\n- battery_level_gte (string)\n- battery_level_lte (string)\n- current_blueprint_id (string)\n- current_blueprint_version_id (string)\n- current_blueprint_version_id_net (string)\n- device_source (string)\n- group_multi (string)\n- group_multi_immediate (string)\n- ios_version (string)\n- ipados_version (string)\n- tvos_version (string)\n- windows_version (string)\n- is_gms (string)\n- last_seen_gt (time.Time)\n- last_seen_lt (time.Time)\n- managed_by (string)\n- ordering (string)\n- os (string)\n- platform (string)\n- policy_multi (string)\n- provisioned_on_gt (time.Time)\n- provisioned_on_lt (time.Time)\n- search (string)\n- security_status (string)\n- serial (string)\n- state (string)\n- tags (string)\n- template_multi (string)\n- udid (string)\n- is_seamless (string)\n- is_locked_down (string)\n- ungrouped_only (boolean)\n" } } }, "x-tagGroups": [ { "name": "ESPER CLOUD API", "tags": [ "esper_cloud_api_Company Settings", "esper_cloud_api_Application", "esper_cloud_api_Application V1", "esper_cloud_api_AndroidDevice", "esper_cloud_api_Device Group", "esper_cloud_api_Token (Deprecated)", "esper_cloud_api_Commands V2", "esper_cloud_api_Enterprise Policy", "esper_cloud_api_Geofence", "esper_cloud_api_Content", "esper_cloud_api_User (Deprecated)", "esper_cloud_api_User", "esper_cloud_api_Blueprint (Deprecated)", "esper_cloud_api_Directory Record", "esper_cloud_api_Tile Icon", "esper_cloud_api_Alerts", "esper_cloud_api_Alarms", "esper_cloud_api_Wallpapers", "esper_cloud_api_Device Telemetry", "esper_cloud_api_Daily and Custom Reports", "esper_cloud_api_SSO Connections", "esper_cloud_api_Roles", "esper_cloud_api_Personal Access Token" ] }, { "name": "BLUEPRINTS", "tags": [ "blueprints_Blueprints API", "blueprints_Custom Actions API", "blueprints_Background Scripts API" ] }, { "name": "PIPELINES", "tags": [ "pipelines_System Status Code", "pipelines_System", "pipelines_Pipelines", "pipelines_Stages", "pipelines_Target Lists", "pipelines_Targets", "pipelines_Device Groups", "pipelines_Operation Lists", "pipelines_Operations", "pipelines_Pipeline Runs", "pipelines_Stage Runs", "pipelines_Target Runs" ] }, { "name": "DEVICE", "tags": [ "device_Device", "device_Device Heartbeat", "device_Device Apps", "device_Device Enrollment in EMM", "device_Operations", "device_DeviceOperations", "device_MultiOS Remote Viewer" ] }, { "name": "APPS MANAGEMENT", "tags": [ "apps_management_VPP License Management", "apps_management_VPP App Management", "apps_management_Tenant Apps", "apps_management_Apple App Store", "apps_management_App List", "apps_management_Webclips", "apps_management_Provisioning Profiles", "apps_management_Preferred Regions", "apps_management_OEM Config Schema", "apps_management_Esper Apps", "apps_management_Tenant Esper Apps" ] }, { "name": "COMMANDS", "tags": [ "commands_Command Request", "commands_Command Status" ] }, { "name": "DRIFT", "tags": [ "drift_Converge", "drift_Converge Command", "drift_Blueprint Drift" ] }, { "name": "DEVICE ONBOARDING", "tags": [ "device_onboarding_DEP Sync Request", "device_onboarding_ABM Provisioning" ] }, { "name": "TENANT", "tags": [ "tenant_APNs certificate", "tenant_DEP Profile", "tenant_DEP Tokens", "tenant_VPP Token Management", "tenant_Google Enterprise", "tenant_MDM Service Config" ] }, { "name": "FOUNDATION", "tags": [ "foundation_FoundryBuilds", "foundation_FoundryDeviceModels", "foundation_FoundryEvents" ] }, { "name": "REPORTS", "tags": [ "reports_Reports API" ] }, { "name": "GEOFENCE", "tags": [ "geofence_Geofences", "geofence_Device State" ] } ] }