Golden API examples

Use these requests with a fresh Aurelia Utilities installation in a disposable environment. You need curl, jq, and an ADMIN or STEWARD token with access to sample-customer-entity. Task monitoring requires ADMIN.

Set the connection values

export GOLDEN_URL="https://golden.example.com"
export GOLDEN_TOKEN="<token-from-your-secret-manager>"

GOLDEN_URL does not include /api. Keep the token out of source control and shared terminal output. The following correction changes a supplied sample record; retain the original document for recovery.

Search for a record

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${GOLDEN_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{"record":{"taxId":"12345678Z"},"pageNumber":0,"pageSize":10}' \
  "${GOLDEN_URL}/api/golden/sample-customer-entity/search" \
  | jq '{count, ids: [.result[]._id]}'

The fresh sample returns CRM-0001 and CRM-DUP-0001. Search metadata describes why they matched; the result order is not an identity guarantee. An empty result means these criteria found no match. See Search records.

Upsert one record

For a correction to a known record, force an update by _id. First read the record and save only its writable business fields and identifier:

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${GOLDEN_TOKEN}" \
  "${GOLDEN_URL}/api/tables/sample_customer/records/CRM-0001" \
  | jq '.record | with_entries(select(
      (.key == "_id") or
      ((.key | startswith("_") | not) and .key != "qualityState" and .key != "id")
    ))' > original-record.json

jq '{update:true, record:(. + {phone:"+34611000000"}),
     comment:"Correct phone normalization"}' original-record.json > correction.json

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${GOLDEN_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-binary @correction.json \
  "${GOLDEN_URL}/api/golden/sample-customer-entity/upsert" \
  | jq '{inserted, updated, recordId:.record._id}'

Expect inserted:false, updated:true, and recordId:"CRM-0001". Aurelia uses _id; it has no sourceRef identity column. Do not copy server metadata into a write. In particular, _source may be supplied at creation, but is refused on update; Golden preserves the existing provenance itself.

This example retains all business fields rather than relying on omitted-field behavior. Do not apply a saved document over concurrent edits: re-read and reconcile changes first. Default upsert searches for a match and can update the first result. Use an explicit write mode when that ambiguity is unacceptable.

For a new independent record, insert:true forces creation and Golden assigns its identifier. Capture record._id from the response; do not assume a supplied identifier will become the new record’s ID. Never retry an insert blindly after a lost response. See Integration patterns.

Follow asynchronous indexing

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${GOLDEN_TOKEN}" \
  "${GOLDEN_URL}/api/golden/sample-customer-entity/records/CRM-0001/index-status"

Wait for INDEXED before checking search results. Inspect error if indexing reaches FAILED; PENDING means indexing has not completed.

Verify the persisted correction:

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${GOLDEN_TOKEN}" \
  "${GOLDEN_URL}/api/tables/sample_customer/records/CRM-0001/quality" \
  | jq '{score, storedState, errorCount, warningCount}'

In the fresh sample the corrected record scores 100, with CURRENT stored quality and no errors or warnings. The original phone scores 93.

Save the table quality after a correction

An administrator can request an on-demand measurement after verifying the persisted correction. Wait for the returned run to finish, then select the new picture in Quality. An older picture remains a record of its own measurement time; saving a corrected record does not rewrite it.

Restore the sample record

In this isolated exercise, restore the saved business values:

jq '{update:true, record:., comment:"Restore sample after exercise"}' \
  original-record.json > restoration.json
curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${GOLDEN_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-binary @restoration.json \
  "${GOLDEN_URL}/api/golden/sample-customer-entity/upsert"

Re-read quality and confirm 93. Restoration is another recorded change; it does not erase the exercise’s audit events. Remove the local JSON files when finished. Reset the sample only when all its current data and configuration are disposable.

Follow a task

Background operations return a run or a run identifier. Sample installation returns run.id. Set RUN_ID from that response, then use an administrator token:

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${GOLDEN_TOKEN}" \
  "${GOLDEN_URL}/api/jobs/runs/${RUN_ID}"

The response is the run itself. Follow it until SUCCEEDED, FAILED, CANCELLED, or SKIPPED, then verify the data outcome. progress uses a 0–1 scale. See Tasks and schedules.

Handle an error

Read the HTTP status and response body together. Treat message text as human guidance, not a stable machine value. Capture the X-Trace-Id response header when present, and remove credentials and record values before sharing evidence. The API conventions explain common statuses and retries.