On this page
Golden API conventions
Apply Golden API conventions for URLs, authentication, JSON, errors, pagination, conflicts, and asynchronous work.
Use these conventions in every Golden integration. Consult the generated API reference for operation-specific parameters, bodies, responses, and schemas, and confirm the documented role requirements.
Base URL
API operations use the /api prefix:
https://<golden-host>/api
Keep the host and token configurable. Do not construct URLs with unescaped record, entity, table, or resource identifiers.
Authentication
Send the assigned credential as a bearer token:
Authorization: Bearer <token>
Use the least-privileged role. A token that can read an entity should not be assumed to have permission to configure, synchronize, merge, or delete it.
JSON requests and responses
Send Content-Type: application/json when an operation accepts a JSON body,
and request application/json responses. Successful response objects can
include informational messages. Error response objects can include an
errors array.
Clients should tolerate additional response properties so a compatible server can add information without breaking readers.
Status codes
| Code | Integration behavior |
|---|---|
200 | Read the operation-specific response and any informational messages |
201 | A run or resource was created; retain the returned identifier |
202 | The request was accepted; follow the operation to completion |
204 | The operation succeeded without a response body |
400 | Correct request shape, field values, or validation failures |
401 | Obtain or replace the credential; do not retry unchanged credentials indefinitely |
403 | Stop and request the required authorization |
404 | Verify the identifier, entity context, and supported path |
409 | Read the structured conflict response before deciding whether another request is safe |
410 | Treat the requested record or state as no longer available |
423 | The entity or resource is disabled or locked; inspect its state before retrying |
Do not parse human-readable error text as a stable machine contract when the operation provides structured fields.
When an upsert addresses a record that has already been merged, the 409
response includes survivorId. Continue with that surviving identifier rather
than retrying the obsolete one.
Correlate a request
Golden returns X-Trace-Id on every response. Send your own value to connect a
Golden request with your logs, or record the value Golden generates. A 500
response deliberately relies on this identifier instead of exposing diagnostic
detail; include it when contacting support.
Message language
Validation and error messages are English by default and Spanish when
Accept-Language requests Spanish. Never parse message text as a machine
contract because both language and wording can vary.
Pagination
Pagination placement and field names are operation-specific. Some operations
use query parameters; record search carries page values in its JSON body. Use
the documented operation or running explorer rather than applying one generic
pagination shape to every endpoint. Golden record APIs commonly use
pageNumber and pageSize; duplicate-cluster lists use page and pageSize.
Job-run queries use page and size, and return
a content array. Audit timelines use an opaque cursor.
Client-visible limits
Apply limits documented by the individual operation or resource. For example,
record search has a default five-second processing duration, while file-list
pagination has its own defaults. Record searches and the paged Golden data queries that declare this limit
accept page sizes from 1 to 1000; larger values return 400. Other operations
have their own pagination contracts. The public API contract does not publish
a global rate limit or payload-size limit.
Do not interpret an absent number as unlimited capacity. Plan-specific service limits and load-test coordination belong to the agreed Trazadera customer channel. See the Golden SaaS service model.
Writes and retries
Do not assume a failed connection means a write had no effect. A request can reach Golden before the client loses the response. Retry a write only when the operation’s idempotency and conflict behavior make the retry safe.
Asynchronous work
An accepted entity, table, or data-flow request may create a task. Follow its identifier until a terminal state rather than treating the initial response as completion. See Resources and tasks.
Contract discovery
Golden provides an OpenAPI contract for its API. Where enabled, Swagger UI presents that live contract. The documentation site publishes a curated customer projection of the published contract as the complete API reference and provides that curated OpenAPI JSON for tooling.
Match the contract version to the Golden release you target before generating a client. See Explore the Golden API and the supported integration policy.