Table reference

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"

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.

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, history, and pending record candidates while retaining the table. History cannot undo it. 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.

Related reading

• Configure datasets
• Query table data through the API
• Create a Golden entity