Reference Data

Lookup Tables HTTP endpoints — Table CRUD, Column CRUD, Row CRUD, and faceted search. 16 endpoints under `/api/referencedata/`.

The Lookup Tables API surface is exposed under /api/referencedata/ — 16 endpoints across four groups (table CRUD, column CRUD, row CRUD, search). The underlying Spring controller is named ReferenceDataController even though the user-facing concept is "Lookup Tables". Every endpoint requires authentication. The mutating endpoints (table / column / row create, update, delete) additionally require the corresponding LOOKUP_TABLE_* permission documented under Lookup Tables → RBAC permissions — but those permissions are global, not per-table or per-owner scoped, so a holder of (for example) LOOKUP_TABLE_DEFINITION_UPDATE can edit columns on any lookup table. The read and search endpoints require only authentication: there is no LOOKUP_TABLE_*_READ permission, so any authenticated caller can read every lookup table's structure and rows. For the feature description, the creation flow, supported PostgreSQL field types, and direct database access via lookup_tables_schema, see the Lookup Tables page.

Table CRUD (4 endpoints)

Method	Path	Operation ID	Purpose
POST	/api/referencedata/table	createReferenceTable	Create a new lookup table. Body: LookupTableFormData (name, namespace_name, optional description). Requires LOOKUP_TABLE_CREATE. The name is normalised (lowercased, spaces → underscores) to form the physical table name; a name that normalises to one that already exists in the same namespace is rejected with 400 ("already exists in this namespace").
GET	/api/referencedata/table/{lookup_table_id}	getLookupTableById	Get a single lookup table including its column schema.
PUT	/api/referencedata/table/{lookup_table_id}	updateLookupTable	Rename or re-describe a table. Body: LookupTableUpdateFormData (name, optional description). Requires LOOKUP_TABLE_UPDATE.
DELETE	/api/referencedata/table/{lookup_table_id}	deleteLookupTable	Delete a lookup table. Requires LOOKUP_TABLE_DELETE.

Column (definition) CRUD (4 endpoints)

Method	Path	Operation ID	Purpose
POST	/api/referencedata/table/{lookup_table_id}/columns	createColumnsForLookupTable	Add one or more columns. Body: array of LookupTableFieldFormData (name, field_type, optional description, is_nullable, is_unique, default_value). Requires LOOKUP_TABLE_DEFINITION_CREATE.
GET	/api/referencedata/table/{lookup_table_id}/columns/{column_id}	getLookupTableField	Get a single column.
PATCH	/api/referencedata/table/{lookup_table_id}/columns/{column_id}	updateLookupTableField	Edit column metadata. Body: LookupTableFieldUpdateFormData. The {column_id} must belong to the {lookup_table_id} in the path, or the request is rejected with 400 ("doesn't belong to"). Nominally requires LOOKUP_TABLE_DEFINITION_UPDATE, but see the authorization caveat below — the permission gate may not fire. The field_type is not in the update form — types are immutable once set.
DELETE	/api/referencedata/table/{lookup_table_id}/columns/{column_id}	deleteLookupTableField	Delete a column. The {column_id} must belong to the {lookup_table_id} in the path, or the request is rejected with 400. Nominally requires LOOKUP_TABLE_DEFINITION_DELETE — see the authorization caveat below.

The column PATCH and DELETE permission gate may not fire — treat these two endpoints as authentication-only. The authorization rule for column mutation is registered against the singular path .../column/{column_id}, while the live route is the plural .../columns/{column_id}. The matcher does not fire, so the request falls through to the catch-all "any authenticated user" rule. Combined with the global (not per-table) scope of LOOKUP_TABLE_DEFINITION_UPDATE / _DELETE, any authenticated caller can edit or delete lookup-table columns regardless of whether they actually hold the LOOKUP_TABLE_DEFINITION_* permission. If this is a concern, restrict who can reach /api/referencedata/ at the network perimeter (reverse-proxy rules, ingress filtering) until it is corrected upstream.

(The related cross-table defect — passing a mismatched {lookup_table_id} to mutate a column on a different table — was closed in 0.29.0: the PATCH and DELETE column endpoints now validate the column-to-table relationship and reject a mismatch with 400, mirroring the read endpoint.)

Row (data) CRUD (4 endpoints)

Method	Path	Operation ID	Purpose
GET	/api/referencedata/table/{lookup_table_id}/data	getLookupTableRowList	Page through rows. Query params: page, size.
POST	/api/referencedata/table/{lookup_table_id}/data	addDataToLookupTable	Insert one or more rows. Body: array of LookupTableRowFormData. Requires LOOKUP_TABLE_DATA_CREATE.
PATCH	/api/referencedata/table/{lookup_table_id}/data/{row_id}	updateLookupTableRow	Edit an existing row. Requires LOOKUP_TABLE_DATA_UPDATE.
DELETE	/api/referencedata/table/{lookup_table_id}/data/{row_id}	deleteLookupTableRow	Delete a row. Requires LOOKUP_TABLE_DATA_DELETE.

Search (4 endpoints)

The Master Data list uses a faceted-search flow shared with other catalog search surfaces — create a search, then page results.

Method	Path	Operation ID	Purpose
POST	/api/referencedata/search	referenceDataSearch	Create a new search and get back a search_id plus the initial facets. Body: ReferenceDataSearchFormData.
GET	/api/referencedata/search/{search_id}	getReferenceDataSearchFacetList	Re-fetch the facets for an existing search.
PUT	/api/referencedata/search/{search_id}	updateReferenceDataSearchFacetList	Update the search query and re-aggregate facets.
GET	/api/referencedata/search/{search_id}/results	getReferenceDataSearchResults	Page through the matching tables. Query params: page, size.

See also

• API Reference hub — the full per-feature index.

• Lookup Tables — feature description, creation flow, PostgreSQL field types, RBAC, direct database access.