Acuity PPM API

BI endpoints are company-scoped and read-only. They serve cached exports without starting generation. Use your Acuity environment's host.

Authentication

Method	Credentials
Basic	Username `company_api_token`; password is the company API token.
Header	`Company-Api-Token: <company-api-token>`
Query parameter	`company_api_token`, supported for compatibility. Prefer Basic or a header to avoid exposing tokens in URLs.

Precedence is header, query parameter, then Basic. Reporting must be enabled. BI does not use the write API's api-auth, api-token, or api-secret headers.

Endpoints

All endpoints below use GET.

Path	Response
`/api/bi/odata/v1`	OData service root for Power BI Navigator.
`/api/bi/odata/v1/$metadata`	XML keys and typed columns.
`/api/bi/odata/v1/{dataset_key}`	OData JSON rows in `value`.
`/api/bi/v1/manifest`	Dataset schemas, export metadata, and links.
`/api/bi/v1/{dataset_key}`	JSON export with `dataset_key`, `schema_version`, `generated_at`, `row_count`, `columns`, and `rows`. Import `rows`.
`/api/bi/v1/{dataset_key}.csv`	Flat CSV with headers.

OData uses version 4.0 and the same exports as JSON/CSV. Its row envelope is:

{
  "@odata.context": "/api/bi/odata/v1/$metadata#financials",
  "value": []
}

All OData system query options beginning with $ are unsupported, including $filter, $select, $top, $skip, $orderby, $expand, and $count. Import complete tables. Power Query transformations can send these options even when the source URL has none.

CSV uses UTF-8 without BOM, comma separators, RFC 4180 quoting, and CRLF line endings. Missing scalar values are empty cells.

Manifest

The manifest returns api_version, company_id, and datasets. Dataset entries include keys/names, schema_version, formats, columns, published_schema, relative JSON/CSV links, and artifacts metadata.

Check latest_successful_generated_at and row_count. Null means no usable export; zero rows can be valid. A listed dataset is not necessarily generated. Custom-field metadata includes publication time and unresolved pending changes.

Request example

curl prompts for the company token as the password:

curl --user company_api_token \
  'https://<acuity-host>/api/bi/v1/manifest'

For header authentication:

GET /api/bi/odata/v1/financials HTTP/1.1
Host: <acuity-host>
Company-Api-Token: <company-api-token>

Export metadata

Dataset responses include X-Acuity-Dataset-Key, X-Acuity-Schema-Version, X-Acuity-Generated-At, ETag, and Last-Modified, with Cache-Control: private, max-age=0, must-revalidate. OData also returns OData-Version: 4.0.

Compare X-Acuity-Generated-At or manifest artifact generated_at with Power BI refresh history when data looks old. Different datasets can have different timestamps.

If-None-Match or If-Modified-Since can produce HTTP 304 with no body. Keep client caches separate by company and environment.

Errors and fixes

Errors contain error and message, with dataset_key or unsupported_options where applicable.

HTTP / error	Action
401 `unauthorized`	Check company/environment and Basic credentials. Clear stale Desktop source permissions or update Service credentials.
403 `bi_reporting_disabled`	Enable reporting or ask Support to check company eligibility.
404 `unknown_dataset`	Use a key listed in your service root or manifest.
404 `not_generated`	Wait for a successful export. Contact Support if preparation fails or stalls.
400 `query_string_token_rejected`	Remove `Company-Api-Token` from the URL. Use Basic or the header; the supported query parameter is `company_api_token`.
400 `unsupported_odata_query_options`	Remove the listed `$` options. If a transformation triggers the error, return to a plain import and keep filtering local or in the report/model.
422 `invalid_cached_artifact`	Contact Support with the dataset key and request time.
Desktop works, Service fails	Check gateway, source mapping, credentials, and refresh history. Resolve the error and re-enable a disabled schedule.

For Support, include environment/company, dataset key, status/error, export timestamp, and Power BI refresh time. Remove tokens and Authorization headers from logs, URLs, and screenshots.