OData API

Base URL: https://odata.opteryx.app

Overview

OData service discovery, metadata, and dataset query endpoints for compatible clients and BI tools.

Endpoints

OData v4 Service Document

Request: get/api/v4/

Tags: OData v4

Returns the OData v4 service document listing all accessible EntitySets grouped by workspace and collection.

Header Parameters

• authorization string | null [header; optional]

Responses

• 200 — Service document with EntitySet list and access metadata (application/json object)
• 401 — Missing or invalid authentication
• 406 — Accept header does not admit application/json, the only format this route returns
• 422 — Validation Error (application/json HTTPValidationError)

Try it live

OData v4 Service-wide EDMX Metadata

Request: get/api/v4/$metadata

Tags: OData v4

Returns the complete OData v4 EDMX metadata document describing all EntityTypes and EntitySets accessible to the authenticated user.

Header Parameters

• authorization string | null [header; optional]

Responses

• 200 — EDMX metadata document (XML) (application/json object)
• 401 — Missing or invalid authentication
• 406 — Accept header does not admit application/xml, the only format this route returns
• 504 — Firestore unavailable; cannot enumerate datasets
• 422 — Validation Error (application/json HTTPValidationError)

Try it live

Query dataset rows

Request: get/api/v4/{workstream}/{collection}/{dataset}

Tags: OData v4

Retrieve data from a dataset with OData v4 query parameters ($filter, $select, $orderby, $top, $skip, $apply, $compute, $count). Returns paginated results with total count and nextLink for server-driven paging. The dataset segment may carry a @{label} version selector: dataset@current (the default, also what a bare dataset means), dataset@previous (the most recent version of the data before this one — maintenance snapshots such as compaction that changed no rows are skipped), dataset@{tag} (a named snapshot), or dataset@{snapshot_id} (a specific snapshot id). @current and @previous are resolved fresh on every page, so paging through them is not snapshot-isolated against concurrent writes; @{tag} and @{snapshot_id} are immutable and page consistently.

Path Parameters

• workstream string [path; required]
• collection string [path; required]
• dataset string [path; required]

Query Parameters

• $filter string | null [query; optional] Row filter, e.g. vendor eq 'Oracle' and price gt 100. Comparison (eq, ne, lt, le, gt, ge), logical (and, or, not) and string (contains, startswith, endswith) operators, plus cast(), date functions, now() with durations for rolling windows, and the Opteryx extension in_subnet(src_addr, '192.168.4.0/24') for IPv4 columns. Case-sensitive; date literals are unquoted (shipped_date gt 2024-01-01). See Querying via OData for the full syntax.
• $top integer | null [query; optional] Limit result rows (0-100000, default 100). Value 0 with $count=true returns count only. Returns @odata.nextLink if result is truncated.
• $skip integer | null [query; optional] Skip N rows for pagination (server-driven). Requires $orderby: without a deterministic row order, paging duplicates some rows and drops others. Example: &$orderby=id asc&$skip=100 to fetch rows 101+. Combine with $top for paging.
• $orderby string | null [query; optional] Sort by column(s): 'col1 asc, col2 desc'. Default ascending. Example: &$orderby=created_date desc
• $count string | null [query; optional] Include total row count in response: 'true' or 'false' (default false). Use with $top=0 to get count only.
• $select string | null [query; optional] Select specific columns: 'col1,col2,col3' or '*' for all (default all). Reduces payload size.
• $search string | null [query; optional] Full-text search (not implemented; returns 501)
• $compute string | null [query; optional] Computed columns, as comma-separated <expression> as <name> clauses, e.g. price mul quantity as TotalValue. Expressions use the same operators and functions as $filter, and the new name can be used in $select, $orderby and $filter on the same request. Can't be combined with $apply.
• $apply string | null [query; optional] Server-side aggregation, e.g. groupby((vendor), aggregate(amount with sum as Total, $count as Count)). Aggregates are $count as Alias or col with <method> as Alias, where <method> is sum, average, min or max. Chain steps with /, e.g. filter(price gt 1)/groupby((vendor), aggregate($count as N)). See Aggregating with $apply.

Header Parameters

• authorization string | null [header; optional]

Responses

• 200 — Query succeeded; returns rows and pagination metadata (application/json object)
• 400 — Invalid query: malformed $filter, unsupported $top value (not 0-100000), negative $skip, $skip without $orderby, invalid $count value, invalid $apply expression, invalid $compute expression, $compute combined with $apply, OData-MaxVersion below 4.0, or a malformed @{label} version selector
• 401 — Missing or invalid authentication (no bearer token or basic auth)
• 403 — Forbidden: authenticated but no permission for dataset
• 404 — Dataset not found, or the @{label} version selector names a tag/snapshot/previous version that does not exist
• 406 — Accept header does not admit application/json, the only format this route returns
• 501 — Unsupported query feature: $search or $expand not implemented
• 422 — Validation Error (application/json HTTPValidationError)

Try it live

Per-dataset OData EDMX metadata

Request: get/api/v4/{workstream}/{collection}/{dataset}/$metadata

Tags: OData v4

Returns the OData $metadata (EDMX) document for one dataset: column types and nullability, plus the Custom.* annotations below. An annotation is left out where it doesn't apply to the dataset's kind or isn't available.

Source and consumer lists name every dataset, including ones you can't read; Visible says which you can.

Add a @{label} version selector (dataset@previous, dataset@{tag}, dataset@{snapshot_id}) to describe another version. Custom.Snapshot.* and Custom.ReadSources.* follow the label; Custom.Tags and Custom.Sources always describe the dataset as it is now.

Path Parameters

• workstream string [path; required]
• collection string [path; required]
• dataset string [path; required]

Header Parameters

• authorization string | null [header; optional]

Responses

• 200 — EDMX metadata document returned as XML (application/json object)
• 400 — Malformed @{label} version selector, or the dataset kind does not support snapshot versioning
• 401 — Missing or invalid authentication
• 403 — Forbidden: no permission to view dataset metadata
• 404 — Dataset not found in catalog, or the @{label} version selector names a tag/snapshot/previous version that does not exist
• 406 — Accept header does not admit application/xml, the only format this route returns
• 422 — Validation Error (application/json HTTPValidationError)

Try it live