On this page

A table stores records described by a dataset. Table creation and lifecycle operations require ADMIN; the administrative table screens also require ADMIN. All built-in roles can read permitted table definitions and records through the API within their data grants.

Create a table

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Authorization: Bearer ${GOLDEN_ADMIN_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "table": "customers",
    "description": "Customer master data",
    "dataset": "customer_dataset",
    "history": true,
    "auditable": true
  }' \
  "${GOLDEN_URL}/api/tables"
PropertyDefaultPurpose
tableRequiredStable table identifier
descriptionEmptyHuman-readable purpose
datasetRequiredExisting dataset resource
historyfalseKeep history records for supported changes
auditablefalseRecord per-record change information

The request property is auditable, not audit. Locking is an entity state, not a table-create property.

History and audit are different

History provides a companion record collection for supported superseded or removed record states. Auditing records who and when for supported record changes. Enable each according to the data-retention and traceability policy; neither reconstructs changes that occurred before it was enabled.

Query current and history records with the same record endpoints by selecting type=TABLE or type=HISTORY. History is versioned: deleting, merging and undoing add versions, and only a table clear removes them. A history read lists identities that are no longer live at their latest version.

Auditing on an existing table can be enabled or disabled through the audit controls procedure. Disabling keeps retained events but does not capture changes made during the gap.

Change table metadata

curl -sS -X PUT "$GOLDEN_URL/api/tables/description/sample_customer?description=Aurelia%20Utilities%20customers" \
  -H "Authorization: Bearer $GOLDEN_ADMIN_TOKEN"

Table identifiers cannot be renamed. To use another identifier, create the new table and migrate its data and dependent configuration in dependency order. Resource renaming is a separate operation.

Read a table’s shape

curl -sS "$GOLDEN_URL/api/tables/sample_customer/metadata" \
  -H "Authorization: Bearer $GOLDEN_TOKEN"

Returns the table’s columns and its data view — the labels and layout a record is presented with. An integration that renders records should read this rather than assume the dataset’s column keys are what a person should see.

Clear or delete

PUT /api/tables/clear/{name} physically removes current records, all history, all prior audit events and pending record candidates while retaining the table. It leaves one CLEAR audit event reporting removedRecordCount, removedHistoryCount and removedAuditEventCount, even when auditing was off. Every removed identity becomes free again. A table whose name cannot support its audit relation is refused with 409 rather than partly cleared. History cannot undo a clear. DELETE /api/tables/{name} removes the table. Confirm the environment, dependencies, and approved recovery path before either operation. Verify an independent backup or reload source first; retained history is deleted by clear. See Recover tasks and deliveries for operational checks.

Golden 3.4.0 · Published 2026-10-29