PI Vision API Reference
- Last UpdatedJul 08, 2026
- 14 minute read
- PI System
- PI Vision API Reference
- Developer
With the release of PI Vision 2021, PI Vision introduces new capabilities that allow PI Vision displays to be imported or exported using the PI Vision API. It is an alternative to using PI Vision Display Utility offline display files (PDIX).
This documentation covers the supported usage and functionality of the PI Vision API for display import and export.
Guidelines for Usage
The guidelines below cover the supported import and export functionality of the PI Vision API. Any modifications of code outside of these guidelines is not permitted.
The PI Vision API enables the export and import of PI Vision displays. The modification of JSON content permitted is limited to display metadata covered in this documentation. This API does not permit the modification of any display definition content such as symbol definition.
Security
Most PI Vision Display API endpoints require authentication with the request. The authenticated user must be authorized as a Utility User or as an Administrator in PI Vision. The exception to this is the Version endpoint, which does not require authentication, and is used primarily to verify that the API service is responsive. In addition to authentication, any request that is not a GET request must include a non-empty value in the X-Requested-With header.
Check server configuration
The method of authentication varies based on the PI Vision configuration. To determine the authentication configuration, use the AuthenticationInfo endpoint. Similar to the Version endpoint, the AuthenticationInfo endpoint does not require authentication.
Invoke-WebRequest -Uri 'https://myServer/PIVision/Utility/api/v1/AuthenticationInfo'
Windows authentication
Using PowerShell, specify -UseDefaultCredentials to authenticate as the current signed-on Windows user.
Invoke-WebRequest -UseDefaultCredentials -Uri 'https://myServer/PIVision/Utility/api/v1/folders'
Using cURL, specify --negotiate to authenticate as the current signed-on Windows user. To authenticate as a different user (or if not on Windows), pass the username and password using -u USERNAME:PASSWORD.
curl --negotiate https://myServer/PIVision/Utility/api/v1/folders
curl --negotiate -u domain\user:mypassword https://myServer/PIVision/Utility/api/v1/folders
OpenID Connect
When PI Vision is configured to authenticate users with OpenID Connect only, you must acquire an access token from the active Identity Server to call the PI Vision API. The token must be provided as a Bearer token in the Authorization header.
The active AIM server is returned from the AuthenticationInfo endpoint and should be used when acquiring new access tokens.
Using PowerShell:
$token = .\GetToken.ps1 -PIVisionServer 'https://myServer/PIVision' # see GetToken.ps1 in "Examples" section
Invoke-WebRequest -Headers @{ Authorization = "Bearer $token" } -Uri 'https://myServer/PIVision/Utility/api/v1/folders'
Using cURL:
curl -H "Authorization: Bearer myAccessTokenHere" https://myServer/PIVision/Utility/api/v1/folders
OpenID Connect and Windows
When PI Vision is configured for "OpenID Connect and prompt for Windows credentials when required", callers must authenticate with an access token and with a Windows identity. In this mode, the access token must be sent in a custom header named PVBearerToken. Note that the Bearer prefix is not used in this header.
Using PowerShell:
$token = .\GetToken.ps1 -PIVisionServer 'https://myServer/PIVision' # see GetToken.ps1 in "Examples" section
Invoke-WebRequest -UseDefaultCredentials -Headers @{ PVBearerToken = $token } -Uri 'https://myServer/PIVision/Utility/api/v1/folders'
Using cURL:
curl --negotiate -H "PVBearerToken: myAccessTokenHere" https://myServer/PIVision/Utility/api/v1/folders
Pagination
Some GET operations utilize pagination to specify or limit the number of results returned in the response. This provides support for low-speed networks and limits memory consumption on the client side.
One of example of this is the GET /Folders endpoint. The following parameters can be passed to configure the results returned via pagination:
skip – Allows the user to skip a specific number of records. The default value is
0. If this parameter is omitted, no records are skipped.count – Allows the user to set the specific number of records to be returned. The default value is
100.
In the case where there are more results than what is requested, the response will contain a HasMore field that indicates that there are more records beyond the requested amount.
The following are pagination examples.
Lets assume that the PI Vision server has two folders at the root level.
Request: GET /Folders?count=1
{
"Items": [
{
"Id": 1,
"Name": "Folder1",
"ParentId": null,
"HasChildren": true
}
],
"HasMore": true <-- Indicates that there are more records available on the server side
}
One folder returned, and HasMore returns true since there is one more folder left to request. It can be requested using following example.
Request: GET /Folders?count=2&skip=1
{
"Items": [
{
"Id": 2,
"Name": "Folder2",
"ParentId": null,
"HasChildren": false
}
],
"HasMore": false
}
The first folder was skipped, and the remaining folder was returned.
Operations
The primary operations provided by the PI Vision Display API are exporting and importing displays. Displays can be exported by calling the GET /Displays/Export endpoint and imported by calling the PUT /Displays endpoint. It is recommended that the request body for PUT /Displays be taken from the content of the GET /Displays/Export response with minimal changes.
Selecting displays
Before exporting, use the GET /Displays endpoint to list the displays in a folder. The optional FolderId parameter controls which folder is listed. It accepts the case-insensitive keywords Home and Unorganized, or an integer folder Id. When omitted, it defaults to Home (the root folder).
List displays in the Home (root) folder by omitting the parameter.
Invoke-WebRequest -UseDefaultCredentials -Uri 'https://myServer/PIVision/Utility/api/v1/displays'
You can also explicitly request the Home folder using the Home keyword (this yields the same result as above):
Invoke-WebRequest -UseDefaultCredentials -Uri 'https://myServer/PIVision/Utility/api/v1/displays?FolderId=Home'
List displays in the Unorganized folder by passing the Unorganized keyword:
Invoke-WebRequest -UseDefaultCredentials -Uri 'https://myServer/PIVision/Utility/api/v1/displays?FolderId=Unorganized'
List displays within a user-created folder by passing that folder's integer Id:
Invoke-WebRequest -UseDefaultCredentials -Uri 'https://myServer/PIVision/Utility/api/v1/displays?FolderId=38807'
Modifying displays before import
You can modify the following fields between the export response and input request body:
ParentId – ID of the parent PI Vision folder. Use
null(or-1) to place the display in the Home (root) folder, or a folder Id to place it in a specific folder. The folder structure should be recreated before the PUT /Displays call.Unorganized – When set to
true, the display is written to the Unorganized folder andParentIdis ignored.Owner – Provides the target display owner for the imported display. The format is
DOMAIN\\username.Name – Sets the PI Vision display name. The maximum length is 1024 characters.
Identities – Specifies the list of AF identity groups that have access to the imported display. To get the list of available AF identities, use the
OSIsoft.AF.AFSecurityIdentity.FindSecurityIdentitiesmethod from OSIsoft.AFSDK. To get the list of current identities for a specific display, use the GET /Displays/{id}/AccessControl endpoint.Labels – Labels associated with the PI Vision display. The maximum label name length is 100 characters.
It is also possible to get and set identities by using the GET /Displays/{id}/AccessControl and PUT /Displays/{id}/AccessControl endpoints.
Folders structure can be managed by using the GET /Folders and PUT /Folder endpoints. Folder name has a maximum length of 1024 characters.
The ParentId and Unorganized fields together control the folder the display is written to. The examples below start from an exported display definition (see Export displays to disk) and adjust only the placement fields before writing, where $displayInfo holds the display definition JSON. Because these are not GET requests, the X-Requested-With header must be included (see Security).
Write the display to the Home (root) folder by setting ParentId to null (or -1) and leaving Unorganized as false:
$displayInfo = $displayInfo -creplace '"ParentId":(null|-?\d+)', '"ParentId":null'
$displayInfo = $displayInfo -creplace '"Unorganized":(true|false)', '"Unorganized":false'
Invoke-WebRequest -UseDefaultCredentials `
-Uri 'https://myServer/PIVision/Utility/api/v1/displays' `
-Method 'Put' `
-Headers @{ 'X-Requested-With' = 'PowerShell' } `
-ContentType 'application/json; charset=utf-8' `
-Body $displayInfo
Write the display to the Unorganized folder by setting Unorganized to true (ParentId is ignored):
$displayInfo = $displayInfo -creplace '"Unorganized":(true|false)', '"Unorganized":true'
Invoke-WebRequest -UseDefaultCredentials `
-Uri 'https://myServer/PIVision/Utility/api/v1/displays' `
-Method 'Put' `
-Headers @{ 'X-Requested-With' = 'PowerShell' } `
-ContentType 'application/json; charset=utf-8' `
-Body $displayInfo
Write the display to a user-created folder by setting ParentId to that folder's integer Id and leaving Unorganized as false:
$displayInfo = $displayInfo -creplace '"ParentId":(null|-?\d+)', '"ParentId":38807'
$displayInfo = $displayInfo -creplace '"Unorganized":(true|false)', '"Unorganized":false'
Invoke-WebRequest -UseDefaultCredentials `
-Uri 'https://myServer/PIVision/Utility/api/v1/displays' `
-Method 'Put' `
-Headers @{ 'X-Requested-With' = 'PowerShell' } `
-ContentType 'application/json; charset=utf-8' `
-Body $displayInfo
Typical workflow
In general, the typical workflow for using the PI Vision Display API should be:
Use GET /Folders and GET /Displays to select displays.
Export displays into temporary storage (memory, file on disk, etc.) using the GET /Displays/{id}/Export endpoint.
Adjust the folder structure on the target PI Vision server by using the GET /Folders and PUT /Folders endpoints.
Update the supported fields for every imported display. For example: updating the target Folder Id in ParentId field or replacing the owner in Owner field.
Import displays into designated location using the PUT /Displays endpoint.
Handling duplicate display names
In cases where displays are imported using the API to a location already containing one or more displays of the same name, use the DuplicateDisplayWriteBehavior field within the display definition to indicate the desired behavior. The same field is returned in the response when the import is completed.
Within the display definition, the DuplicateDisplayWriteBehavior property is added to the top level, and contains one of the following values:
"DuplicateDisplayWriteBehavior": "Append"
"DuplicateDisplayWriteBehavior": "Overwrite"
"DuplicateDisplayWriteBehavior": "Skip"
Append
A value of Append creates a new PI Vision display in the target folder with a numeral in parentheses appended to the display name.
The response from the import call reflects this new name and the result of the import operation:
{
"Id": 17,
"Name": "Sample Display (1)",
"PatchErrors": [
],
"DuplicateDisplayWriteBehavior": "Append"
}
Append is the default value for DuplicateDisplayWriteBehavior. If the display definition for the PI Vision display to be imported does not contain DuplicateDisplayWriteBehavior, the default behavior is to create a new display in the target folder with a modified display name.
Overwrite
A value of Overwrite overwrites a PI Vision display with the same name as the imported display definition if it already exists.
The response from the import call reflects this new name and the result of the import operation:
{
"Id": 18,
"PatchErrors": null,
"DuplicateDisplayWriteBehavior": "Overwrite"
}
Skip
A value of Skip does not replace a PI Vision display in the target location if a display with the same name as the imported display definition already exists.
The response from the import call reflects this and the result of the import operation:
{
"Name": "Sample Display",
"PatchErrors": [
],
"DuplicateDisplayWriteBehavior": "Skip"
}
Examples
To illustrate possible uses of the API, the following example PowerShell scripts show how the API can perform common operations, such as exporting and importing displays. These scripts are meant to be a guide to illustrate the various features of the PI Vision display API. The scripts include:
Export.ps1exports PI Vision displays and saves them as .json files on diskImport.ps1reads PI Vision displays from .json files on disk and imports them into PI VisionFunctions.ps1contains shared functions used by the above two scriptsGetToken.ps1retreives an access token from the Identity Server (usable if PI Vision is configured for OpenID Connect)
To experiment with these scripts, copy them to your local environment and save them as .ps1 files, then invoke the scripts with the required parameters.
Export.ps1 saves each display as a .json file in a local directory (.\displays by default), and Import.ps1 reads .json files back from a local directory (.\displays by default as well). The export and import steps are connected only through this shared local directory. Import.ps1 does not read from the source server. If you change the location, pass a matching -DestinationDirectory to Export.ps1 and -SourceDirectory to Import.ps1.
For example:
# Export all displays from PI Vision folder 'Example\Folder' to files stored in .\displays
.\Export.ps1 -SourceServer 'https://SourceServer/pivision' -SourceFolderPath 'Example', 'Folder'
# Read the display files from .\displays and write them to a different PI Vision server under the 'Imported' folder
.\Import.ps1 -DestinationServer 'https://DestServer/pivision' -DestinationFolderPath 'Imported'
# Export displays from the Unorganized folder to .\displays, then import those same local files to the Unorganized folder on another server
.\Export.ps1 -SourceServer 'https://SourceServer/pivision' -SourceFolderPath 'Unorganized'
.\Import.ps1 -DestinationServer 'https://DestServer/pivision' -DestinationFolderPath 'Unorganized'
# Export displays from a folder to .\displays, then import those same local files to the Home folder on another server
.\Export.ps1 -SourceServer 'https://SourceServer/pivision' -SourceFolderPath 'Example', 'Folder'
.\Import.ps1 -DestinationServer 'https://DestServer/pivision' -DestinationFolderPath 'Home'
# Export displays to a custom local directory (exampleDirectory), then import from that same directory
.\Export.ps1 -SourceServer 'https://SourceServer/pivision' -SourceFolderPath 'Example', 'Folder' -DestinationDirectory 'C:\temp\exampleDirectory'
.\Import.ps1 -DestinationServer 'https://DestServer/pivision' -DestinationFolderPath 'Imported' -SourceDirectory 'C:\temp\exampleDirectory'
Or if your PI Vision server is configured to use OpenID Connect, get an access token first and pass it as a parameter to the other scripts:
# Get an access token and store it so we can pass it to PI Vision
$token = .\GetToken.ps1 -PIVisionServer 'https://SourceServer/PIVision'
# Export all displays from the Home folder of PI Vision and write them to 'C:\temp\exports'
.\Export.ps1 -SourceServer 'https://SourceServer/pivision' -DestinationDirectory 'C:\temp\exports' -Token $token
Export displays to disk
The following script, Export.ps1, exports all PI Vision displays from a PI Vision folder and stores them as files in a local directory (defaults to .\displays).
#requires -version 4
<#
.SYNOPSIS
An example script capable of exporting PI Vision displays to disk.
.DESCRIPTION
Read displays from the PI Vision server and write them as .json files into the
provided destination folder.
This script does not have comprehensive error handling (no retries, no skips).
#>
param(
# The source PI Vision server (without trailing slash)
[Parameter(Mandatory)]
[string]$SourceServer,
# The source PI Vision folder path, as a list of folder names.
# If your folder is "Demo\Test1", you would pass "-SourceFolderPath 'Demo', 'Test1'"
# Pass 'Unorganized' to read from the Unorganized folder. To read from the Home
# folder, pass 'Home' or omit this parameter.
[string[]]$SourceFolderPath,
# Destination directory to write displays into. Default is '.\displays'
[string]$DestinationDirectory = '.\displays',
# Bearer token to use when connecting to PI Vision. Not required if connecting
# to PI Vision using Windows authentication.
[string]$Token = $null
)
# Stop if any errors occur
$ErrorActionPreference = 'Stop'
# Import functions
Import-module "$PSScriptRoot\functions.ps1" -Force
# Create destination directory if missing
if (-not (Test-Path $DestinationDirectory)) {
New-Item -Path $DestinationDirectory -ItemType Directory
}
# Ensure we can connect to the PI Vision server
Test-PIVisionApiConnection -ServerUrl $sourceServer -Token $Token
# The folder to read displays from: a folder path, 'Home', or 'Unorganized'.
# Omit to default to Home.
$sourceFolderId = $null
if ($SourceFolderPath.Count -eq 1 -and $SourceFolderPath[0] -imatch '^Unorganized