On this page

Choose an integration shape based on latency, volume, and who owns recovery. Golden supports synchronous record search and single-record writes alongside resource-driven table and entity operations.

Architects comparing web, synchronous, batch, delivery, and hybrid designs should first use Choose an enterprise integration approach.

Use this page to choose behavior and recovery strategy. Use the Golden API reference for exact record operations, the Table API for bulk work, and the schema catalog for request and response models.

Choose a pattern

NeedPatternImportant constraint
Check for an existing subject during a transactionRecord-shaped searchAdds a synchronous dependency
Create or correct one entity recordSingle-record upsertRequires STEWARD or ADMIN
Process an extract or large record setConfigured table load and entity synchronizationFollow the returned task
Deliver mastered records downstreamConfigured destinationDesign the receiver for safe redelivery

Search before creating a source record

The search body is a record fragment shaped by the entity’s dataset. It is not a free-text query language.

import os
import requests

url = os.environ["GOLDEN_URL"]
token = os.environ["GOLDEN_TOKEN"]

response = requests.post(
    f"{url}/api/golden/sample-customer-entity/search",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "record": {"email": "ana.garcia@example.com"},
        "options": {},
        "pageNumber": 0,
        "pageSize": 10,
    },
    timeout=5,
)
response.raise_for_status()

matches = response.json()["result"]

An empty result means the submitted criteria found no matching record. It does not prove the subject is absent under every possible criterion. Decide explicitly whether your caller fails open, fails closed, or asks for review when Golden is unavailable.

Upsert one record

POST /api/golden/{entity}/upsert accepts one record per request. It does not accept a records batch.

Golden resolves the record a write addresses from its _id and the dataset identity, computed after the entity’s pipeline. The rules, the conflict body and what an update changes are in the record write reference. Use the complete read–correct–verify–restore example for Aurelia. It reads CRM-0001, keeps its business fields and _id, and sends update:true.

Choose the write mode from what a wrong outcome would cost:

ModeUse when
No flagThe key decides: Golden updates the record it names, or creates one. On a DEFAULT dataset a free usable _id creates under that identifier
update: trueCreating a second record would be less safe than failing the request
insert: trueThe record must be new; Golden refuses the request when the key already names one

Treat a 409 or 410 as a data-state decision, not a generic retry signal: the conflict body says whether to continue with a survivor, a restored record or an existing record. Keep the source identity stable. A computed identity that is missing or disagrees with a supplied _id is refused rather than silently replaced.

Use this endpoint for controlled individual writes. For volume, configure a source, transformation or pipeline as needed, and load it through the entity’s synchronization.

Follow indexing after a write

When an entity indexes writes asynchronously, query:

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

The response reports PENDING, INDEXED, or FAILED, together with the time first queued, last status change, attempt count, and an error when indexing failed. Wait for INDEXED before diagnosing a newly written record as missing from search. An ADMIN can list failed entries and retry one or all of them through the entity indexing-failure operations.

Run bulk work through configured resources

Bulk ingestion and export use saved resources and create asynchronous work. Validate the resources with representative data, start the appropriate table or entity operation, and follow its returned task identifier.

configured source → entity synchronization → searchable or resolved records
configured source → table load → a table that belongs to no entity
entity → configured destination → downstream system

An entity’s data is written through the entity: a table load into an entity’s table is refused. A synchronization applies the upsert’s identity rules and counts the rows it cannot key instead of stopping; see Entity synchronization.

Do not implement bulk upsert by assuming the single-record endpoint accepts an array. The exact load and synchronization request schemas are available in the running explorer where the deployment enables it.

Deliver mastered data

Use a supported Kafka, HTTP, JDBC, or Golden-table destination for managed delivery. A timeout can leave the sender uncertain whether a write was applied, so downstream consumers should use stable record identity and tolerate a safe repeat where their protocol allows it. A receiver must also implement the clear event that empties its mirror; the product event reference describes every payload a destination receives.

Golden does not document a generic table-query language or change-feed endpoint. Do not use undocumented SQL-like filters for polling. Use the supported table record filters from Query table data through the API or a configured destination.

Handle failures

StatusRecommended response
400Correct the request or data; do not retry unchanged
401Obtain or replace the credential, then retry once
403Stop; assign an appropriate role or change the workflow
404Recheck the environment, path, and identifier
409Read the conflict response and reconcile record state
410Treat the addressed record as no longer available
423Inspect whether the entity or resource is disabled or locked before retrying
5xxRetry only according to the operation’s write safety and your recovery policy

Next steps

Golden 3.4.0 · Published 2026-10-29