# Reference Data

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". All endpoints require authentication and respect the per-table RBAC permissions documented under [Lookup Tables → RBAC permissions](/features/master-data-management/lookup-tables.md#rbac-permissions). For the feature description, the creation flow, supported PostgreSQL field types, and direct database access via `lookup_tables_schema`, see the [Lookup Tables](/features/master-data-management/lookup-tables.md) 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`. |
| `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`. Requires `LOOKUP_TABLE_DEFINITION_UPDATE`. 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. Requires `LOOKUP_TABLE_DEFINITION_DELETE`.                                                                                                                                                |

## 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](/developer-guides/api-reference.md) — the full per-feature index.
* [Lookup Tables](/features/master-data-management/lookup-tables.md) — feature description, creation flow, PostgreSQL field types, RBAC, direct database access.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.opendatadiscovery.org/developer-guides/api-reference/reference-data.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.