On this page
Golden API examples
Use concrete Golden API request and response examples for search, controlled writes, indexing, tasks, and errors.
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 update 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 change 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:"+34612345678"}),
comment:"Test a phone update"}' 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’s customer dataset uses DEFAULT identity; its sources use _id as
their provenance key. Do not copy server metadata into a write. Golden
preserves existing provenance, and an update may add a new _source entry
subject to the dataset’s lineage rules.
This example retains all business fields. An update changes only the members
the body carries, and a member sent as null is emptied. Do not apply a saved
document over concurrent edits: re-read and reconcile changes first.
update:true makes the request fail rather than create a record when the
_id names none.
To create an independent record, send insert:true. On Aurelia’s identity the
new record is created under the _id you send when it is free, and the request
is refused when that _id already names a record or one in history. Capture
record._id from the response and read messages. Never retry an insert
blindly after a lost response: search for the record first. The
record write reference lists every
answer.
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 update and inspect its quality:
curl --fail-with-body --silent --show-error \
--header "Authorization: Bearer ${GOLDEN_TOKEN}" \
"${GOLDEN_URL}/api/tables/sample_customer/records/CRM-0001" \
| jq '.record.phone'
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}'
Confirm that the record now holds +34612345678. The installed cleaning pipeline
has already normalized the original source phone to +34611000000, so
changing its spelling alone would not test a real update. Compare the current
quality explanation with the stored state instead of assuming a score.
Save the table quality after an update
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 the record and confirm its original phone +34611000000 and current
quality state. 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.