API Versions and Compatibility

Understand PBRS API version labels, check compatibility with your installed build, and verify integrations before upgrading.

Compatibility depends on the PBRS installation, the operation being called, its request and response formats, and the reporting workflow being executed.

Understand the version labels

The OpenAPI specification accompanying these guides identifies itself as 4.5.20260805.

Record your actual installed PBRS build separately. A specification's version label does not establish that every earlier or later PBRS build implements the same behavior.

API URLs do not contain a version segment

Build the base address from the configured protocol, hostname, and port:

{scheme}://{host}:{port}

Append the complete endpoint path:

Do not add /v1 to these paths.

Keep /api out of the base address because the client-credentials token endpoint does not use that prefix.

Record your integration baseline

Before changing PBRS or your application, record the configuration that currently works.

Use exact build numbers in your records. Labels such as “latest” do not identify a reproducible configuration.

For collaboration and failover, record the build and configuration of every participating server. Do not assume a mixed-build deployment is compatible without checking the applicable release guidance.

Check compatibility by operation

A successful Ping establishes connectivity, not compatibility with every operation your integration uses.

Review each operation for:

• HTTP method and endpoint path.
• Authentication requirements.
• Required headers and content type.
• Parameter location: path, query, or body.
• Field names, casing, and data types.
• Required and conditional fields.
• Empty, omitted, and null-value behavior.
• Response status, body shape, and field types.
• Side effects, execution identifiers, and retry behavior.

Use the request schema for the specific operation. Similar names do not make two operations interchangeable.

Review authentication behavior

The documented authentication routes are:

Access tokens expire after 60 minutes.

Protected requests require the token in the Authorization header with the Bearer prefix. Ping does not require a token. Incorrect credentials return HTTP 401.

Do not retain an older 24-hour token assumption or insert /api before /oauth2/token.

After an upgrade, test the authentication method your application actually uses, including obtaining a replacement token and continuing protected requests.

See Authentication and Token Management for request examples.

Preserve operation-specific request formats

Property names and casing

Use the exact names shown in the target request schema.

For example:

• Schedule authoring and execution requests use uniqueid where specified.
• Some lookup operations use Id or id in query parameters.
• Status and cancellation requests use ExecutionId.
• Process termination uses ProcessId.

Do not globally rename every identifier to one spelling.

JSON and form encoding

Use the content types documented for the operation.

JSON is suitable for nested objects, arrays, and explicit null values. For form-encoded requests, follow the operation's field naming and serialization rules.

These values are not interchangeable:

• An omitted property.
• An empty string.
• JSON null.
• An empty array.
• An empty object.

Verify serialization after changing an HTTP client or regenerating an SDK.

GET requests with bodies

Some PBRS GET operations require a request body.

For example, package keyword search uses:

GET /api/PackageSchedule/GetAll

with an explicit search body.

Some API explorers and generated clients cannot send GET bodies correctly. A missing request body can change the result even when the method and URL are correct.

Use the documented cURL example or a client that supports the required request. Use a POST alternative only where the endpoint reference explicitly provides one.

SingleSchedule/GetAll has a documented POST alternative. Do not assume every GET operation does.

Distinguish authoring, read, and import models

PBRS uses different representations for creating schedules, reading schedules, and importing exported definitions.

A read response is not necessarily a lossless update request or a complete export.

A field returned by a read operation is not automatically writable.

Import field names can legitimately differ from authoring names. Do not apply authoring-field corrections to an exported definition without checking the import schema.

Package authoring field names

Use the following names in package create/update requests:

DataDriver.ValuesJson contains serialized JSON in a string, not a directly nested array.

MultiThreaded and ThreadCount are not supported writable package authoring inputs.

These distinctions identify the current request format. They do not establish that alternative names were supported aliases or were removed in a particular release.

For import, fields such as PackageAttr.PackageName and PackageAttr.IsDataDriven belong to the separate exported-attribute schema. Preserve them when required by a compatible export.

See Create and Manage Report Packages and Import and Migrate Schedule Definitions for the corresponding workflows.

Verify response handling

Do not use one parser for every successful response.

Check HTTP status and content before parsing. An empty successful response is not malformed JSON.

For execution status, parse ResultJson separately when populated. Completed can contain Result: false.

For import, do not assume returnModel always contains nested JSON.

Handle additional response values

Retain unfamiliar status strings and additional response fields for investigation.

Do not automatically classify an unfamiliar execution state as success or failure. Continue appropriate monitoring or reconciliation.

Flexible response handling should not hide missing required values, unexpected types, or failed results.

Verify update and execution semantics

Compatibility includes behavior, not only matching JSON fields.

Complete updates

Where an operation requires a complete update:

• Preserve required report configuration.
• Include all destinations that should remain.
• Preserve destination identifiers.
• Include intended filters and parameters.
• Preserve recurrence and enabled state.

For applicable schedule updates, omitted destinations are removed. Empty filter collections can remove existing filters.

Do not assume that an update endpoint behaves like a partial patch.

Execution modes

Keep ExecutionId, ProcessId, and schedule identifiers separate.

Do not substitute one execution mode for another solely because their request bodies look similar. For example, ExecuteScheduleOnTimeAsync affects NextRun.

After any upgrade, verify both the reported execution result and the generated output.

Limits and retries

PBRS does not throttle API requests, but that does not mean unlimited execution capacity or freedom from reporting-service limits.

Review your polling intervals, request timeouts, execution deadlines, and concurrency controls.

Do not assume submissions are idempotent. Reconcile uncertain creation, import, clone, update, or execution outcomes before repeating them.

Prepare for a PBRS upgrade

Review the PBRS release announcements and follow the PBRS software update procedure.

Before upgrading:

1. Record the current PBRS build and integration baseline.
2. Review release information for the target build.
3. Back up the PBRS configuration and retain the required recovery materials.
4. Preserve your application configuration and API specification.
5. Coordinate scheduled work, external API submissions, and active executions.
6. Arrange the required maintenance window and server restart.
7. Prepare representative tests using controlled destinations.
8. Confirm the recovery procedure for the installation and its dependencies.

Use an appropriate test environment before changing production.

Do not assume that reinstalling an older executable reverses database or configuration changes. Plan recovery using compatible backups and the applicable support guidance.

Test after upgrading

Run the checks relevant to your integration:

Test only against controlled schedules and destinations when an operation can create, modify, execute, or delete data.

Start and stop controls, cancellation, termination, and cloning can change state even when they use GET. Keep them out of generic connectivity tests.

Record the upgraded build and results before resuming normal submissions and scheduled delivery.

Compare specification changes

Before replacing your application's OpenAPI file or regenerating an SDK, compare it with the version used for your current integration.

Review:

• Added or removed operations.
• HTTP method and path changes.
• Required fields and parameter locations.
• Request and response types.
• Enum values and open-string statuses.
• Nullability and empty-response handling.
• Request-body serialization.
• Error and execution-result behavior.

A documentation correction does not necessarily mean the server changed. Compare the corrected request with the behavior of your installed build.

Regenerating an SDK does not upgrade PBRS. Upgrading PBRS does not automatically update your application's generated client.

Keep the specification, generated client, application release, and verification results associated in your deployment records.

Investigate a compatibility problem

When a previously working integration fails:

1. Confirm the PBRS server and installed build.
2. Compare the actual HTTP request with the endpoint reference.
3. Check method, path, headers, body, and serialization.
4. Inspect the raw response before applying application-specific parsing.
5. Reproduce the request with the documented client example where appropriate.
6. Check reporting accounts, permissions, network access, and external dependencies.
7. Reconcile any state-changing request before retrying.

For a support request, include:

• PBRS version and build.
• API operation and HTTP method.
• A sanitized request.
• HTTP status and sanitized response.
• Relevant execution or schedule identifiers.
• When the behavior began.
• The previously working build or application version.
• Whether the problem occurs with a direct request or only through a generated client.

Do not include access tokens, passwords, client secrets, or sensitive report data.

Next steps

Use Troubleshoot API Integrations to investigate request and configuration failures.

Use Monitor, Recover, and Reconcile Executions when an execution outcome is uncertain.

Use Import and Migrate Schedule Definitions when moving schedules between installations.