Message header keywords
- Last UpdatedSep 04, 2025
- 2 minute read
The OMF specification defines a message as two parts: the headers, and the body. The headers describe how the body of the message should be interpreted. The PI Web API communicates using HTTPS, and treats the HTTP request headers as the OMF message headers. Each version of the OMF specification can add, remove, or update what message headers are allowed.
The following table shows headers that apply to all versions of OMF.
|
Header |
Defined by OMF specification |
Required |
Details |
|---|---|---|---|
|
omfversion |
Yes |
Required |
Specifies the version of the Open Message Format specification to use when processing the request. The PI Web API supports versions 1.0, 1.1, and 1.2. |
|
Authorization |
No |
Varies |
Before executing a request, the PI Web API checks whether the user making the request can be authenticated - and, if so, enforces the PI System security model when they interact with a resource. The PI Web API supports various authentication methods, including Anonymous, Basic, and Kerberos. The allowed authentication methods are controlled by the PI Web API's AuthenticationMethods configuration item. For maximum compatibility, applications should be prepared to encounter Basic authentication challenges. If specified, the value for this header must be valid according to the allowed authentication methods. The allowed authentication methods are returned by the PI Web API by the WWW-Authenticate response header. |
|
Content-Type |
No |
Optional |
The way HTTP request content is processed can vary depending on the version of OMF that was specified. However, for maximum compatibility with existing HTTP infrastructure (for example, load balancers, proxies, and so on), requests should also specify a content type when possible. This can help avoid requests being incorrectly manipulated before they reach the PI Web API. If specified, the value for this header must be a valid MIME type. For example, if the HTTP request content is serialized as JSON, a value like application/json; charset=utf-8 would be appropriate. |
|
X-Requested-With |
No |
Optional |
When the PI Web API Cross-Site Request Forgery (CSRF) defense setting is enabled, this header must be included. The CSRF defense setting is controlled by the PI Web API's EnableCSRFDefense configuration item. Although this defense can be disabled, applications should assume it is enabled to ensure compatibility. The value for this header can be any non-empty string. A common value used by web applications is XMLHttpRequest. |
The following headers apply to version 1.2 of the OMF specification.
|
Header |
Required |
Details |
|---|---|---|
|
messagetype |
Required |
Specifies the resource type described by the message body. Allowed values are:
|
|
action |
Optional |
Specifies the action to be performed using the data in the request body. The PI Web API supports the create, update, and delete actions. If not specified, the default action is create. |
|
messageformat |
Optional |
Specifies the serialization format of the message body. The only value defined by the specification is json. If omitted, the default value is json. |
|
compression |
Optional |
The compression algorithm used to compress the message body. The only value defined by the specification is gzip. If this header is not included, the PI Web API assumes the message is not compressed. |