Developer guide

OData & analytics

Explore Workroomly’s read-only OData v4 service, authorized datasets and Power BI connection setup.

On this page

What OData gives you
Authenticate and discover
Query your data
Pagination and query limits
Connect Power BI Desktop
Available datasets
Troubleshoot a connection

What OData gives you

OData exposes business data as discoverable entity sets with a common query syntax. Use it for reporting, scheduled exports and analytics without writing a separate REST integration for each dataset.

Workroomly implements a read-only OData v4 subset at https://api.workroomly.com/odata/. Use the endpoint shown in Settings → Developers → Data Access if your application uses a different environment. Data Access keys determine the workroom, modules and permitted subspaces.

Authenticate and discover

Create a Data Access key with explicit modules and, for CRM/Board/Desk, selected subspaces. Integration keys and MCP OAuth tokens do not authenticate this service. Never send your Workroomly login password.

Use Bearer authentication in code. In a client’s Basic authentication dialog, use Workroomly as the username and the full Data Access key as the password. Use HTTPS.

# Discover only the datasets permitted by this key.
curl --fail-with-body --silent --show-error \
  'https://api.workroomly.com/odata/' \
  -H "Authorization: Bearer $WORKROOMLY_API_KEY"

# Discover field names, EDM types and nullability.
curl --fail-with-body --silent --show-error \
  'https://api.workroomly.com/odata/$metadata' \
  -H "Authorization: Bearer $WORKROOMLY_API_KEY"

The service root returns an @odata.context URL and a value array of entity-set names and URLs. The metadata document is XML. Both are filtered by your key’s module permissions. Data rows remain restricted to its authorized subspaces and the dataset’s visibility rules.

Query your data

This example selects a few CRM contact columns, filters by modification date, sorts deterministically and requests at most 50 rows. The single-quoted query arguments keep Bash from expanding the dollar signs.

curl --fail-with-body --silent --show-error --get \
  'https://api.workroomly.com/odata/crm_contacts' \
  -H "Authorization: Bearer $WORKROOMLY_API_KEY" \
  --data-urlencode '$select=id,name,email,updated_at' \
  --data-urlencode '$filter=updated_at ge 2026-01-01T00:00:00Z' \
  --data-urlencode '$orderby=updated_at asc,id asc' \
  --data-urlencode '$top=50' \
  --data-urlencode '$count=true'

Query option	Supported behavior
$select	Choose exposed columns; * selects all exposed columns.
$filter	Field comparisons eq/ne/gt/ge/lt/le where the field supports them; and/or/not, parentheses and supported string functions.
$orderby	Allowed fields with asc or desc; id is added as a tie-breaker.
$top	Non-negative total row cap; 0 returns an empty collection.
$skip	Non-negative direct offset, capped at 10,000. Prefer continuation links.
$count=true	Include @odata.count. Counting is skipped unless requested.
$format	JSON only; supports IEEE754Compatible for exact numeric strings.
$skiptoken	Server-issued continuation token. Follow nextLink instead of constructing it.

String filters can use contains, startswith and endswith on supported string fields. Escape an apostrophe by doubling it inside an OData string literal. Unsupported expressions fail instead of being silently ignored.

Single-record URLs use /odata/crm_contacts(<record-UUID>) with optional $select/$format. /odata/crm_contacts/$count returns a plain-text count and supports only $filter/$format.

Protocol limits: $expand, $batch, $search, $apply, $delta, navigation properties, arithmetic and lambda expressions are not implemented. Relationships are exposed as selected scalar IDs/labels; join them in your reporting model. POST/PUT/PATCH/DELETE return a read-only error.

Pagination and query limits

Collections return value and may include @odata.nextLink. Follow that URL unchanged with the same credential until no nextLink remains. It binds the query, key, permissions and position; editing query options, changing keys or altering scopes invalidates the continuation. Tokens expire after 24 hours, so restart the query if one expires.

The default page size is 100, constrained by the deployment’s read limit. The default workroom concurrency limit is four requests and the PostgreSQL statement timeout is 15 seconds. Deployments can tune these values. Filters are limited to 2,048 characters and bounded expression depth. Use narrower fields/filters and avoid parallel full-dataset scans.

Continuation uses a timestamp cutoff and stable ordering; it is not a durable historical snapshot. Rows modified or removed while an export runs may be omitted. Reconcile mutable data on later refreshes.

A collection’s count appears only when requested. For large integer/decimal values, request Accept: application/json;IEEE754Compatible=true to receive exact numeric strings and avoid JavaScript precision loss. Successful response bytes consume the shared workroom Data Transfer allowance; failed requests and HEAD responses do not consume response-byte allowance.

Connect Power BI Desktop

Use the OData Feed connector in Power BI Desktop with OData v4 and your Data Access key.

Copy the OData endpoint from Settings → Developers → Data Access. Create a dedicated Data Access key for reporting.
In Power BI Desktop, choose Get data → OData feed and enter the service root, including its trailing slash.
Choose Basic authentication. Enter Workroomly as the username and the Data Access key as the password. Apply it to that service root.
In Navigator, select an authorized dataset. Choose Transform Data to filter/select columns, or Load.
Refresh and confirm that the expected workroom records appear. An empty table may reflect the key’s scopes or dataset visibility rules.

Microsoft documents the connector flow in OData Feed. To replace a rotated key, use File → Options and settings → Data source settings → Edit Permissions → Credentials → Edit, then refresh. See desktop authentication settings.

For published reports, configure Power BI service credentials and scheduled refresh separately. Follow Microsoft’s gateway requirements for Basic authentication in online connections, then run a refresh to confirm your report can retrieve data. Keep the key in the connector’s credential store, outside M query source.

Available datasets

Browse 32 datasets for your reporting workflows. Your service root lists the datasets available to your key. Expand a dataset for its columns. Files expose shared metadata; Goals expose workroom-visible trees; Pages expose public metadata without submitted form values.

Find a dataset

32 results

assets_assetsAsset

Permission: assets.* · REST resource: assets.asset

Selectable columns

idasset_numbernamecategory_namelifecycle_stateoperational_statecustody_statefinancial_stateconditionmanufacturermodel_nameserial_numberacquisition_methodacquisition_dateacquisition_costincidental_costcurrencyvendor_namepurchase_order_reflocation_namedepartmentsource_typecreated_atupdated_at