API Access

Prerequisites

Before you begin, make sure you have the following:

• A BusinessOptix user account with access to the target library.
• A bearer token provisioned by an administrator for that library. See Provisioning API Bearer Tokens for the step-by-step process.
• The hostname and library name for your environment (your administrator can confirm these if you're unsure).

Authentication

The BusinessOptix API uses bearer token authentication. Every request must include an Authorization header containing your token:

Authorization: Bearer <your-token>

A few important things to know about bearer tokens:

• Each token is tied to a specific user account and carries that user's permissions — the API can only do what that user is authorised to do.
• Tokens are library-specific. If you need to access multiple libraries, even on the same server, you will need a separate token for each one.
• Tokens have an expiry date. If your requests start returning authentication errors, check with your administrator whether your token needs to be renewed.

For full details on how tokens are created and managed, see Provisioning API Bearer Tokens.

API Base URL

Each library has its own API endpoint. The URL follows this pattern:

https://<hostname>/<libraryname>/Library/OpenAPI/

For example, if your hostname is dev.businessoptix.com and your library is called ProductBacklog, the base URL would be:

https://dev.businessoptix.com/ProductBacklog/Library/OpenAPI/

OpenAPI / Swagger Definition

The API is described using the OpenAPI (formerly Swagger) specification. You can retrieve the definition from your library's OpenAPI endpoint. This gives you a complete, machine-readable description of all available endpoints, request parameters, and response schemas.

The OpenAPI definition is dynamic — it reflects the current configuration of your library. This means:

• If your library has data sources configured, the API will include endpoints for interacting with them.
• If your library has importers, the API will include endpoints for triggering and managing imports.
• If your library uses forms, the API will include endpoints for working with those forms.

As your library configuration evolves, the API definition updates to match, so it always represents the operations that are actually available to you.

You can use this definition with tools like Postman or Insomnia, or any OpenAPI-compatible client to explore and test the API.

Swagger UI

BusinessOptix also supports the Swagger UI, which provides a browser-based interface for exploring and testing the API directly — no additional tooling required. The Swagger UI is available at:

https://<hostname>/<libraryname>/Library/Shared/OpenAPI/index.html

Swagger UI is not installed by default. Contact Customer Support to have it enabled for your library.

Making Your First API Call

Once you have your bearer token and know your base URL, you're ready to make a call. A typical request looks like this:

A GET request to your library's OpenAPI endpoint, with the Authorization header set to Bearer <your-token>. A successful response will return the OpenAPI specification as JSON, confirming that your token and URL are both correct.

If you're using the Swagger UI, you can enter your bearer token in the "Authorize" dialog and then interact with the API directly through the browser.

Troubleshooting

• 401 Unauthorized — Your token may be expired, revoked, or incorrect. Check with your administrator.
• 404 Not Found — Double-check your hostname and library name. Remember that both are case-sensitive.
• 403 Forbidden — Your token is valid, but the associated user account doesn't have permission for the operation you're attempting.