openapi: 3.1.0
info:
title: OSIsoft PI Web API
description: >-
OSIsoft PI Web API (now part of AVEVA) provides a REST interface for accessing
the PI System process historian. APIs enable real-time and historical time-series
data retrieval, event frame queries, asset framework hierarchy navigation, and
calculated data for industrial process monitoring.
version: 2023.2.0
contact:
name: AVEVA Support
url: https://softwaresupport.aveva.com
license:
name: AVEVA Software License
url: https://www.aveva.com/legal/
servers:
- url: https://{piwebapi_host}/piwebapi
description: PI Web API server
variables:
piwebapi_host:
default: piwebapi.example.com
description: PI Web API server hostname
security:
- basicAuth: []
- kerberos: []
tags:
- name: AssetServers
description: Asset Framework server navigation
- name: Attributes
description: AF attribute management
- name: BatchRequests
description: Batch and parallel request execution
- name: DataServers
description: PI Data Archive server management
- name: Elements
description: AF element management
- name: EventFrames
description: Event frame query and management
- name: PIPoints
description: PI point (tag) management and data
- name: Streams
description: Time-series data streams
paths:
/dataservers:
get:
operationId: listDataServers
summary: List PI Data Archive servers
description: Returns all registered PI Data Archive servers accessible via this PI Web API instance.
tags:
- DataServers
parameters:
- name: selectedFields
in: query
description: Comma-separated list of fields to return
schema:
type: string
responses:
'200':
description: List of data servers
content:
application/json:
schema:
type: object
properties:
Items:
type: array
items:
$ref: '#/components/schemas/DataServer'
Links:
$ref: '#/components/schemas/PaginationLinks'
'401':
$ref: '#/components/responses/Unauthorized'
/dataservers/{webId}/points:
get:
operationId: listPIPoints
summary: List PI points on a server
description: Returns PI points (tags) on the specified PI Data Archive server with optional name filtering.
tags:
- PIPoints
parameters:
- $ref: '#/components/parameters/WebId'
- name: nameFilter
in: query
description: Wildcard filter for tag names (e.g. *.FLOW)
schema:
type: string
- name: type
in: query
description: Filter by point type
schema:
type: string
enum: [Float16, Float32, Float64, Int16, Int32, Digital, Timestamp, String]
- name: maxCount
in: query
schema:
type: integer
default: 1000
maximum: 10000
- name: startIndex
in: query
schema:
type: integer
default: 0
- name: selectedFields
in: query
schema:
type: string
responses:
'200':
description: PI point list
content:
application/json:
schema:
type: object
properties:
Items:
type: array
items:
$ref: '#/components/schemas/PIPoint'
Links:
$ref: '#/components/schemas/PaginationLinks'
'404':
$ref: '#/components/responses/NotFound'
/points/{webId}:
get:
operationId: getPIPoint
summary: Get a PI point
description: Returns PI point configuration and metadata.
tags:
- PIPoints
parameters:
- $ref: '#/components/parameters/WebId'
- name: selectedFields
in: query
schema:
type: string
responses:
'200':
description: PI point details
content:
application/json:
schema:
$ref: '#/components/schemas/PIPoint'
'404':
$ref: '#/components/responses/NotFound'
/streams/{webId}/value:
get:
operationId: getStreamValue
summary: Get current stream value
description: Returns the current (snapshot) value for a PI point or AF attribute stream.
tags:
- Streams
parameters:
- $ref: '#/components/parameters/WebId'
- name: desiredUnits
in: query
description: Unit of measure for the returned value
schema:
type: string
- name: selectedFields
in: query
schema:
type: string
responses:
'200':
description: Current stream value
content:
application/json:
schema:
$ref: '#/components/schemas/TimedValue'
'404':
$ref: '#/components/responses/NotFound'
/streams/{webId}/recorded:
get:
operationId: getStreamRecorded
summary: Get recorded stream values
description: Returns archive (recorded) values for a PI point or AF attribute within a time range.
tags:
- Streams
parameters:
- $ref: '#/components/parameters/WebId'
- name: startTime
in: query
description: Start time (absolute or relative, e.g. "*-1d" or "2026-03-01T00:00:00Z")
schema:
type: string
default: '*-1d'
- name: endTime
in: query
description: End time
schema:
type: string
default: '*'
- name: boundaryType
in: query
schema:
type: string
enum: [Inside, Outside, Interpolated]
default: Inside
- name: maxCount
in: query
schema:
type: integer
default: 1000
- name: desiredUnits
in: query
schema:
type: string
- name: selectedFields
in: query
schema:
type: string
responses:
'200':
description: Recorded values
content:
application/json:
schema:
type: object
properties:
Items:
type: array
items:
$ref: '#/components/schemas/TimedValue'
Links:
$ref: '#/components/schemas/PaginationLinks'
'404':
$ref: '#/components/responses/NotFound'
/streams/{webId}/interpolated:
get:
operationId: getStreamInterpolated
summary: Get interpolated stream values
description: Returns interpolated values at a fixed time interval within a time range.
tags:
- Streams
parameters:
- $ref: '#/components/parameters/WebId'
- name: startTime
in: query
schema:
type: string
default: '*-1d'
- name: endTime
in: query
schema:
type: string
default: '*'
- name: interval
in: query
description: Interval between values (e.g. "1h", "5m")
schema:
type: string
default: '1h'
- name: desiredUnits
in: query
schema:
type: string
- name: maxCount
in: query
schema:
type: integer
default: 1000
- name: selectedFields
in: query
schema:
type: string
responses:
'200':
description: Interpolated values
content:
application/json:
schema:
type: object
properties:
Items:
type: array
items:
$ref: '#/components/schemas/TimedValue'
/streams/{webId}/summary:
get:
operationId: getStreamSummary
summary: Get stream summary statistics
description: Returns statistical summaries (min, max, average, count, etc.) for a stream over a time range.
tags:
- Streams
parameters:
- $ref: '#/components/parameters/WebId'
- name: startTime
in: query
schema:
type: string
default: '*-1d'
- name: endTime
in: query
schema:
type: string
default: '*'
- name: summaryType
in: query
description: Comma-separated summary types
schema:
type: string
example: Minimum,Maximum,Average,StdDev,Count
- name: calculationBasis
in: query
schema:
type: string
enum: [TimeWeighted, EventWeighted]
default: TimeWeighted
responses:
'200':
description: Summary statistics
content:
application/json:
schema:
type: object
properties:
Items:
type: array
items:
$ref: '#/components/schemas/StreamSummary'
/assetservers:
get:
operationId: listAssetServers
summary: List Asset Framework servers
description: Returns all registered PI Asset Framework (AF) servers.
tags:
- AssetServers
responses:
'200':
description: Asset server list
content:
application/json:
schema:
type: object
properties:
Items:
type: array
items:
$ref: '#/components/schemas/AssetServer'
/assetdatabases/{webId}/elements:
get:
operationId: listElements
summary: List AF elements
description: Returns top-level AF elements in an asset database.
tags:
- Elements
parameters:
- $ref: '#/components/parameters/WebId'
- name: nameFilter
in: query
schema:
type: string
- name: templateName
in: query
schema:
type: string
- name: maxCount
in: query
schema:
type: integer
default: 1000
- name: selectedFields
in: query
schema:
type: string
responses:
'200':
description: Element list
content:
application/json:
schema:
type: object
properties:
Items:
type: array
items:
$ref: '#/components/schemas/Element'
Links:
$ref: '#/components/schemas/PaginationLinks'
/elements/{webId}/attributes:
get:
operationId: listAttributes
summary: List element attributes
description: Returns attributes of an AF element.
tags:
- Attributes
parameters:
- $ref: '#/components/parameters/WebId'
- name: nameFilter
in: query
schema:
type: string
- name: selectedFields
in: query
schema:
type: string
responses:
'200':
description: Attribute list
content:
application/json:
schema:
type: object
properties:
Items:
type: array
items:
$ref: '#/components/schemas/Attribute'
/eventframes:
get:
operationId: listEventFrames
summary: Query event frames
description: Returns event frames matching specified criteria within a time range.
tags:
- EventFrames
parameters:
- name: databaseWebId
in: query
required: true
description: AF database WebId to search
schema:
type: string
- name: startTime
in: query
schema:
type: string
default: '*-7d'
- name: endTime
in: query
schema:
type: string
default: '*'
- name: nameFilter
in: query
schema:
type: string
- name: templateName
in: query
schema:
type: string
- name: maxCount
in: query
schema:
type: integer
default: 1000
- name: selectedFields
in: query
schema:
type: string
responses:
'200':
description: Event frame list
content:
application/json:
schema:
type: object
properties:
Items:
type: array
items:
$ref: '#/components/schemas/EventFrame'
Links:
$ref: '#/components/schemas/PaginationLinks'
/batch:
post:
operationId: executeBatch
summary: Execute a batch request
description: >-
Executes multiple PI Web API requests in a single HTTP call. Supports
sequential and parallel execution with parameter substitution between requests.
tags:
- BatchRequests
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties:
$ref: '#/components/schemas/BatchRequest'
responses:
'207':
description: Batch results (one per request)
content:
application/json:
schema:
type: object
additionalProperties:
$ref: '#/components/schemas/BatchResponse'
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: HTTP Basic Authentication
kerberos:
type: http
scheme: negotiate
description: Kerberos/Windows Integrated Authentication
parameters:
WebId:
name: webId
in: path
required: true
description: PI Web API WebId (unique opaque identifier for PI System objects)
schema:
type: string
responses:
Unauthorized:
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
DataServer:
type: object
properties:
WebId:
type: string
Id:
type: string
format: uuid
Name:
type: string
Path:
type: string
description: PI path (\\ServerName)
IsConnected:
type: boolean
ServerVersion:
type: string
ServerTime:
type: string
format: date-time
Links:
type: object
PIPoint:
type: object
description: A PI point (tag) definition
properties:
WebId:
type: string
Id:
type: integer
Name:
type: string
description: Tag name
Path:
type: string
description: Full PI path (\\Server\TagName)
PointType:
type: string
enum: [Float16, Float32, Float64, Int16, Int32, Digital, Timestamp, String]
EngineeringUnits:
type: string
Description:
type: string
Descriptor:
type: string
PointClass:
type: string
Zero:
type: number
format: double
Span:
type: number
format: double
Step:
type: boolean
description: True if values change as step function
Future:
type: boolean
TimedValue:
type: object
description: A PI time-series value with timestamp
properties:
Timestamp:
type: string
format: date-time
Value:
description: Value; numeric, string, or digital state object
oneOf:
- type: number
- type: string
- type: object
properties:
Name:
type: string
Value:
type: integer
Good:
type: boolean
description: True if value is of good quality
Questionable:
type: boolean
Substituted:
type: boolean
Annotated:
type: boolean
UnitsAbbreviation:
type: string
StreamSummary:
type: object
properties:
Type:
type: string
enum: [Minimum, Maximum, Average, StdDev, Total, Count, Range, PercentGood]
Value:
$ref: '#/components/schemas/TimedValue'
AssetServer:
type: object
properties:
WebId:
type: string
Id:
type: string
format: uuid
Name:
type: string
Path:
type: string
IsConnected:
type: boolean
ServerVersion:
type: string
Element:
type: object
description: A PI AF element
properties:
WebId:
type: string
Id:
type: string
format: uuid
Name:
type: string
Description:
type: string
Path:
type: string
TemplateName:
type: string
HasChildren:
type: boolean
CategoryNames:
type: array
items:
type: string
Attribute:
type: object
description: A PI AF attribute
properties:
WebId:
type: string
Id:
type: string
format: uuid
Name:
type: string
Description:
type: string
Path:
type: string
Type:
type: string
TypeQualifier:
type: string
DataReference:
type: string
description: Data reference plugin type (e.g. PI Point)
ConfigString:
type: string
description: Configuration string for data reference
IsManualDataEntry:
type: boolean
HasChildren:
type: boolean
EngineeringUnits:
type: string
EventFrame:
type: object
description: A PI AF event frame
properties:
WebId:
type: string
Id:
type: string
format: uuid
Name:
type: string
Description:
type: string
TemplateName:
type: string
StartTime:
type: string
format: date-time
EndTime:
type: string
format: date-time
nullable: true
AcknowledgedBy:
type: string
AcknowledgedDate:
type: string
format: date-time
nullable: true
CanBeAcknowledged:
type: boolean
IsAcknowledged:
type: boolean
IsAnnotated:
type: boolean
Severity:
type: string
enum: [None, OK, Information, Warning, Minor, Major, Critical]
BatchRequest:
type: object
properties:
Method:
type: string
enum: [GET, POST, PUT, PATCH, DELETE]
Resource:
type: string
description: Relative URL of the PI Web API resource
ParentIds:
type: array
items:
type: string
description: IDs of batch requests that must complete before this one
Parameters:
type: array
items:
type: string
description: Parameter substitution references (e.g. {0}.Content.WebId)
Headers:
type: object
additionalProperties:
type: string
BatchResponse:
type: object
properties:
Status:
type: integer
Headers:
type: object
additionalProperties:
type: string
Content:
type: object
PaginationLinks:
type: object
properties:
First:
type: string
format: uri
Previous:
type: string
format: uri
nullable: true
Next:
type: string
format: uri
nullable: true
Last:
type: string
format: uri
Error:
type: object
properties:
Errors:
type: array
items:
type: string