canonical: https://jentic.com/apis/osisoft.com/osisoft-main

# Osisoft PI Web API 2018 SP1 Swagger Spec

PI Web API exposes the OSIsoft (now AVEVA) PI System over REST, giving programmatic access to the historian, asset framework, analyses, event frames, batch records, and notifications stored across an industrial deployment. With 413 endpoints, it covers reading and writing time-series tags, navigating asset hierarchies, running search across element templates, and configuring security on every PI object. Operators in manufacturing, energy, and utilities use PI Web API to push real-time sensor data into analytics, MES, and digital twin pipelines.

## For AI agents

Read and write industrial time-series data, navigate asset frameworks, and run analyses on the OSIsoft PI System. Agents can pull tag values, query event frames, and stream sensor history through REST.

## Scope

Does not handle ERP transactions, MES scheduling, or document management - use for PI System time-series, asset framework, and event frame access only.

## Capabilities

- Retrieve current and historical values for PI tags and AF attributes by Web ID
- Search the PI Asset Framework for elements matching templates, attributes, or text
- Run interpolated, recorded, and summary calculations against time-series data
- List, acknowledge, and write event frames triggered by PI Notifications
- Manage analyses: list backing calculations, evaluate them on demand, and read results
- Inspect security on every PI object via /security and /securityIdentities endpoints

## Use cases

### Industrial Time-Series Pull for Analytics

Operations teams pull PI sensor history into cloud analytics, machine-learning pipelines, and reliability tools. `/streams/{webId}/recorded` returns archived values between two timestamps, while `/streams/{webId}/interpolated` produces evenly spaced values for downstream models. A typical export of a few hundred tags into a data lake takes under a day to wire up against PI Web API.

Example prompt: Get the recorded values for tag with Web ID 'F1...' between '2026-06-01T00:00:00Z' and '2026-06-02T00:00:00Z' by calling GET `/streams/{webId}/recorded` with the appropriate startTime and endTime.

### Asset Framework Discovery

Reliability engineers search the PI Asset Framework to find assets matching a template (for example all centrifugal pumps with vibration sensors). `/elements/search` and /elementtemplates support text, template, and attribute filters; the result includes Web IDs to drive subsequent value reads. This pattern replaces brittle naming conventions with structured queries grounded in the AF model.

Example prompt: Search the Asset Framework for elements derived from the 'CentrifugalPump' template by calling GET `/elements/search` with templateName='CentrifugalPump' and return the Web IDs.

### Event Frame and Notification Audit

Process engineers audit equipment events using PI Notifications and event frames. /eventframes lets the agent list events filtered by start time, severity, and category; `/eventframes/{webId}` returns full context including triggering attributes and acknowledgement state. This becomes the audit trail when investigating excursions, downtime, or batch deviations.

Example prompt: List event frames started after '2026-06-10T00:00:00Z' by calling GET /eventframes with startTime parameter set, then fetch each by Web ID for full context.

### AI Agent for Industrial Operations via Jentic

Plant-floor AI agents that monitor and recommend actions need scoped access to PI Web API operations. Through Jentic, an agent searches for 'get current value of a PI tag', loads the matching schema, and executes the call without holding a long-lived PI Web API credential. This keeps OT credentials inside your Jentic One instance and lets the agent cleanly compose value reads with downstream analytics.

Example prompt: Use Jentic to search 'get the current value of a PI tag', load the GET `/streams/{webId}/value` schema, and execute it for the tag identified earlier in the conversation.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/` | Root entry point with links to system endpoints |
| GET | `/analyses` | List analyses configured in PI AF |
| GET | `/analyses/search` | Search analyses by name, template, or owner |
| GET | `/analyses/{webId}` | Get a single analysis by Web ID |
| PATCH | `/analyses/{webId}` | Update an analysis configuration |
| DELETE | `/analyses/{webId}` | Delete an analysis |
| GET | `/analyses/{webId}/categories` | List categories assigned to an analysis |
| GET | `/analyses/{webId}/security` | Read security on an analysis |

## Key resources

- **Streams** — Time-series read and write operations for tags and AF attributes
- **Elements** — PI Asset Framework elements representing physical and logical assets
- **Element Templates** — Templates defining attribute structure for AF elements
- **Event Frames** — Discrete events triggered by PI Notifications, with start, end, and context
- **Analyses** — Calculations defined in PI AF and evaluated against time-series data
- **Security** — Security identities, mappings, and ACLs across PI objects

## Why Jentic

- **Setup:** The PI Web API can be reached without credentials on some deployments, but wiring it by hand still means handling whatever Kerberos, basic, or bearer auth your PI System uses and mapping the stream, element, and analysis routes yourself. Through Jentic you install once, import the PI Web API from the API Directory, store any credential once, and your agent calls it.
- **Permission scoping:** PI Web API puts the object WebId in the URL path (`/analyses/{webId}`), so a rule can pin your agent to reading a specific object and its categories or security. You choose the operations it may call, so destructive operations like deleting or patching an analysis stay out of the allowed set unless you add them.
- **Credential handling:** Any PI Web API credential your deployment uses, whether a Kerberos ticket, basic, or bearer token, is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get the current value of a PI tag' or 'search for an analysis', and Jentic returns the matching PI Web API operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **PI Web API 2018 SP1 Swagger Spec** — The same PI Web API surface published under a separate api-slug; either spec can drive the integration.
- **New Relic API** — New Relic ingests metrics from IT systems while PI Web API holds metrics from OT systems; combining them gives a unified plant view.
- **Sentry API** — Sentry tracks errors in software that orchestrates PI data, while PI Web API exposes the data itself.

## FAQ

### What authentication does the PI Web API use?

PI Web API supports Kerberos, NTLM, Basic, and Bearer authentication depending on the deployment configuration; the public Swagger spec does not declare a security scheme, but production deployments invariably require credentials. Through Jentic, the configured credential is stored encrypted in the vault and injected at call time so the secret never enters the agent's context.

### Can I read historical PI tag values through the API?

Yes. GET `/streams/{webId}/recorded` returns archived values between two timestamps, GET `/streams/{webId}/interpolated` returns values at evenly spaced intervals, and GET `/streams/{webId}/summary` returns aggregates like average, minimum, and maximum over a window. You first resolve the Web ID for the tag using `/points/search` or `/elements/search.`

### What are the rate limits for the PI Web API?

The PI Web API does not apply hard rate limits in its spec; throughput is bounded by the configured PI Web API server, the underlying PI Data Archive, and any reverse proxy. For bulk historical reads use /streamsets endpoints to batch many Web IDs in a single request rather than hammering /streams individually.

### How do I search the Asset Framework through Jentic?

Through Jentic, search for 'find PI assets', load the GET `/elements/search` schema, and execute it with templateName, query, or attributeName parameters. Jentic injects the configured credential and returns matching elements with their Web IDs for downstream value reads.

### Does PI Web API support writing values back to PI?

Yes. POST `/streams/{webId}/value` writes a single value and POST `/streams/{webId}/recorded` posts an array of timestamped values. Write access depends on the security identities mapped to the PI account; use /security endpoints to inspect ACLs before attempting writes.

### Is the PI Web API free to use?

PI Web API ships as part of a licensed PI System deployment from AVEVA (formerly OSIsoft) and is included with PI Server licences. There are no per-call charges; cost is the underlying PI System licence and infrastructure.

### Can I limit what my agent is allowed to do with the PI Web API?

Yes. Jentic One runs self-hosted, so your own rules decide which PI Web API operations and credentials the agent may use. Because the API puts the object WebId in the URL path, such as `/analyses/{webId}` or `/streams/{webId}/recorded`, you can pin the agent to reading a specific object and its categories or security. You choose the operations it may call, so destructive routes like DELETE `/analyses/{webId}` or PATCH `/analyses/{webId}` stay out of the allowed set unless you add them.