DEVELOPER GUIDEREFERENCE CONTRACT

Search API

Search derived read models without treating search indexes as authoritative records.

CONTRACT PRINCIPLES

The protocol carries business semantics.

Each integration must preserve authority, policy, evidence and recovery context.

Pin API/schema/profile versions in test evidence.

Carry a correlation ID across request, event, connector and evidence records.

Protect material write operations from accidental replay.

Never infer legal authority solely from transport success.

REFERENCE ENDPOINTS

The downloadable contract contains request/response models, OAuth scopes, idempotency and representative errors.

Reference API surface
Area	Reference route	Semantics
Resolver	GET /v1/resolve/{identifier}	Official ID → TTID resolution with authority context
DPP	GET /v1/dpp/{identifier}	Policy-qualified DPP read
Claims	POST /v1/claims	Evidence-backed claim submission
Evidence	POST /v1/evidence	Evidence/provenance reference
Mandate	POST /v1/mandates	Delegation lifecycle
Lifecycle	POST /v1/things/{thingId}/transitions	Material transition
Search	GET /v1/search	Derived read model
Connector	POST /v1/connectors/{id}/reconcile	Business reconciliation

GET/v1/search

Search a derived read model without treating the search index as a system of record.

OAuth: thing.read
State: Search query and disclosure context are supplied. → Derived results are returned and can be resolved back to authoritative/source-aware records.
Evidence: Search access may be audited by deployment policy.
Errors: 400 invalid query · 403 disclosure denied · 503 index unavailable
Retry: Safe read retry.

{"q":"battery model X"}

{"results":[{"thingId":"ttid:thing:01...","officialIdentifier":"...","source":"derived-index"}],"authoritative":false}

ARCHITECTURE WORKSHOP

Align product-group applicability, authority boundaries, portal journeys, integration contracts and evidence before committing to production claims.